Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Éric Araujo | b805c47 | 2011-06-08 01:11:36 +0200 | [diff] [blame] | 82 | script, :file:`setup.py`, containing the above code, and run this command from a |
| 83 | terminal:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | python setup.py sdist |
| 86 | |
Éric Araujo | e197df0 | 2011-08-19 02:30:15 +0200 | [diff] [blame] | 87 | For Windows, open a command prompt window (:menuselection:`Start --> |
| 88 | Accessories`) and change the command to:: |
Éric Araujo | b805c47 | 2011-06-08 01:11:36 +0200 | [diff] [blame] | 89 | |
| 90 | setup.py sdist |
| 91 | |
| 92 | :command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | containing your setup script :file:`setup.py`, and your module :file:`foo.py`. |
| 94 | The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and |
| 95 | will unpack into a directory :file:`foo-1.0`. |
| 96 | |
| 97 | If an end-user wishes to install your :mod:`foo` module, all she has to do is |
| 98 | download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the |
| 99 | :file:`foo-1.0` directory---run :: |
| 100 | |
| 101 | python setup.py install |
| 102 | |
| 103 | which will ultimately copy :file:`foo.py` to the appropriate directory for |
| 104 | third-party modules in their Python installation. |
| 105 | |
| 106 | This simple example demonstrates some fundamental concepts of the Distutils. |
| 107 | First, both developers and installers have the same basic user interface, i.e. |
| 108 | the setup script. The difference is which Distutils *commands* they use: the |
| 109 | :command:`sdist` command is almost exclusively for module developers, while |
| 110 | :command:`install` is more often for installers (although most developers will |
| 111 | want to install their own code occasionally). |
| 112 | |
| 113 | If you want to make things really easy for your users, you can create one or |
| 114 | more built distributions for them. For instance, if you are running on a |
| 115 | Windows machine, and want to make things easy for other Windows users, you can |
| 116 | create an executable installer (the most appropriate type of built distribution |
| 117 | for this platform) with the :command:`bdist_wininst` command. For example:: |
| 118 | |
| 119 | python setup.py bdist_wininst |
| 120 | |
| 121 | will create an executable installer, :file:`foo-1.0.win32.exe`, in the current |
| 122 | directory. |
| 123 | |
| 124 | Other useful built distribution formats are RPM, implemented by the |
| 125 | :command:`bdist_rpm` command, Solaris :program:`pkgtool` |
| 126 | (:command:`bdist_pkgtool`), and HP-UX :program:`swinstall` |
| 127 | (:command:`bdist_sdux`). For example, the following command will create an RPM |
| 128 | file called :file:`foo-1.0.noarch.rpm`:: |
| 129 | |
| 130 | python setup.py bdist_rpm |
| 131 | |
| 132 | (The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore |
| 133 | this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or |
| 134 | Mandrake Linux.) |
| 135 | |
| 136 | You can find out what distribution formats are available at any time by running |
| 137 | :: |
| 138 | |
| 139 | python setup.py bdist --help-formats |
| 140 | |
| 141 | |
| 142 | .. _python-terms: |
| 143 | |
| 144 | General Python terminology |
| 145 | ========================== |
| 146 | |
| 147 | If you're reading this document, you probably have a good idea of what modules, |
| 148 | extensions, and so forth are. Nevertheless, just to be sure that everyone is |
| 149 | operating from a common starting point, we offer the following glossary of |
| 150 | common Python terms: |
| 151 | |
| 152 | module |
| 153 | the basic unit of code reusability in Python: a block of code imported by some |
| 154 | other code. Three types of modules concern us here: pure Python modules, |
| 155 | extension modules, and packages. |
| 156 | |
| 157 | pure Python module |
| 158 | a module written in Python and contained in a single :file:`.py` file (and |
| 159 | possibly associated :file:`.pyc` and/or :file:`.pyo` files). Sometimes referred |
| 160 | to as a "pure module." |
| 161 | |
| 162 | extension module |
| 163 | a module written in the low-level language of the Python implementation: C/C++ |
| 164 | for Python, Java for Jython. Typically contained in a single dynamically |
| 165 | loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python |
| 166 | extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python |
| 167 | extensions on Windows, or a Java class file for Jython extensions. (Note that |
| 168 | currently, the Distutils only handles C/C++ extensions for Python.) |
| 169 | |
| 170 | package |
| 171 | a module that contains other modules; typically contained in a directory in the |
| 172 | filesystem and distinguished from other directories by the presence of a file |
| 173 | :file:`__init__.py`. |
| 174 | |
| 175 | root package |
| 176 | the root of the hierarchy of packages. (This isn't really a package, since it |
| 177 | doesn't have an :file:`__init__.py` file. But we have to call it something.) |
| 178 | The vast majority of the standard library is in the root package, as are many |
| 179 | small, standalone third-party modules that don't belong to a larger module |
| 180 | collection. Unlike regular packages, modules in the root package can be found in |
| 181 | many directories: in fact, every directory listed in ``sys.path`` contributes |
| 182 | modules to the root package. |
| 183 | |
| 184 | |
| 185 | .. _distutils-term: |
| 186 | |
| 187 | Distutils-specific terminology |
| 188 | ============================== |
| 189 | |
| 190 | The following terms apply more specifically to the domain of distributing Python |
| 191 | modules using the Distutils: |
| 192 | |
| 193 | module distribution |
| 194 | a collection of Python modules distributed together as a single downloadable |
| 195 | resource and meant to be installed *en masse*. Examples of some well-known |
Martin v. Löwis | 2f48d89 | 2011-05-09 08:05:43 +0200 | [diff] [blame] | 196 | module distributions are NumPy, SciPy, PIL (the Python Imaging |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 197 | Library), or mxBase. (This would be called a *package*, except that term is |
| 198 | already taken in the Python context: a single module distribution may contain |
| 199 | zero, one, or many Python packages.) |
| 200 | |
| 201 | pure module distribution |
| 202 | a module distribution that contains only pure Python modules and packages. |
| 203 | Sometimes referred to as a "pure distribution." |
| 204 | |
| 205 | non-pure module distribution |
| 206 | a module distribution that contains at least one extension module. Sometimes |
| 207 | referred to as a "non-pure distribution." |
| 208 | |
| 209 | distribution root |
| 210 | the top-level directory of your source tree (or source distribution); the |
| 211 | directory where :file:`setup.py` exists. Generally :file:`setup.py` will be |
| 212 | run from this directory. |
| 213 | |
| 214 | |