Mercurial > cpython-lru_cache-weakref

annotate Doc/packaging/setupscript.rst @ 70817:dd775b1561ba

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix markup.
author Georg Brandl <georg@python.org>
date Tue, 14 Jun 2011 21:09:55 +0200
parents 22f077f82e74
children 375c99d53058
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
70594
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
1 .. _packaging-setup-script:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
2
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
3 ************************
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
4 Writing the Setup Script
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
5 ************************
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
6
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
7 The setup script is the center of all activity in building, distributing, and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
8 installing modules using Distutils. The main purpose of the setup script is
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
9 to describe your module distribution to Distutils, so that the various
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
10 commands that operate on your modules do the right thing. As we saw in section
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
11 :ref:`packaging-simple-example`, the setup script consists mainly of a
70595
22f077f82e74 Kill trailing whitespace
Éric Araujo <merwok@netwok.org>
parents: 70594
diff changeset
12 call to :func:`setup` where the most information is supplied as
70594
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
13 keyword arguments to :func:`setup`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
14
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
15 Here's a slightly more involved example, which we'll follow for the next couple
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
16 of sections: a setup script that could be used for Packaging itself::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
17
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
18 #!/usr/bin/env python
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
19
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
20 from packaging.core import setup, find_packages
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
21
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
22 setup(name='Packaging',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
23 version='1.0',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
24 summary='Python Distribution Utilities',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
25 keywords=['packaging', 'packaging'],
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
26 author=u'Tarek Ziadé',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
27 author_email='tarek@ziade.org',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
28 home_page='http://bitbucket.org/tarek/packaging/wiki/Home',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
29 license='PSF',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
30 packages=find_packages())
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
31
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
32
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
33 There are only two differences between this and the trivial one-file
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
34 distribution presented in section :ref:`packaging-simple-example`: more
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
35 metadata and the specification of pure Python modules by package rather than
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
36 by module. This is important since Ristutils consist of a couple of dozen
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
37 modules split into (so far) two packages; an explicit list of every module
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
38 would be tedious to generate and difficult to maintain. For more information
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
39 on the additional metadata, see section :ref:`packaging-metadata`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
40
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
41 Note that any pathnames (files or directories) supplied in the setup script
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
42 should be written using the Unix convention, i.e. slash-separated. The
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
43 Distutils will take care of converting this platform-neutral representation into
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
44 whatever is appropriate on your current platform before actually using the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
45 pathname. This makes your setup script portable across operating systems, which
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
46 of course is one of the major goals of the Distutils. In this spirit, all
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
47 pathnames in this document are slash-separated.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
48
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
49 This, of course, only applies to pathnames given to Distutils functions. If
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
50 you, for example, use standard Python functions such as :func:`glob.glob` or
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
51 :func:`os.listdir` to specify files, you should be careful to write portable
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
52 code instead of hardcoding path separators::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
53
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
54 glob.glob(os.path.join('mydir', 'subdir', '*.html'))
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
55 os.listdir(os.path.join('mydir', 'subdir'))
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
56
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
57
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
58 .. _packaging-listing-packages:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
59
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
60 Listing whole packages
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
61 ======================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
62
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
63 The :option:`packages` option tells the Distutils to process (build, distribute,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
64 install, etc.) all pure Python modules found in each package mentioned in the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
65 :option:`packages` list. In order to do this, of course, there has to be a
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
66 correspondence between package names and directories in the filesystem. The
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
67 default correspondence is the most obvious one, i.e. package :mod:`packaging` is
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
68 found in the directory :file:`packaging` relative to the distribution root.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
69 Thus, when you say ``packages = ['foo']`` in your setup script, you are
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
70 promising that the Distutils will find a file :file:`foo/__init__.py` (which
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
71 might be spelled differently on your system, but you get the idea) relative to
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
72 the directory where your setup script lives. If you break this promise, the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
73 Distutils will issue a warning but still process the broken package anyways.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
74
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
75 If you use a different convention to lay out your source directory, that's no
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
76 problem: you just have to supply the :option:`package_dir` option to tell the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
77 Distutils about your convention. For example, say you keep all Python source
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
78 under :file:`lib`, so that modules in the "root package" (i.e., not in any
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
79 package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
80 :file:`lib/foo`, and so forth. Then you would put ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
81
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
82 package_dir = {'': 'lib'}
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
83
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
84 in your setup script. The keys to this dictionary are package names, and an
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
85 empty package name stands for the root package. The values are directory names
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
86 relative to your distribution root. In this case, when you say ``packages =
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
87 ['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
88
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
89 Another possible convention is to put the :mod:`foo` package right in
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
90 :file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
91 written in the setup script as ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
92
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
93 package_dir = {'foo': 'lib'}
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
94
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
95 A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
96 applies to all packages below *package*, so the :mod:`foo.bar` case is
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
97 automatically handled here. In this example, having ``packages = ['foo',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
98 'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
99 :file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir`
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
100 applies recursively, you must explicitly list all packages in
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
101 :option:`packages`: the Distutils will *not* recursively scan your source tree
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
102 looking for any directory with an :file:`__init__.py` file.)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
103
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
104
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
105 .. _packaging-listing-modules:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
106
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
107 Listing individual modules
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
108 ==========================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
109
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
110 For a small module distribution, you might prefer to list all modules rather
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
111 than listing packages---especially the case of a single module that goes in the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
112 "root package" (i.e., no package at all). This simplest case was shown in
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
113 section :ref:`packaging-simple-example`; here is a slightly more involved
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
114 example::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
115
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
116 py_modules = ['mod1', 'pkg.mod2']
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
117
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
118 This describes two modules, one of them in the "root" package, the other in the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
119 :mod:`pkg` package. Again, the default package/directory layout implies that
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
120 these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
121 that :file:`pkg/__init__.py` exists as well. And again, you can override the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
122 package/directory correspondence using the :option:`package_dir` option.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
123
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
124
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
125 .. _packaging-describing-extensions:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
126
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
127 Describing extension modules
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
128 ============================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
129
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
130 Just as writing Python extension modules is a bit more complicated than writing
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
131 pure Python modules, describing them to the Distutils is a bit more complicated.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
132 Unlike pure modules, it's not enough just to list modules or packages and expect
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
133 the Distutils to go out and find the right files; you have to specify the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
134 extension name, source file(s), and any compile/link requirements (include
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
135 directories, libraries to link with, etc.).
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
136
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
137 .. XXX read over this section
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
138
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
139 All of this is done through another keyword argument to :func:`setup`, the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
140 :option:`ext_modules` option. :option:`ext_modules` is just a list of
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
141 :class:`Extension` instances, each of which describes a single extension module.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
142 Suppose your distribution includes a single extension, called :mod:`foo` and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
143 implemented by :file:`foo.c`. If no additional instructions to the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
144 compiler/linker are needed, describing this extension is quite simple::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
145
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
146 Extension('foo', ['foo.c'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
147
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
148 The :class:`Extension` class can be imported from :mod:`packaging.core` along
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
149 with :func:`setup`. Thus, the setup script for a module distribution that
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
150 contains only this one extension and nothing else might be::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
151
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
152 from packaging.core import setup, Extension
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
153 setup(name='foo',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
154 version='1.0',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
155 ext_modules=[Extension('foo', ['foo.c'])])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
156
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
157 The :class:`Extension` class (actually, the underlying extension-building
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
158 machinery implemented by the :command:`build_ext` command) supports a great deal
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
159 of flexibility in describing Python extensions, which is explained in the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
160 following sections.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
161
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
162
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
163 Extension names and packages
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
164 ----------------------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
165
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
166 The first argument to the :class:`Extension` constructor is always the name of
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
167 the extension, including any package names. For example, ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
168
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
169 Extension('foo', ['src/foo1.c', 'src/foo2.c'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
170
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
171 describes an extension that lives in the root package, while ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
172
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
173 Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
174
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
175 describes the same extension in the :mod:`pkg` package. The source files and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
176 resulting object code are identical in both cases; the only difference is where
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
177 in the filesystem (and therefore where in Python's namespace hierarchy) the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
178 resulting extension lives.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
179
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
180 If you have a number of extensions all in the same package (or all under the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
181 same base package), use the :option:`ext_package` keyword argument to
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
182 :func:`setup`. For example, ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
183
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
184 setup(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
185 ext_package='pkg',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
186 ext_modules=[Extension('foo', ['foo.c']),
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
187 Extension('subpkg.bar', ['bar.c'])])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
188
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
189 will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
190 :mod:`pkg.subpkg.bar`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
191
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
192
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
193 Extension source files
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
194 ----------------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
195
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
196 The second argument to the :class:`Extension` constructor is a list of source
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
197 files. Since the Distutils currently only support C, C++, and Objective-C
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
198 extensions, these are normally C/C++/Objective-C source files. (Be sure to use
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
199 appropriate extensions to distinguish C++\ source files: :file:`.cc` and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
200 :file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
201
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
202 However, you can also include SWIG interface (:file:`.i`) files in the list; the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
203 :command:`build_ext` command knows how to deal with SWIG extensions: it will run
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
204 SWIG on the interface file and compile the resulting C/C++ file into your
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
205 extension.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
206
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
207 .. XXX SWIG support is rough around the edges and largely untested!
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
208
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
209 This warning notwithstanding, options to SWIG can be currently passed like
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
210 this::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
211
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
212 setup(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
213 ext_modules=[Extension('_foo', ['foo.i'],
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
214 swig_opts=['-modern', '-I../include'])],
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
215 py_modules=['foo'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
216
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
217 Or on the command line like this::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
218
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
219 > python setup.py build_ext --swig-opts="-modern -I../include"
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
220
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
221 On some platforms, you can include non-source files that are processed by the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
222 compiler and included in your extension. Currently, this just means Windows
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
223 message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
224 Visual C++. These will be compiled to binary resource (:file:`.res`) files and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
225 linked into the executable.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
226
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
227
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
228 Preprocessor options
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
229 --------------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
230
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
231 Three optional arguments to :class:`Extension` will help if you need to specify
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
232 include directories to search or preprocessor macros to define/undefine:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
233 ``include_dirs``, ``define_macros``, and ``undef_macros``.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
234
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
235 For example, if your extension requires header files in the :file:`include`
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
236 directory under your distribution root, use the ``include_dirs`` option::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
237
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
238 Extension('foo', ['foo.c'], include_dirs=['include'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
239
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
240 You can specify absolute directories there; if you know that your extension will
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
241 only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
242 away with ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
243
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
244 Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
245
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
246 You should avoid this sort of non-portable usage if you plan to distribute your
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
247 code: it's probably better to write C code like ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
248
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
249 #include <X11/Xlib.h>
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
250
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
251 If you need to include header files from some other Python extension, you can
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
252 take advantage of the fact that header files are installed in a consistent way
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
253 by the Distutils :command:`install_header` command. For example, the Numerical
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
254 Python header files are installed (on a standard Unix installation) to
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
255 :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
256 according to your platform and Python installation.) Since the Python include
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
257 directory---\ :file:`/usr/local/include/python1.5` in this case---is always
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
258 included in the search path when building Python extensions, the best approach
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
259 is to write C code like ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
260
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
261 #include <Numerical/arrayobject.h>
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
262
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
263 .. TODO check if it's d2.sysconfig or the new sysconfig module now
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
264
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
265 If you must put the :file:`Numerical` include directory right into your header
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
266 search path, though, you can find that directory using the Distutils
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
267 :mod:`packaging.sysconfig` module::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
268
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
269 from packaging.sysconfig import get_python_inc
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
270 incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
271 setup(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
272 Extension(..., include_dirs=[incdir]))
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
273
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
274 Even though this is quite portable---it will work on any Python installation,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
275 regardless of platform---it's probably easier to just write your C code in the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
276 sensible way.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
277
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
278 You can define and undefine preprocessor macros with the ``define_macros`` and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
279 ``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
280 tuples, where ``name`` is the name of the macro to define (a string) and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
281 ``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
282 to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
283 most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
284 just a list of macros to undefine.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
285
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
286 For example::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
287
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
288 Extension(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
289 define_macros=[('NDEBUG', '1'),
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
290 ('HAVE_STRFTIME', None)],
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
291 undef_macros=['HAVE_FOO', 'HAVE_BAR'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
292
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
293 is the equivalent of having this at the top of every C source file::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
294
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
295 #define NDEBUG 1
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
296 #define HAVE_STRFTIME
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
297 #undef HAVE_FOO
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
298 #undef HAVE_BAR
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
299
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
300
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
301 Library options
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
302 ---------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
303
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
304 You can also specify the libraries to link against when building your extension,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
305 and the directories to search for those libraries. The ``libraries`` option is
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
306 a list of libraries to link against, ``library_dirs`` is a list of directories
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
307 to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
308 directories to search for shared (dynamically loaded) libraries at run-time.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
309
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
310 For example, if you need to link against libraries known to be in the standard
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
311 library search path on target systems ::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
312
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
313 Extension(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
314 libraries=['gdbm', 'readline'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
315
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
316 If you need to link with libraries in a non-standard location, you'll have to
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
317 include the location in ``library_dirs``::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
318
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
319 Extension(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
320 library_dirs=['/usr/X11R6/lib'],
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
321 libraries=['X11', 'Xt'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
322
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
323 (Again, this sort of non-portable construct should be avoided if you intend to
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
324 distribute your code.)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
325
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
326 .. XXX Should mention clib libraries here or somewhere else!
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
327
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
328
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
329 Other options
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
330 -------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
331
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
332 There are still some other options which can be used to handle special cases.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
333
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
334 The :option:`optional` option is a boolean; if it is true,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
335 a build failure in the extension will not abort the build process, but
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
336 instead simply not install the failing extension.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
337
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
338 The :option:`extra_objects` option is a list of object files to be passed to the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
339 linker. These files must not have extensions, as the default extension for the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
340 compiler is used.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
341
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
342 :option:`extra_compile_args` and :option:`extra_link_args` can be used to
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
343 specify additional command-line options for the respective compiler and linker
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
344 command lines.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
345
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
346 :option:`export_symbols` is only useful on Windows. It can contain a list of
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
347 symbols (functions or variables) to be exported. This option is not needed when
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
348 building compiled extensions: Distutils will automatically add ``initmodule``
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
349 to the list of exported symbols.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
350
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
351 The :option:`depends` option is a list of files that the extension depends on
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
352 (for example header files). The build command will call the compiler on the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
353 sources to rebuild extension if any on this files has been modified since the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
354 previous build.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
355
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
356 Relationships between Distributions and Packages
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
357 ================================================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
358
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
359 .. FIXME rewrite to update to PEP 345 (but without dist/release confusion)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
360
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
361 A distribution may relate to packages in three specific ways:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
362
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
363 #. It can require packages or modules.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
364
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
365 #. It can provide packages or modules.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
366
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
367 #. It can obsolete packages or modules.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
368
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
369 These relationships can be specified using keyword arguments to the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
370 :func:`packaging.core.setup` function.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
371
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
372 Dependencies on other Python modules and packages can be specified by supplying
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
373 the *requires* keyword argument to :func:`setup`. The value must be a list of
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
374 strings. Each string specifies a package that is required, and optionally what
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
375 versions are sufficient.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
376
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
377 To specify that any version of a module or package is required, the string
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
378 should consist entirely of the module or package name. Examples include
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
379 ``'mymodule'`` and ``'xml.parsers.expat'``.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
380
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
381 If specific versions are required, a sequence of qualifiers can be supplied in
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
382 parentheses. Each qualifier may consist of a comparison operator and a version
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
383 number. The accepted comparison operators are::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
384
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
385 < > ==
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
386 <= >= !=
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
387
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
388 These can be combined by using multiple qualifiers separated by commas (and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
389 optional whitespace). In this case, all of the qualifiers must be matched; a
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
390 logical AND is used to combine the evaluations.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
391
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
392 Let's look at a bunch of examples:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
393
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
394 +-------------------------+----------------------------------------------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
395 | Requires Expression | Explanation |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
396 +=========================+==============================================+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
397 | ``==1.0`` | Only version ``1.0`` is compatible |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
398 +-------------------------+----------------------------------------------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
399 | ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
400 | | is compatible, except ``1.5.1`` |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
401 +-------------------------+----------------------------------------------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
402
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
403 Now that we can specify dependencies, we also need to be able to specify what we
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
404 provide that other distributions can require. This is done using the *provides*
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
405 keyword argument to :func:`setup`. The value for this keyword is a list of
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
406 strings, each of which names a Python module or package, and optionally
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
407 identifies the version. If the version is not specified, it is assumed to match
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
408 that of the distribution.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
409
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
410 Some examples:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
411
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
412 +---------------------+----------------------------------------------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
413 | Provides Expression | Explanation |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
414 +=====================+==============================================+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
415 | ``mypkg`` | Provide ``mypkg``, using the distribution |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
416 | | version |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
417 +---------------------+----------------------------------------------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
418 | ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
419 | | the distribution version |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
420 +---------------------+----------------------------------------------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
421
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
422 A package can declare that it obsoletes other packages using the *obsoletes*
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
423 keyword argument. The value for this is similar to that of the *requires*
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
424 keyword: a list of strings giving module or package specifiers. Each specifier
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
425 consists of a module or package name optionally followed by one or more version
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
426 qualifiers. Version qualifiers are given in parentheses after the module or
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
427 package name.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
428
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
429 The versions identified by the qualifiers are those that are obsoleted by the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
430 distribution being described. If no qualifiers are given, all versions of the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
431 named module or package are understood to be obsoleted.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
432
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
433 .. _packaging-installing-scripts:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
434
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
435 Installing Scripts
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
436 ==================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
437
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
438 So far we have been dealing with pure and non-pure Python modules, which are
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
439 usually not run by themselves but imported by scripts.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
440
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
441 Scripts are files containing Python source code, intended to be started from the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
442 command line. Scripts don't require Distutils to do anything very complicated.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
443 The only clever feature is that if the first line of the script starts with
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
444 ``#!`` and contains the word "python", the Distutils will adjust the first line
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
445 to refer to the current interpreter location. By default, it is replaced with
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
446 the current interpreter location. The :option:`--executable` (or :option:`-e`)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
447 option will allow the interpreter path to be explicitly overridden.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
448
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
449 The :option:`scripts` option simply is a list of files to be handled in this
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
450 way. From the PyXML setup script::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
451
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
452 setup(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
453 scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
454
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
455 All the scripts will also be added to the ``MANIFEST`` file if no template is
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
456 provided. See :ref:`packaging-manifest`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
457
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
458 .. _packaging-installing-package-data:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
459
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
460 Installing Package Data
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
461 =======================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
462
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
463 Often, additional files need to be installed into a package. These files are
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
464 often data that's closely related to the package's implementation, or text files
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
465 containing documentation that might be of interest to programmers using the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
466 package. These files are called :dfn:`package data`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
467
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
468 Package data can be added to packages using the ``package_data`` keyword
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
469 argument to the :func:`setup` function. The value must be a mapping from
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
470 package name to a list of relative path names that should be copied into the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
471 package. The paths are interpreted as relative to the directory containing the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
472 package (information from the ``package_dir`` mapping is used if appropriate);
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
473 that is, the files are expected to be part of the package in the source
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
474 directories. They may contain glob patterns as well.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
475
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
476 The path names may contain directory portions; any necessary directories will be
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
477 created in the installation.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
478
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
479 For example, if a package should contain a subdirectory with several data files,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
480 the files can be arranged like this in the source tree::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
481
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
482 setup.py
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
483 src/
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
484 mypkg/
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
485 __init__.py
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
486 module.py
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
487 data/
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
488 tables.dat
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
489 spoons.dat
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
490 forks.dat
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
491
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
492 The corresponding call to :func:`setup` might be::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
493
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
494 setup(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
495 packages=['mypkg'],
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
496 package_dir={'mypkg': 'src/mypkg'},
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
497 package_data={'mypkg': ['data/*.dat']})
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
498
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
499
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
500 All the files that match ``package_data`` will be added to the ``MANIFEST``
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
501 file if no template is provided. See :ref:`packaging-manifest`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
502
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
503
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
504 .. _packaging-additional-files:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
505
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
506 Installing Additional Files
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
507 ===========================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
508
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
509 The :option:`data_files` option can be used to specify additional files needed
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
510 by the module distribution: configuration files, message catalogs, data files,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
511 anything which doesn't fit in the previous categories.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
512
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
513 :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
514 following way::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
515
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
516 setup(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
517 data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
518 ('config', ['cfg/data.cfg']),
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
519 ('/etc/init.d', ['init-script'])])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
520
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
521 Note that you can specify the directory names where the data files will be
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
522 installed, but you cannot rename the data files themselves.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
523
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
524 Each (*directory*, *files*) pair in the sequence specifies the installation
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
525 directory and the files to install there. If *directory* is a relative path, it
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
526 is interpreted relative to the installation prefix (Python's ``sys.prefix`` for
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
527 pure-Python packages, ``sys.exec_prefix`` for packages that contain extension
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
528 modules). Each file name in *files* is interpreted relative to the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
529 :file:`setup.py` script at the top of the package source distribution. No
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
530 directory information from *files* is used to determine the final location of
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
531 the installed file; only the name of the file is used.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
532
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
533 You can specify the :option:`data_files` options as a simple sequence of files
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
534 without specifying a target directory, but this is not recommended, and the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
535 :command:`install_dist` command will print a warning in this case. To install data
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
536 files directly in the target directory, an empty string should be given as the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
537 directory.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
538
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
539 All the files that match ``data_files`` will be added to the ``MANIFEST`` file
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
540 if no template is provided. See :ref:`packaging-manifest`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
541
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
542
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
543
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
544 .. _packaging-metadata:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
545
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
546 Metadata reference
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
547 ==================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
548
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
549 The setup script may include additional metadata beyond the name and version.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
550 This table describes required and additional information:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
551
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
552 .. TODO synchronize with setupcfg; link to it (but don't remove it, it's a
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
553 useful summary)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
554
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
555 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
556 | Meta-Data | Description | Value | Notes |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
557 +======================+===========================+=================+========+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
558 | ``name`` | name of the project | short string | \(1) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
559 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
560 | ``version`` | version of this release | short string | (1)(2) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
561 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
562 | ``author`` | project author's name | short string | \(3) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
563 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
564 | ``author_email`` | email address of the | email address | \(3) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
565 | | project author | | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
566 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
567 | ``maintainer`` | project maintainer's name | short string | \(3) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
568 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
569 | ``maintainer_email`` | email address of the | email address | \(3) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
570 | | project maintainer | | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
571 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
572 | ``home_page`` | home page for the project | URL | \(1) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
573 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
574 | ``summary`` | short description of the | short string | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
575 | | project | | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
576 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
577 | ``description`` | longer description of the | long string | \(5) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
578 | | project | | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
579 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
580 | ``download_url`` | location where the | URL | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
581 | | project may be downloaded | | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
582 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
583 | ``classifiers`` | a list of classifiers | list of strings | \(4) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
584 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
585 | ``platforms`` | a list of platforms | list of strings | |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
586 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
587 | ``license`` | license for the release | short string | \(6) |
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
588 +----------------------+---------------------------+-----------------+--------+
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
589
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
590 Notes:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
591
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
592 (1)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
593 These fields are required.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
594
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
595 (2)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
596 It is recommended that versions take the form *major.minor[.patch[.sub]]*.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
597
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
598 (3)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
599 Either the author or the maintainer must be identified.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
600
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
601 (4)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
602 The list of classifiers is available from the `PyPI website
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
603 <http://pypi.python.org/pypi>`_. See also :mod:`packaging.create`.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
604
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
605 (5)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
606 The ``description`` field is used by PyPI when you are registering a
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
607 release, to build its PyPI page.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
608
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
609 (6)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
610 The ``license`` field is a text indicating the license covering the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
611 distribution where the license is not a selection from the "License" Trove
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
612 classifiers. See the ``Classifier`` field. Notice that
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
613 there's a ``licence`` distribution option which is deprecated but still
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
614 acts as an alias for ``license``.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
615
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
616 'short string'
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
617 A single line of text, not more than 200 characters.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
618
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
619 'long string'
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
620 Multiple lines of plain text in reStructuredText format (see
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
621 http://docutils.sf.net/).
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
622
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
623 'list of strings'
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
624 See below.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
625
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
626 In Python 2.x, "string value" means a unicode object. If a byte string (str or
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
627 bytes) is given, it has to be valid ASCII.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
628
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
629 .. TODO move this section to the version document, keep a summary, add a link
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
630
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
631 Encoding the version information is an art in itself. Python projects generally
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
632 adhere to the version format *major.minor[.patch][sub]*. The major number is 0
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
633 for initial, experimental releases of software. It is incremented for releases
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
634 that represent major milestones in a project. The minor number is incremented
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
635 when important new features are added to the project. The patch number
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
636 increments when bug-fix releases are made. Additional trailing version
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
637 information is sometimes used to indicate sub-releases. These are
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
638 "a1,a2,...,aN" (for alpha releases, where functionality and API may change),
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
639 "b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
640 (for final pre-release release testing). Some examples:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
641
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
642 0.1.0
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
643 the first, experimental release of a project
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
644
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
645 1.0.1a2
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
646 the second alpha release of the first patch version of 1.0
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
647
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
648 :option:`classifiers` are specified in a Python list::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
649
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
650 setup(...,
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
651 classifiers=[
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
652 'Development Status :: 4 - Beta',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
653 'Environment :: Console',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
654 'Environment :: Web Environment',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
655 'Intended Audience :: End Users/Desktop',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
656 'Intended Audience :: Developers',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
657 'Intended Audience :: System Administrators',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
658 'License :: OSI Approved :: Python Software Foundation License',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
659 'Operating System :: MacOS :: MacOS X',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
660 'Operating System :: Microsoft :: Windows',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
661 'Operating System :: POSIX',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
662 'Programming Language :: Python',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
663 'Topic :: Communications :: Email',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
664 'Topic :: Office/Business',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
665 'Topic :: Software Development :: Bug Tracking',
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
666 ])
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
667
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
668
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
669 Debugging the setup script
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
670 ==========================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
671
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
672 Sometimes things go wrong, and the setup script doesn't do what the developer
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
673 wants.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
674
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
675 Distutils catches any exceptions when running the setup script, and print a
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
676 simple error message before the script is terminated. The motivation for this
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
677 behaviour is to not confuse administrators who don't know much about Python and
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
678 are trying to install a project. If they get a big long traceback from deep
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
679 inside the guts of Distutils, they may think the project or the Python
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
680 installation is broken because they don't read all the way down to the bottom
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
681 and see that it's a permission problem.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
682
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
683 .. FIXME DISTUTILS_DEBUG is dead, document logging/warnings here
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
684
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
685 On the other hand, this doesn't help the developer to find the cause of the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
686 failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
687 to anything except an empty string, and Packaging will now print detailed
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
688 information about what it is doing, and prints the full traceback in case an
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
689 exception occurs.