Mercurial > cpython-lru_cache-weakref

annotate Doc/distutils/setupscript.rst @ 80661:94de77bd0b4b 2.7

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