|
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 |