/Doc/distutils/introduction.rst

  1.. _distutils-intro:
  2
  3****************************
  4An Introduction to Distutils
  5****************************
  6
  7This document covers using the Distutils to distribute your Python modules,
  8concentrating on the role of developer/distributor: if you're looking for
  9information on installing Python modules, you should refer to the
 10:ref:`install-index` chapter.
 11
 12
 13.. _distutils-concepts:
 14
 15Concepts & Terminology
 16======================
 17
 18Using the Distutils is quite simple, both for module developers and for
 19users/administrators installing third-party modules.  As a developer, your
 20responsibilities (apart from writing solid, well-documented and well-tested
 21code, of course!) are:
 22
 23* write a setup script (:file:`setup.py` by convention)
 24
 25* (optional) write a setup configuration file
 26
 27* create a source distribution
 28
 29* (optional) create one or more built (binary) distributions
 30
 31Each of these tasks is covered in this document.
 32
 33Not all module developers have access to a multitude of platforms, so it's not
 34always feasible to expect them to create a multitude of built distributions.  It
 35is hoped that a class of intermediaries, called *packagers*, will arise to
 36address this need.  Packagers will take source distributions released by module
 37developers, build them on one or more platforms, and release the resulting built
 38distributions.  Thus, users on the most popular platforms will be able to
 39install most popular Python module distributions in the most natural way for
 40their platform, without having to run a single setup script or compile a line of
 41code.
 42
 43
 44.. _distutils-simple-example:
 45
 46A Simple Example
 47================
 48
 49The setup script is usually quite simple, although since it's written in Python,
 50there are no arbitrary limits to what you can do with it, though you should be
 51careful about putting arbitrarily expensive operations in your setup script.
 52Unlike, say, Autoconf-style configure scripts, the setup script may be run
 53multiple times in the course of building and installing your module
 54distribution.
 55
 56If all you want to do is distribute a module called :mod:`foo`, contained in a
 57file :file:`foo.py`, then your setup script can be as simple as this::
 58
 59   from distutils.core import setup
 60   setup(name='foo',
 61         version='1.0',
 62         py_modules=['foo'],
 63         )
 64
 65Some observations:
 66
 67* most information that you supply to the Distutils is supplied as keyword
 68  arguments to the :func:`setup` function
 69
 70* those keyword arguments fall into two categories: package metadata (name,
 71  version number) and information about what's in the package (a list of pure
 72  Python modules, in this case)
 73
 74* modules are specified by module name, not filename (the same will hold true
 75  for packages and extensions)
 76
 77* it's recommended that you supply a little more metadata, in particular your
 78  name, email address and a URL for the project (see section :ref:`setup-script`
 79  for an example)
 80
 81To create a source distribution for this module, you would create a setup
 82script, :file:`setup.py`, containing the above code, and run::
 83
 84   python setup.py sdist
 85
 86which will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
 87containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
 88The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
 89will unpack into a directory :file:`foo-1.0`.
 90
 91If an end-user wishes to install your :mod:`foo` module, all she has to do is
 92download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
 93:file:`foo-1.0` directory---run ::
 94
 95   python setup.py install
 96
 97which will ultimately copy :file:`foo.py` to the appropriate directory for
 98third-party modules in their Python installation.
 99
100This simple example demonstrates some fundamental concepts of the Distutils.
101First, both developers and installers have the same basic user interface, i.e.
102the setup script.  The difference is which Distutils *commands* they use: the
103:command:`sdist` command is almost exclusively for module developers, while
104:command:`install` is more often for installers (although most developers will
105want to install their own code occasionally).
106
107If you want to make things really easy for your users, you can create one or
108more built distributions for them.  For instance, if you are running on a
109Windows machine, and want to make things easy for other Windows users, you can
110create an executable installer (the most appropriate type of built distribution
111for this platform) with the :command:`bdist_wininst` command.  For example::
112
113   python setup.py bdist_wininst
114
115will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
116directory.
117
118Other useful built distribution formats are RPM, implemented by the
119:command:`bdist_rpm` command, Solaris :program:`pkgtool`
120(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
121(:command:`bdist_sdux`).  For example, the following command will create an RPM
122file called :file:`foo-1.0.noarch.rpm`::
123
124   python setup.py bdist_rpm
125
126(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
127this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
128Mandrake Linux.)
129
130You can find out what distribution formats are available at any time by running
131::
132
133   python setup.py bdist --help-formats
134
135
136.. _python-terms:
137
138General Python terminology
139==========================
140
141If you're reading this document, you probably have a good idea of what modules,
142extensions, and so forth are.  Nevertheless, just to be sure that everyone is
143operating from a common starting point, we offer the following glossary of
144common Python terms:
145
146module
147   the basic unit of code reusability in Python: a block of code imported by some
148   other code.  Three types of modules concern us here: pure Python modules,
149   extension modules, and packages.
150
151pure Python module
152   a module written in Python and contained in a single :file:`.py` file (and
153   possibly associated :file:`.pyc` and/or :file:`.pyo` files).  Sometimes referred
154   to as a "pure module."
155
156extension module
157   a module written in the low-level language of the Python implementation: C/C++
158   for Python, Java for Jython. Typically contained in a single dynamically
159   loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
160   extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
161   extensions on Windows, or a Java class file for Jython extensions.  (Note that
162   currently, the Distutils only handles C/C++ extensions for Python.)
163
164package
165   a module that contains other modules; typically contained in a directory in the
166   filesystem and distinguished from other directories by the presence of a file
167   :file:`__init__.py`.
168
169root package
170   the root of the hierarchy of packages.  (This isn't really a package, since it
171   doesn't have an :file:`__init__.py` file.  But we have to call it something.)
172   The vast majority of the standard library is in the root package, as are many
173   small, standalone third-party modules that don't belong to a larger module
174   collection. Unlike regular packages, modules in the root package can be found in
175   many directories: in fact, every directory listed in ``sys.path`` contributes
176   modules to the root package.
177
178
179.. _distutils-term:
180
181Distutils-specific terminology
182==============================
183
184The following terms apply more specifically to the domain of distributing Python
185modules using the Distutils:
186
187module distribution
188   a collection of Python modules distributed together as a single downloadable
189   resource and meant to be installed *en masse*.  Examples of some well-known
190   module distributions are Numeric Python, PyXML, PIL (the Python Imaging
191   Library), or mxBase.  (This would be called a *package*, except that term is
192   already taken in the Python context: a single module distribution may contain
193   zero, one, or many Python packages.)
194
195pure module distribution
196   a module distribution that contains only pure Python modules and packages.
197   Sometimes referred to as a "pure distribution."
198
199non-pure module distribution
200   a module distribution that contains at least one extension module.  Sometimes
201   referred to as a "non-pure distribution."
202
203distribution root
204   the top-level directory of your source tree (or  source distribution); the
205   directory where :file:`setup.py` exists.  Generally  :file:`setup.py` will be
206   run from this directory.
207
208