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