Doc/distutils/introduction.rst

   1 .. _distutils-intro:
   2
   3 ****************************
   4 An Introduction to Distutils
   5 ****************************
   6
   7 This document covers using the Distutils to distribute your Python modules,
   8 concentrating on the role of developer/distributor: if you're looking for
   9 information on installing Python modules, you should refer to the
  10 :ref:`install-index` chapter.
  11
  12
  13 .. _distutils-concepts:
  14
  15 Concepts & Terminology
  16 ======================
  17
  18 Using the Distutils is quite simple, both for module developers and for
  19 users/administrators installing third-party modules.  As a developer, your
  20 responsibilities (apart from writing solid, well-documented and well-tested
  21 code, 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
  31 Each of these tasks is covered in this document.
  32
  33 Not all module developers have access to a multitude of platforms, so it's not
  34 always feasible to expect them to create a multitude of built distributions.  It
  35 is hoped that a class of intermediaries, called *packagers*, will arise to
  36 address this need.  Packagers will take source distributions released by module
  37 developers, build them on one or more platforms, and release the resulting built
  38 distributions.  Thus, users on the most popular platforms will be able to
  39 install most popular Python module distributions in the most natural way for
  40 their platform, without having to run a single setup script or compile a line of
  41 code.
  42
  43
  44 .. _distutils-simple-example:
  45
  46 A Simple Example
  47 ================
  48
  49 The setup script is usually quite simple, although since it's written in Python,
  50 there are no arbitrary limits to what you can do with it, though you should be
  51 careful about putting arbitrarily expensive operations in your setup script.
  52 Unlike, say, Autoconf-style configure scripts, the setup script may be run
  53 multiple times in the course of building and installing your module
  54 distribution.
  55
  56 If all you want to do is distribute a module called :mod:`foo`, contained in a
  57 file :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
  65 Some 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
  81 To create a source distribution for this module, you would create a setup
  82 script, :file:`setup.py`, containing the above code, and run::
  83
  84    python setup.py sdist
  85
  86 which will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
  87 containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
  88 The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
  89 will unpack into a directory :file:`foo-1.0`.
  90
  91 If an end-user wishes to install your :mod:`foo` module, all she has to do is
  92 download :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
  97 which will ultimately copy :file:`foo.py` to the appropriate directory for
  98 third-party modules in their Python installation.
  99
 100 This simple example demonstrates some fundamental concepts of the Distutils.
 101 First, both developers and installers have the same basic user interface, i.e.
 102 the 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
 105 want to install their own code occasionally).
 106
 107 If you want to make things really easy for your users, you can create one or
 108 more built distributions for them.  For instance, if you are running on a
 109 Windows machine, and want to make things easy for other Windows users, you can
 110 create an executable installer (the most appropriate type of built distribution
 111 for this platform) with the :command:`bdist_wininst` command.  For example::
 112
 113    python setup.py bdist_wininst
 114
 115 will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
 116 directory.
 117
 118 Other 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
 122 file 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
 127 this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
 128 Mandrake Linux.)
 129
 130 You 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
 138 General Python terminology
 139 ==========================
 140
 141 If you're reading this document, you probably have a good idea of what modules,
 142 extensions, and so forth are.  Nevertheless, just to be sure that everyone is
 143 operating from a common starting point, we offer the following glossary of
 144 common Python terms:
 145
 146 module
 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
 151 pure 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
 156 extension 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
 164 package
 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
 169 root 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
 181 Distutils-specific terminology
 182 ==============================
 183
 184 The following terms apply more specifically to the domain of distributing Python
 185 modules using the Distutils:
 186
 187 module 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
 195 pure module distribution
 196    a module distribution that contains only pure Python modules and packages.
 197    Sometimes referred to as a "pure distribution."
 198
 199 non-pure module distribution
 200    a module distribution that contains at least one extension module.  Sometimes
 201    referred to as a "non-pure distribution."
 202
 203 distribution 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