Mercurial > cpython-lru_cache-weakref

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

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix markup.
author Georg Brandl <georg@python.org>
date Tue, 14 Jun 2011 21:09:55 +0200
parents 790353becf8c
children 4d5a546b6186
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
26 setup(name='Distutils',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
27 version='1.0',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
28 description='Python Distribution Utilities',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
29 author='Greg Ward',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
30 author_email='gward@python.net',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
31 url='http://www.python.org/sigs/distutils-sig/',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
32 packages=['distutils', 'distutils.command'],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
49186
47db62bf6aa7 Merged revisions 66452 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47285
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
56 glob.glob(os.path.join('mydir', 'subdir', '*.html'))
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 Distutils will issue a warning but still process the broken package anyways.
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
44396
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43176
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
153 from distutils.core import setup, Extension
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
154 setup(name='foo',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
155 version='1.0',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
156 ext_modules=[Extension('foo', ['foo.c'])],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
186 setup(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
187 ext_package='pkg',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
188 ext_modules=[Extension('foo', ['foo.c']),
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
189 Extension('subpkg.bar', ['bar.c'])],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
63351
790353becf8c After distutils doc reversal, change back **bold todo** items to XXX comments.
Georg Brandl <georg@python.org>
parents: 63350
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
215 setup(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
216 ext_modules=[Extension('_foo', ['foo.i'],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
217 swig_opts=['-modern', '-I../include'])],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
218 py_modules=['foo'],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 by the Distutils :command:`install_header` command. For example, the Numerical
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
271 from distutils.sysconfig import get_python_inc
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
272 incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
273 setup(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
274 Extension(..., include_dirs=[incdir]),
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
291 Extension(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
292 define_macros=[('NDEBUG', '1'),
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
293 ('HAVE_STRFTIME', None)],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
298 #define NDEBUG 1
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
299 #define HAVE_STRFTIME
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
300 #undef HAVE_FOO
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
316 Extension(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
322 Extension(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
323 library_dirs=['/usr/X11R6/lib'],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
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
63351
790353becf8c After distutils doc reversal, change back **bold todo** items to XXX comments.
Georg Brandl <georg@python.org>
parents: 63350
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
53072
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52610
diff changeset
337 The :option:`optional` option is a boolean; if it is true,
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52610
diff changeset
338 a build failure in the extension will not abort the build process, but
7e978ca42930 Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 52610
diff changeset
339 instead simply not install the failing extension.
52610
f7b11bf01a12 Merged revisions 70910 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51885
diff changeset
340
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341 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
342 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
343 compiler is used.
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:`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
346 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
347 command lines.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 :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
350 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
351 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
352 to the list of exported symbols.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353
51587
b8f10c6fad52 Merged revisions 69566 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 50563
diff changeset
354 The :option:`depends` option is a list of files that the extension depends on
b8f10c6fad52 Merged revisions 69566 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 50563
diff changeset
355 (for example header files). The build command will call the compiler on the
b8f10c6fad52 Merged revisions 69566 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 50563
diff changeset
356 sources to rebuild extension if any on this files has been modified since the
b8f10c6fad52 Merged revisions 69566 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 50563
diff changeset
357 previous build.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359 Relationships between Distributions and Packages
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360 ================================================
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 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
363
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
364 #. It can require 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 #. It can provide packages or modules.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 #. It can obsolete packages or modules.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370 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
371 :func:`distutils.core.setup` function.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
372
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
373 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
374 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
375 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
376 versions are sufficient.
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 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
379 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
380 ``'mymodule'`` and ``'xml.parsers.expat'``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382 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
383 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
384 number. The accepted comparison operators are::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
385
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
386 < > ==
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
387 <= >= !=
42604
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 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
390 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
391 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
392
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 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
394
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 | Requires Expression | Explanation |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397 +=========================+==============================================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398 | ``==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
399 +-------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
400 | ``>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
401 | | is compatible, except ``1.5.1`` |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 +-------------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404 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
405 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
406 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
407 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
408 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
409 that of the distribution.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
410
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
411 Some examples:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
412
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
413 +---------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
414 | Provides Expression | Explanation |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
415 +=====================+==============================================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
416 | ``mypkg`` | Provide ``mypkg``, using the distribution |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
417 | | version |
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 | ``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
420 | | the distribution version |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
421 +---------------------+----------------------------------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
422
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
423 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
424 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
425 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
426 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
427 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
428 package name.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
429
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
430 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
431 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
432 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
433
51671
54cf68fc7312 Merged revisions 69692 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51587
diff changeset
434 .. _distutils-installing-scripts:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
435
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
436 Installing 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
439 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
440 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
441
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
442 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
443 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
444 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
445 ``#!`` 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
446 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
447 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
448 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
449
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
450 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
451 way. From the PyXML setup script::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
452
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
453 setup(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
454 scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
455 )
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
456
53501
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
457 .. versionchanged:: 3.1
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
458 All the scripts will also be added to the ``MANIFEST`` file if no template is
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
459 provided. See :ref:`manifest`.
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
460
51671
54cf68fc7312 Merged revisions 69692 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51587
diff changeset
461
54cf68fc7312 Merged revisions 69692 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51587
diff changeset
462 .. _distutils-installing-package-data:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
463
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
464 Installing Package Data
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
465 =======================
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 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
468 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
469 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
470 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
471
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
472 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
473 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
474 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
475 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
476 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
477 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
478 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
479
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
480 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
481 created in the installation.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
482
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
483 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
484 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
485
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
486 setup.py
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
487 src/
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
488 mypkg/
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
489 __init__.py
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
490 module.py
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
491 data/
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
492 tables.dat
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
493 spoons.dat
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
494 forks.dat
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
495
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
496 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
497
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
498 setup(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
499 packages=['mypkg'],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
500 package_dir={'mypkg': 'src/mypkg'},
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
501 package_data={'mypkg': ['data/*.dat']},
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
502 )
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
503
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
504
53501
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
505 .. versionchanged:: 3.1
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
506 All the files that match ``package_data`` will be added to the ``MANIFEST``
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
507 file if no template is provided. See :ref:`manifest`.
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
508
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
509
51671
54cf68fc7312 Merged revisions 69692 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51587
diff changeset
510 .. _distutils-additional-files:
54cf68fc7312 Merged revisions 69692 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51587
diff changeset
511
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
512 Installing Additional Files
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
513 ===========================
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 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
516 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
517 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
518
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
519 :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
520 following way::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
521
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
522 setup(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
523 data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
524 ('config', ['cfg/data.cfg']),
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
525 ('/etc/init.d', ['init-script'])]
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
526 )
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
527
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
528 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
529 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
530
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
531 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
532 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
533 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
534 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
535 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
536 :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
537 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
538 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
539
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
540 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
541 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
542 :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
543 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
544 directory.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
545
53501
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
546 .. versionchanged:: 3.1
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
547 All the files that match ``data_files`` will be added to the ``MANIFEST``
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
548 file if no template is provided. See :ref:`manifest`.
98aa631dac2b Reintroduce versionchanged tags, but with correct version.
Georg Brandl <georg@python.org>
parents: 53500
diff changeset
549
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
550
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
551 .. _meta-data:
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 Additional meta-data
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
554 ====================
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 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
557 This information includes:
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 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
560 | Meta-Data | Description | Value | Notes |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
561 +======================+===========================+=================+========+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
562 | ``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
563 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
564 | ``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
565 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
566 | ``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
567 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
568 | ``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
569 | | package author | | |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
570 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
571 | ``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
572 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
573 | ``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
574 | | package maintainer | | |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
575 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
576 | ``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
577 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
578 | ``description`` | short, summary | short string | |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
579 | | description of the | | |
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 +----------------------+---------------------------+-----------------+--------+
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
582 | ``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
583 | | package | | |
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 | ``download_url`` | location where the | URL | \(4) |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
586 | | package may be downloaded | | |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
587 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
588 | ``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
589 +----------------------+---------------------------+-----------------+--------+
50250
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49735
diff changeset
590 | ``platforms`` | a list of platforms | list of strings | |
1adfabcbe073 Merged revisions 67886-67887 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 49735
diff changeset
591 +----------------------+---------------------------+-----------------+--------+
54763
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
592 | ``license`` | license for the package | short string | \(6) |
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
593 +----------------------+---------------------------+-----------------+--------+
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
594
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
595 Notes:
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 (1)
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
598 These fields are required.
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 (2)
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
601 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
602
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
603 (3)
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
604 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
605
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
606 (4)
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
607 These fields should not be used if your package is to be compatible with Python
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
608 versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
609 <http://pypi.python.org/pypi>`_.
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
610
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
611 (5)
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
612 The ``long_description`` field is used by PyPI when you are registering a
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
613 package, to build its home page.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
614
54763
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
615 (6)
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
616 The ``license`` field is a text indicating the license covering the
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
617 package where the license is not a selection from the "License" Trove
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
618 classifiers. See the ``Classifier`` field. Notice that
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
619 there's a ``licence`` distribution option which is deprecated but still
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
620 acts as an alias for ``license``.
9814d7f659a0 Merged revisions 73441 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 53501
diff changeset
621
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
622 'short string'
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
623 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
624
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
625 'long string'
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
626 Multiple lines of plain text in reStructuredText format (see
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
627 http://docutils.sf.net/).
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 'list of strings'
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
630 See below.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
631
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
632 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
633 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
634 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
635 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
636 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
637 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
638 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
639 "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
640 "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
641 (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
642
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
643 0.1.0
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
644 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
645
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
646 1.0.1a2
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
647 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
648
57798
e23f5ec93315 Merged revisions 76906 via svnmerge from
Ezio Melotti <ezio.melotti@gmail.com>
parents: 54763
diff changeset
649 :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
650
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
651 setup(...,
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
652 classifiers=[
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
653 'Development Status :: 4 - Beta',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
654 'Environment :: Console',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
655 'Environment :: Web Environment',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
656 'Intended Audience :: End Users/Desktop',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
657 'Intended Audience :: Developers',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
658 'Intended Audience :: System Administrators',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
659 'License :: OSI Approved :: Python Software Foundation License',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
660 'Operating System :: MacOS :: MacOS X',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
661 'Operating System :: Microsoft :: Windows',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
662 'Operating System :: POSIX',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
663 'Programming Language :: Python',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
664 'Topic :: Communications :: Email',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
665 'Topic :: Office/Business',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
666 'Topic :: Software Development :: Bug Tracking',
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
667 ],
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
668 )
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
669
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
670 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
671 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
672 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
673 :func:`setup` call. ::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
674
51885
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
675 # patch distutils if it can't cope with the "classifiers" or
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
676 # "download_url" keywords
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
677 from sys import version
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
678 if version < '2.2.3':
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
679 from distutils.dist import DistributionMetadata
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
680 DistributionMetadata.classifiers = None
e9d03f6b0d59 Merged revisions 70007 via svnmerge from
Tarek Ziadé <ziade.tarek@gmail.com>
parents: 51787
diff changeset
681 DistributionMetadata.download_url = None
42604
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
684 Debugging the setup script
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
687 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
688 wants.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
689
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
690 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
691 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
692 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
693 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
694 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
695 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
696 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
697
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
698 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
699 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
700 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
701 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
702 occurs.