|
1 .. _built-dist: |
|
2 |
|
3 **************************** |
|
4 Creating Built Distributions |
|
5 **************************** |
|
6 |
|
7 A "built distribution" is what you're probably used to thinking of either as a |
|
8 "binary package" or an "installer" (depending on your background). It's not |
|
9 necessarily binary, though, because it might contain only Python source code |
|
10 and/or byte-code; and we don't call it a package, because that word is already |
|
11 spoken for in Python. (And "installer" is a term specific to the world of |
|
12 mainstream desktop systems.) |
|
13 |
|
14 A built distribution is how you make life as easy as possible for installers of |
|
15 your module distribution: for users of RPM-based Linux systems, it's a binary |
|
16 RPM; for Windows users, it's an executable installer; for Debian-based Linux |
|
17 users, it's a Debian package; and so forth. Obviously, no one person will be |
|
18 able to create built distributions for every platform under the sun, so the |
|
19 Distutils are designed to enable module developers to concentrate on their |
|
20 specialty---writing code and creating source distributions---while an |
|
21 intermediary species called *packagers* springs up to turn source distributions |
|
22 into built distributions for as many platforms as there are packagers. |
|
23 |
|
24 Of course, the module developer could be his own packager; or the packager could |
|
25 be a volunteer "out there" somewhere who has access to a platform which the |
|
26 original developer does not; or it could be software periodically grabbing new |
|
27 source distributions and turning them into built distributions for as many |
|
28 platforms as the software has access to. Regardless of who they are, a packager |
|
29 uses the setup script and the :command:`bdist` command family to generate built |
|
30 distributions. |
|
31 |
|
32 As a simple example, if I run the following command in the Distutils source |
|
33 tree:: |
|
34 |
|
35 python setup.py bdist |
|
36 |
|
37 then the Distutils builds my module distribution (the Distutils itself in this |
|
38 case), does a "fake" installation (also in the :file:`build` directory), and |
|
39 creates the default type of built distribution for my platform. The default |
|
40 format for built distributions is a "dumb" tar file on Unix, and a simple |
|
41 executable installer on Windows. (That tar file is considered "dumb" because it |
|
42 has to be unpacked in a specific location to work.) |
|
43 |
|
44 Thus, the above command on a Unix system creates |
|
45 :file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place |
|
46 installs the Distutils just as though you had downloaded the source distribution |
|
47 and run ``python setup.py install``. (The "right place" is either the root of |
|
48 the filesystem or Python's :file:`{prefix}` directory, depending on the options |
|
49 given to the :command:`bdist_dumb` command; the default is to make dumb |
|
50 distributions relative to :file:`{prefix}`.) |
|
51 |
|
52 Obviously, for pure Python distributions, this isn't any simpler than just |
|
53 running ``python setup.py install``\ ---but for non-pure distributions, which |
|
54 include extensions that would need to be compiled, it can mean the difference |
|
55 between someone being able to use your extensions or not. And creating "smart" |
|
56 built distributions, such as an RPM package or an executable installer for |
|
57 Windows, is far more convenient for users even if your distribution doesn't |
|
58 include any extensions. |
|
59 |
|
60 The :command:`bdist` command has a :option:`--formats` option, similar to the |
|
61 :command:`sdist` command, which you can use to select the types of built |
|
62 distribution to generate: for example, :: |
|
63 |
|
64 python setup.py bdist --format=zip |
|
65 |
|
66 would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip`\ |
|
67 ---again, this archive would be unpacked from the root directory to install the |
|
68 Distutils. |
|
69 |
|
70 The available formats for built distributions are: |
|
71 |
|
72 +-------------+------------------------------+---------+ |
|
73 | Format | Description | Notes | |
|
74 +=============+==============================+=========+ |
|
75 | ``gztar`` | gzipped tar file | (1),(3) | |
|
76 | | (:file:`.tar.gz`) | | |
|
77 +-------------+------------------------------+---------+ |
|
78 | ``ztar`` | compressed tar file | \(3) | |
|
79 | | (:file:`.tar.Z`) | | |
|
80 +-------------+------------------------------+---------+ |
|
81 | ``tar`` | tar file (:file:`.tar`) | \(3) | |
|
82 +-------------+------------------------------+---------+ |
|
83 | ``zip`` | zip file (:file:`.zip`) | \(4) | |
|
84 +-------------+------------------------------+---------+ |
|
85 | ``rpm`` | RPM | \(5) | |
|
86 +-------------+------------------------------+---------+ |
|
87 | ``pkgtool`` | Solaris :program:`pkgtool` | | |
|
88 +-------------+------------------------------+---------+ |
|
89 | ``sdux`` | HP-UX :program:`swinstall` | | |
|
90 +-------------+------------------------------+---------+ |
|
91 | ``rpm`` | RPM | \(5) | |
|
92 +-------------+------------------------------+---------+ |
|
93 | ``wininst`` | self-extracting ZIP file for | (2),(4) | |
|
94 | | Windows | | |
|
95 +-------------+------------------------------+---------+ |
|
96 |
|
97 Notes: |
|
98 |
|
99 (1) |
|
100 default on Unix |
|
101 |
|
102 (2) |
|
103 default on Windows |
|
104 |
|
105 **\*\*** to-do! **\*\*** |
|
106 |
|
107 (3) |
|
108 requires external utilities: :program:`tar` and possibly one of :program:`gzip`, |
|
109 :program:`bzip2`, or :program:`compress` |
|
110 |
|
111 (4) |
|
112 requires either external :program:`zip` utility or :mod:`zipfile` module (part |
|
113 of the standard Python library since Python 1.6) |
|
114 |
|
115 (5) |
|
116 requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm |
|
117 --version`` to find out which version you have) |
|
118 |
|
119 You don't have to use the :command:`bdist` command with the :option:`--formats` |
|
120 option; you can also use the command that directly implements the format you're |
|
121 interested in. Some of these :command:`bdist` "sub-commands" actually generate |
|
122 several similar formats; for instance, the :command:`bdist_dumb` command |
|
123 generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and |
|
124 ``zip``), and :command:`bdist_rpm` generates both binary and source RPMs. The |
|
125 :command:`bdist` sub-commands, and the formats generated by each, are: |
|
126 |
|
127 +--------------------------+-----------------------+ |
|
128 | Command | Formats | |
|
129 +==========================+=======================+ |
|
130 | :command:`bdist_dumb` | tar, ztar, gztar, zip | |
|
131 +--------------------------+-----------------------+ |
|
132 | :command:`bdist_rpm` | rpm, srpm | |
|
133 +--------------------------+-----------------------+ |
|
134 | :command:`bdist_wininst` | wininst | |
|
135 +--------------------------+-----------------------+ |
|
136 |
|
137 The following sections give details on the individual :command:`bdist_\*` |
|
138 commands. |
|
139 |
|
140 |
|
141 .. _creating-dumb: |
|
142 |
|
143 Creating dumb built distributions |
|
144 ================================= |
|
145 |
|
146 **\*\*** Need to document absolute vs. prefix-relative packages here, but first |
|
147 I have to implement it! **\*\*** |
|
148 |
|
149 |
|
150 .. _creating-rpms: |
|
151 |
|
152 Creating RPM packages |
|
153 ===================== |
|
154 |
|
155 The RPM format is used by many popular Linux distributions, including Red Hat, |
|
156 SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux |
|
157 distributions) is your usual environment, creating RPM packages for other users |
|
158 of that same distribution is trivial. Depending on the complexity of your module |
|
159 distribution and differences between Linux distributions, you may also be able |
|
160 to create RPMs that work on different RPM-based distributions. |
|
161 |
|
162 The usual way to create an RPM of your module distribution is to run the |
|
163 :command:`bdist_rpm` command:: |
|
164 |
|
165 python setup.py bdist_rpm |
|
166 |
|
167 or the :command:`bdist` command with the :option:`--format` option:: |
|
168 |
|
169 python setup.py bdist --formats=rpm |
|
170 |
|
171 The former allows you to specify RPM-specific options; the latter allows you to |
|
172 easily specify multiple formats in one run. If you need to do both, you can |
|
173 explicitly specify multiple :command:`bdist_\*` commands and their options:: |
|
174 |
|
175 python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \ |
|
176 bdist_wininst --target_version="2.0" |
|
177 |
|
178 Creating RPM packages is driven by a :file:`.spec` file, much as using the |
|
179 Distutils is driven by the setup script. To make your life easier, the |
|
180 :command:`bdist_rpm` command normally creates a :file:`.spec` file based on the |
|
181 information you supply in the setup script, on the command line, and in any |
|
182 Distutils configuration files. Various options and sections in the |
|
183 :file:`.spec` file are derived from options in the setup script as follows: |
|
184 |
|
185 +------------------------------------------+----------------------------------------------+ |
|
186 | RPM :file:`.spec` file option or section | Distutils setup script option | |
|
187 +==========================================+==============================================+ |
|
188 | Name | :option:`name` | |
|
189 +------------------------------------------+----------------------------------------------+ |
|
190 | Summary (in preamble) | :option:`description` | |
|
191 +------------------------------------------+----------------------------------------------+ |
|
192 | Version | :option:`version` | |
|
193 +------------------------------------------+----------------------------------------------+ |
|
194 | Vendor | :option:`author` and :option:`author_email`, | |
|
195 | | or --- & :option:`maintainer` and | |
|
196 | | :option:`maintainer_email` | |
|
197 +------------------------------------------+----------------------------------------------+ |
|
198 | Copyright | :option:`license` | |
|
199 +------------------------------------------+----------------------------------------------+ |
|
200 | Url | :option:`url` | |
|
201 +------------------------------------------+----------------------------------------------+ |
|
202 | %description (section) | :option:`long_description` | |
|
203 +------------------------------------------+----------------------------------------------+ |
|
204 |
|
205 Additionally, there are many options in :file:`.spec` files that don't have |
|
206 corresponding options in the setup script. Most of these are handled through |
|
207 options to the :command:`bdist_rpm` command as follows: |
|
208 |
|
209 +-------------------------------+-----------------------------+-------------------------+ |
|
210 | RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value | |
|
211 | or section | | | |
|
212 +===============================+=============================+=========================+ |
|
213 | Release | :option:`release` | "1" | |
|
214 +-------------------------------+-----------------------------+-------------------------+ |
|
215 | Group | :option:`group` | "Development/Libraries" | |
|
216 +-------------------------------+-----------------------------+-------------------------+ |
|
217 | Vendor | :option:`vendor` | (see above) | |
|
218 +-------------------------------+-----------------------------+-------------------------+ |
|
219 | Packager | :option:`packager` | (none) | |
|
220 +-------------------------------+-----------------------------+-------------------------+ |
|
221 | Provides | :option:`provides` | (none) | |
|
222 +-------------------------------+-----------------------------+-------------------------+ |
|
223 | Requires | :option:`requires` | (none) | |
|
224 +-------------------------------+-----------------------------+-------------------------+ |
|
225 | Conflicts | :option:`conflicts` | (none) | |
|
226 +-------------------------------+-----------------------------+-------------------------+ |
|
227 | Obsoletes | :option:`obsoletes` | (none) | |
|
228 +-------------------------------+-----------------------------+-------------------------+ |
|
229 | Distribution | :option:`distribution_name` | (none) | |
|
230 +-------------------------------+-----------------------------+-------------------------+ |
|
231 | BuildRequires | :option:`build_requires` | (none) | |
|
232 +-------------------------------+-----------------------------+-------------------------+ |
|
233 | Icon | :option:`icon` | (none) | |
|
234 +-------------------------------+-----------------------------+-------------------------+ |
|
235 |
|
236 Obviously, supplying even a few of these options on the command-line would be |
|
237 tedious and error-prone, so it's usually best to put them in the setup |
|
238 configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If |
|
239 you distribute or package many Python module distributions, you might want to |
|
240 put options that apply to all of them in your personal Distutils configuration |
|
241 file (:file:`~/.pydistutils.cfg`). |
|
242 |
|
243 There are three steps to building a binary RPM package, all of which are |
|
244 handled automatically by the Distutils: |
|
245 |
|
246 #. create a :file:`.spec` file, which describes the package (analogous to the |
|
247 Distutils setup script; in fact, much of the information in the setup script |
|
248 winds up in the :file:`.spec` file) |
|
249 |
|
250 #. create the source RPM |
|
251 |
|
252 #. create the "binary" RPM (which may or may not contain binary code, depending |
|
253 on whether your module distribution contains Python extensions) |
|
254 |
|
255 Normally, RPM bundles the last two steps together; when you use the Distutils, |
|
256 all three steps are typically bundled together. |
|
257 |
|
258 If you wish, you can separate these three steps. You can use the |
|
259 :option:`--spec-only` option to make :command:`bdist_rpm` just create the |
|
260 :file:`.spec` file and exit; in this case, the :file:`.spec` file will be |
|
261 written to the "distribution directory"---normally :file:`dist/`, but |
|
262 customizable with the :option:`--dist-dir` option. (Normally, the :file:`.spec` |
|
263 file winds up deep in the "build tree," in a temporary directory created by |
|
264 :command:`bdist_rpm`.) |
|
265 |
|
266 .. % \XXX{this isn't implemented yet---is it needed?!} |
|
267 .. % You can also specify a custom \file{.spec} file with the |
|
268 .. % \longprogramopt{spec-file} option; used in conjunction with |
|
269 .. % \longprogramopt{spec-only}, this gives you an opportunity to customize |
|
270 .. % the \file{.spec} file manually: |
|
271 .. % |
|
272 .. % \ begin{verbatim} |
|
273 .. % > python setup.py bdist_rpm --spec-only |
|
274 .. % # ...edit dist/FooBar-1.0.spec |
|
275 .. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec |
|
276 .. % \ end{verbatim} |
|
277 .. % |
|
278 .. % (Although a better way to do this is probably to override the standard |
|
279 .. % \command{bdist\_rpm} command with one that writes whatever else you want |
|
280 .. % to the \file{.spec} file.) |
|
281 |
|
282 |
|
283 .. _creating-wininst: |
|
284 |
|
285 Creating Windows Installers |
|
286 =========================== |
|
287 |
|
288 Executable installers are the natural format for binary distributions on |
|
289 Windows. They display a nice graphical user interface, display some information |
|
290 about the module distribution to be installed taken from the metadata in the |
|
291 setup script, let the user select a few options, and start or cancel the |
|
292 installation. |
|
293 |
|
294 Since the metadata is taken from the setup script, creating Windows installers |
|
295 is usually as easy as running:: |
|
296 |
|
297 python setup.py bdist_wininst |
|
298 |
|
299 or the :command:`bdist` command with the :option:`--formats` option:: |
|
300 |
|
301 python setup.py bdist --formats=wininst |
|
302 |
|
303 If you have a pure module distribution (only containing pure Python modules and |
|
304 packages), the resulting installer will be version independent and have a name |
|
305 like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix |
|
306 platforms or Mac OS X. |
|
307 |
|
308 If you have a non-pure distribution, the extensions can only be created on a |
|
309 Windows platform, and will be Python version dependent. The installer filename |
|
310 will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You |
|
311 have to create a separate installer for every Python version you want to |
|
312 support. |
|
313 |
|
314 The installer will try to compile pure modules into :term:`bytecode` after installation |
|
315 on the target system in normal and optimizing mode. If you don't want this to |
|
316 happen for some reason, you can run the :command:`bdist_wininst` command with |
|
317 the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` |
|
318 option. |
|
319 |
|
320 By default the installer will display the cool "Python Powered" logo when it is |
|
321 run, but you can also supply your own bitmap which must be a Windows |
|
322 :file:`.bmp` file with the :option:`--bitmap` option. |
|
323 |
|
324 The installer will also display a large title on the desktop background window |
|
325 when it is run, which is constructed from the name of your distribution and the |
|
326 version number. This can be changed to another text by using the |
|
327 :option:`--title` option. |
|
328 |
|
329 The installer file will be written to the "distribution directory" --- normally |
|
330 :file:`dist/`, but customizable with the :option:`--dist-dir` option. |
|
331 |
|
332 .. _cross-compile-windows: |
|
333 |
|
334 Cross-compiling on Windows |
|
335 ========================== |
|
336 |
|
337 Starting with Python 2.6, distutils is capable of cross-compiling between |
|
338 Windows platforms. In practice, this means that with the correct tools |
|
339 installed, you can use a 32bit version of Windows to create 64bit extensions |
|
340 and vice-versa. |
|
341 |
|
342 To build for an alternate platform, specify the :option:`--plat-name` option |
|
343 to the build command. Valid values are currently 'win32', 'win-amd64' and |
|
344 'win-ia64'. For example, on a 32bit version of Windows, you could execute:: |
|
345 |
|
346 python setup.py build --plat-name=win-amd64 |
|
347 |
|
348 to build a 64bit version of your extension. The Windows Installers also |
|
349 support this option, so the command:: |
|
350 |
|
351 python setup.py build --plat-name=win-amd64 bdist_wininst |
|
352 |
|
353 would create a 64bit installation executable on your 32bit version of Windows. |
|
354 |
|
355 To cross-compile, you must download the Python source code and cross-compile |
|
356 Python itself for the platform you are targetting - it is not possible from a |
|
357 binary installtion of Python (as the .lib etc file for other platforms are |
|
358 not included.) In practice, this means the user of a 32 bit operating |
|
359 system will need to use Visual Studio 2008 to open the |
|
360 :file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the |
|
361 "x64" configuration of the 'pythoncore' project before cross-compiling |
|
362 extensions is possible. |
|
363 |
|
364 Note that by default, Visual Studio 2008 does not install 64bit compilers or |
|
365 tools. You may need to reexecute the Visual Studio setup process and select |
|
366 these tools (using Control Panel->[Add/Remove] Programs is a convenient way to |
|
367 check or modify your existing install.) |
|
368 |
|
369 .. _postinstallation-script: |
|
370 |
|
371 The Postinstallation script |
|
372 --------------------------- |
|
373 |
|
374 Starting with Python 2.3, a postinstallation script can be specified which the |
|
375 :option:`--install-script` option. The basename of the script must be |
|
376 specified, and the script filename must also be listed in the scripts argument |
|
377 to the setup function. |
|
378 |
|
379 This script will be run at installation time on the target system after all the |
|
380 files have been copied, with ``argv[1]`` set to :option:`-install`, and again at |
|
381 uninstallation time before the files are removed with ``argv[1]`` set to |
|
382 :option:`-remove`. |
|
383 |
|
384 The installation script runs embedded in the windows installer, every output |
|
385 (``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be |
|
386 displayed in the GUI after the script has finished. |
|
387 |
|
388 Some functions especially useful in this context are available as additional |
|
389 built-in functions in the installation script. |
|
390 |
|
391 |
|
392 .. function:: directory_created(path) |
|
393 file_created(path) |
|
394 |
|
395 These functions should be called when a directory or file is created by the |
|
396 postinstall script at installation time. It will register *path* with the |
|
397 uninstaller, so that it will be removed when the distribution is uninstalled. |
|
398 To be safe, directories are only removed if they are empty. |
|
399 |
|
400 |
|
401 .. function:: get_special_folder_path(csidl_string) |
|
402 |
|
403 This function can be used to retrieve special folder locations on Windows like |
|
404 the Start Menu or the Desktop. It returns the full path to the folder. |
|
405 *csidl_string* must be one of the following strings:: |
|
406 |
|
407 "CSIDL_APPDATA" |
|
408 |
|
409 "CSIDL_COMMON_STARTMENU" |
|
410 "CSIDL_STARTMENU" |
|
411 |
|
412 "CSIDL_COMMON_DESKTOPDIRECTORY" |
|
413 "CSIDL_DESKTOPDIRECTORY" |
|
414 |
|
415 "CSIDL_COMMON_STARTUP" |
|
416 "CSIDL_STARTUP" |
|
417 |
|
418 "CSIDL_COMMON_PROGRAMS" |
|
419 "CSIDL_PROGRAMS" |
|
420 |
|
421 "CSIDL_FONTS" |
|
422 |
|
423 If the folder cannot be retrieved, :exc:`OSError` is raised. |
|
424 |
|
425 Which folders are available depends on the exact Windows version, and probably |
|
426 also the configuration. For details refer to Microsoft's documentation of the |
|
427 :cfunc:`SHGetSpecialFolderPath` function. |
|
428 |
|
429 Vista User Access Control (UAC) |
|
430 =============================== |
|
431 |
|
432 Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` |
|
433 option. The default is 'none' (meaning no UAC handling is done), and other |
|
434 valid values are 'auto' (meaning prompt for UAC elevation if Python was |
|
435 installed for all users) and 'force' (meaning always prompt for elevation) |
|
436 |
|
437 .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) |
|
438 |
|
439 This function creates a shortcut. *target* is the path to the program to be |
|
440 started by the shortcut. *description* is the description of the shortcut. |
|
441 *filename* is the title of the shortcut that the user will see. *arguments* |
|
442 specifies the command line arguments, if any. *workdir* is the working directory |
|
443 for the program. *iconpath* is the file containing the icon for the shortcut, |
|
444 and *iconindex* is the index of the icon in the file *iconpath*. Again, for |
|
445 details consult the Microsoft documentation for the :class:`IShellLink` |
|
446 interface. |