cpython-lru_cache-weakref: Doc/distutils/setupscript.rst annotate

annotate Doc/distutils/setupscript.rst @ 58765:2ba7677bfa95 legacy-trunk

testCopysign was defined twice in test_math; combine the definitions

author	Mark Dickinson <dickinsm@gmail.com>
date	Sat, 06 Feb 2010 23:11:25 +0000
parents	f7f5e1d27e06
children	946464fd6921

rev	line source
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1 .. _setup-script:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ************************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 Writing the Setup Script
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 ************************
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 The setup script is the centre of all activity in building, distributing, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 installing modules using the Distutils. The main purpose of the setup script is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9 to describe your module distribution to the Distutils, so that the various
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 commands that operate on your modules do the right thing. As we saw in section
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 :ref:`distutils-simple-example` above, the setup script consists mainly of a call to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 :func:`setup`, and most information supplied to the Distutils by the module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 developer is supplied as keyword arguments to :func:`setup`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 Here's a slightly more involved example, which we'll follow for the next couple
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 of sections: the Distutils' own setup script. (Keep in mind that although the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 Distutils are included with Python 1.6 and later, they also have an independent
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 existence so that Python 1.5.2 users can use them to install other module
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 distributions. The Distutils' own setup script, shown here, is used to install
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 the package into Python 1.5.2.) ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	22 #!/usr/bin/env python
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	24 from distutils.core import setup
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	26 setup(name='Distutils',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	27 version='1.0',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	28 description='Python Distribution Utilities',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	29 author='Greg Ward',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	30 author_email='gward@python.net',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	31 url='http://www.python.org/sigs/distutils-sig/',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	32 packages=['distutils', 'distutils.command'],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	33 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 There are only two differences between this and the trivial one-file
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37 specification of pure Python modules by package, rather than by module. This is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 important since the Distutils consist of a couple of dozen modules split into
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39 (so far) two packages; an explicit list of every module would be tedious to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 generate and difficult to maintain. For more information on the additional
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 meta-data, see section :ref:`meta-data`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 Note that any pathnames (files or directories) supplied in the setup script
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 should be written using the Unix convention, i.e. slash-separated. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 Distutils will take care of converting this platform-neutral representation into
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 whatever is appropriate on your current platform before actually using the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 pathname. This makes your setup script portable across operating systems, which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 of course is one of the major goals of the Distutils. In this spirit, all
49184 59db4b3a06b0 Remove things specific to the old Macintosh, and spell "Mac OS X" consistently. Georg Brandl <georg@python.org> parents: 45764 diff changeset	49 pathnames in this document are slash-separated.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 This, of course, only applies to pathnames given to Distutils functions. If
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 you, for example, use standard Python functions such as :func:`glob.glob` or
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 :func:`os.listdir` to specify files, you should be careful to write portable
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 code instead of hardcoding path separators::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	56 glob.glob(os.path.join('mydir', 'subdir', '*.html'))
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	57 os.listdir(os.path.join('mydir', 'subdir'))
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 .. _listing-packages:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 Listing whole packages
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 ======================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 The :option:`packages` option tells the Distutils to process (build, distribute,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 install, etc.) all pure Python modules found in each package mentioned in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 :option:`packages` list. In order to do this, of course, there has to be a
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 correspondence between package names and directories in the filesystem. The
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 default correspondence is the most obvious one, i.e. package :mod:`distutils` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70 found in the directory :file:`distutils` relative to the distribution root.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 Thus, when you say ``packages = ['foo']`` in your setup script, you are
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 promising that the Distutils will find a file :file:`foo/__init__.py` (which
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 might be spelled differently on your system, but you get the idea) relative to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 the directory where your setup script lives. If you break this promise, the
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
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	84 package_dir = {'': 'lib'}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 in your setup script. The keys to this dictionary are package names, and an
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 empty package name stands for the root package. The values are directory names
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 relative to your distribution root. In this case, when you say ``packages =
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 ['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 Another possible convention is to put the :mod:`foo` package right in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 :file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 written in the setup script as ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	95 package_dir = {'foo': 'lib'}
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98 applies to all packages below package, so the :mod:`foo.bar` case is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 automatically handled here. In this example, having ``packages = ['foo',
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 :file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 applies recursively, you must explicitly list all packages in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 :option:`packages`: the Distutils will not recursively scan your source tree
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 looking for any directory with an :file:`__init__.py` file.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107 .. _listing-modules:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 Listing individual modules
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 ==========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 For a small module distribution, you might prefer to list all modules rather
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 than listing packages---especially the case of a single module that goes in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 "root package" (i.e., no package at all). This simplest case was shown in
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 section :ref:`distutils-simple-example`; here is a slightly more involved example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	117 py_modules = ['mod1', 'pkg.mod2']
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 This describes two modules, one of them in the "root" package, the other in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120 :mod:`pkg` package. Again, the default package/directory layout implies that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	121 these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	122 that :file:`pkg/__init__.py` exists as well. And again, you can override the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 package/directory correspondence using the :option:`package_dir` option.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 .. _describing-extensions:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 Describing extension modules
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 ============================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131 Just as writing Python extension modules is a bit more complicated than writing
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 pure Python modules, describing them to the Distutils is a bit more complicated.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 Unlike pure modules, it's not enough just to list modules or packages and expect
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134 the Distutils to go out and find the right files; you have to specify the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 extension name, source file(s), and any compile/link requirements (include
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 directories, libraries to link with, etc.).
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 42604 diff changeset	138 .. XXX read over this section
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140 All of this is done through another keyword argument to :func:`setup`, the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 :option:`ext_modules` option. :option:`ext_modules` is just a list of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 :class:`Extension` instances, each of which describes a single extension module.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 Suppose your distribution includes a single extension, called :mod:`foo` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 implemented by :file:`foo.c`. If no additional instructions to the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 compiler/linker are needed, describing this extension is quite simple::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	147 Extension('foo', ['foo.c'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	148
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149 The :class:`Extension` class can be imported from :mod:`distutils.core` along
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 with :func:`setup`. Thus, the setup script for a module distribution that
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151 contains only this one extension and nothing else might be::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	153 from distutils.core import setup, Extension
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	154 setup(name='foo',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	155 version='1.0',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	156 ext_modules=[Extension('foo', ['foo.c'])],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	157 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 The :class:`Extension` class (actually, the underlying extension-building
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 machinery implemented by the :command:`build_ext` command) supports a great deal
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 of flexibility in describing Python extensions, which is explained in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 following sections.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 Extension names and packages
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 ----------------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 The first argument to the :class:`Extension` constructor is always the name of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 the extension, including any package names. For example, ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	171 Extension('foo', ['src/foo1.c', 'src/foo2.c'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 describes an extension that lives in the root package, while ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	175 Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 describes the same extension in the :mod:`pkg` package. The source files and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178 resulting object code are identical in both cases; the only difference is where
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 in the filesystem (and therefore where in Python's namespace hierarchy) the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 resulting extension lives.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 If you have a number of extensions all in the same package (or all under the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 same base package), use the :option:`ext_package` keyword argument to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 :func:`setup`. For example, ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	186 setup(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	187 ext_package='pkg',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	188 ext_modules=[Extension('foo', ['foo.c']),
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	189 Extension('subpkg.bar', ['bar.c'])],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	190 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 :mod:`pkg.subpkg.bar`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 Extension source files
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 ----------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 The second argument to the :class:`Extension` constructor is a list of source
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 files. Since the Distutils currently only support C, C++, and Objective-C
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 extensions, these are normally C/C++/Objective-C source files. (Be sure to use
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 appropriate extensions to distinguish C++\ source files: :file:`.cc` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 :file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 However, you can also include SWIG interface (:file:`.i`) files in the list; the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 :command:`build_ext` command knows how to deal with SWIG extensions: it will run
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 SWIG on the interface file and compile the resulting C/C++ file into your
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 extension.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 *\\* SWIG support is rough around the edges and largely untested! \\**
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 This warning notwithstanding, options to SWIG can be currently passed like
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	215 setup(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	216 ext_modules=[Extension('_foo', ['foo.i'],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	217 swig_opts=['-modern', '-I../include'])],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	218 py_modules=['foo'],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	219 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 Or on the commandline like this::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	223 > python setup.py build_ext --swig-opts="-modern -I../include"
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 On some platforms, you can include non-source files that are processed by the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226 compiler and included in your extension. Currently, this just means Windows
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 Visual C++. These will be compiled to binary resource (:file:`.res`) files and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 linked into the executable.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	232 Preprocessor options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233 --------------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235 Three optional arguments to :class:`Extension` will help if you need to specify
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 include directories to search or preprocessor macros to define/undefine:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 ``include_dirs``, ``define_macros``, and ``undef_macros``.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 For example, if your extension requires header files in the :file:`include`
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 directory under your distribution root, use the ``include_dirs`` option::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	242 Extension('foo', ['foo.c'], include_dirs=['include'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 You can specify absolute directories there; if you know that your extension will
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 away with ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	248 Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 You should avoid this sort of non-portable usage if you plan to distribute your
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 code: it's probably better to write C code like ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	253 #include <X11/Xlib.h>
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 If you need to include header files from some other Python extension, you can
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 take advantage of the fact that header files are installed in a consistent way
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
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	265 #include <Numerical/arrayobject.h>
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 If you must put the :file:`Numerical` include directory right into your header
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268 search path, though, you can find that directory using the Distutils
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 :mod:`distutils.sysconfig` module::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	271 from distutils.sysconfig import get_python_inc
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	272 incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	273 setup(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	274 Extension(..., include_dirs=[incdir]),
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	275 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277 Even though this is quite portable---it will work on any Python installation,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278 regardless of platform---it's probably easier to just write your C code in the
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 sensible way.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 You can define and undefine pre-processor macros with the ``define_macros`` and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282 ``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283 tuples, where ``name`` is the name of the macro to define (a string) and
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 ``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285 to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 just a list of macros to undefine.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 For example::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	291 Extension(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	292 define_macros=[('NDEBUG', '1'),
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	293 ('HAVE_STRFTIME', None)],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	294 undef_macros=['HAVE_FOO', 'HAVE_BAR'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 is the equivalent of having this at the top of every C source file::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	298 #define NDEBUG 1
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	299 #define HAVE_STRFTIME
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	300 #undef HAVE_FOO
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	301 #undef HAVE_BAR
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 Library options
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305 ---------------
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 You can also specify the libraries to link against when building your extension,
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308 and the directories to search for those libraries. The ``libraries`` option is
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 a list of libraries to link against, ``library_dirs`` is a list of directories
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 directories to search for shared (dynamically loaded) libraries at run-time.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 For example, if you need to link against libraries known to be in the standard
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 library search path on target systems ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	316 Extension(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	317 libraries=['gdbm', 'readline'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 If you need to link with libraries in a non-standard location, you'll have to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 include the location in ``library_dirs``::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	322 Extension(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	323 library_dirs=['/usr/X11R6/lib'],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	324 libraries=['X11', 'Xt'])
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 (Again, this sort of non-portable construct should be avoided if you intend to
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327 distribute your code.)
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 *\\* Should mention clib libraries here or somewhere else! \\**
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
53066 8861298586c1 Re-word Andrew M. Kuchling <amk@amk.ca> parents: 52606 diff changeset	337 The :option:`optional` option is a boolean; if it is true,
8861298586c1 Re-word Andrew M. Kuchling <amk@amk.ca> parents: 52606 diff changeset	338 a build failure in the extension will not abort the build process, but
8861298586c1 Re-word Andrew M. Kuchling <amk@amk.ca> parents: 52606 diff changeset	339 instead simply not install the failing extension.
52606 5856fae009e8 #5583 Added optional Extensions in Distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 51883 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
51585 bd2b779f5f31 #5158: added documentation on the depends option in distutils extensions Tarek Ziadé <ziade.tarek@gmail.com> parents: 50522 diff changeset	354 The :option:`depends` option is a list of files that the extension depends on
bd2b779f5f31 #5158: added documentation on the depends option in distutils extensions Tarek Ziadé <ziade.tarek@gmail.com> parents: 50522 diff changeset	355 (for example header files). The build command will call the compiler on the
bd2b779f5f31 #5158: added documentation on the depends option in distutils extensions Tarek Ziadé <ziade.tarek@gmail.com> parents: 50522 diff changeset	356 sources to rebuild extension if any on this files has been modified since the
bd2b779f5f31 #5158: added documentation on the depends option in distutils extensions Tarek Ziadé <ziade.tarek@gmail.com> parents: 50522 diff changeset	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
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	386 < > ==
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 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
51667 982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	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
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	453 setup(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	454 scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	455 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456
51785 ecd8ef4e79e6 using versionchanged instead of versionadded for distutils doc on sdist default files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51667 diff changeset	457 .. versionchanged:: 2.7
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	458 All the scripts will also be added to the ``MANIFEST``
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	459 file if no template is provided. See :ref:`manifest`.
51667 982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	460
982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	461 .. _distutils-installing-package-data:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463 Installing Package Data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 =======================
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 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	467 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	468 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	469 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	470
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 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	472 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	473 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	474 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	475 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	476 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	477 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	478
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 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	480 created in the installation.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 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	483 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	484
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	485 setup.py
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	486 src/
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	487 mypkg/
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	488 __init__.py
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	489 module.py
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	490 data/
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	491 tables.dat
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	492 spoons.dat
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	493 forks.dat
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 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	496
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	497 setup(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	498 packages=['mypkg'],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	499 package_dir={'mypkg': 'src/mypkg'},
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	500 package_data={'mypkg': ['data/*.dat']},
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	501 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503 .. versionadded:: 2.4
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504
51785 ecd8ef4e79e6 using versionchanged instead of versionadded for distutils doc on sdist default files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51667 diff changeset	505 .. versionchanged:: 2.7
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	506 All the files that match ``package_data`` will be added to the ``MANIFEST``
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	507 file if no template is provided. See :ref:`manifest`.
51667 982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	508
982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	509
982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	510 .. _distutils-additional-files:
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511
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
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	522 setup(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	523 data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	524 ('config', ['cfg/data.cfg']),
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	525 ('/etc/init.d', ['init-script'])]
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 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
51785 ecd8ef4e79e6 using versionchanged instead of versionadded for distutils doc on sdist default files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51667 diff changeset	546 .. versionchanged:: 2.7
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	547 All the files that match ``data_files`` will be added to the ``MANIFEST``
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	548 file if no template is provided. See :ref:`manifest`.
51667 982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	549
982f9e2925a4 Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files Tarek Ziadé <ziade.tarek@gmail.com> parents: 51585 diff changeset	550
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 .. _meta-data:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 Additional meta-data
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 ====================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 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	558 This information includes:
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 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 \| Meta-Data \| Description \| Value \| Notes \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 +======================+===========================+=================+========+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 \| ``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	564 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 \| ``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	566 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567 \| ``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	568 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 \| ``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	570 \| \| package author \| \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 \| ``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	573 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 \| ``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	575 \| \| package maintainer \| \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 \| ``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	578 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579 \| ``description`` \| short, summary \| short string \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 \| \| description of the \| \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 \| \| package \| \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 +----------------------+---------------------------+-----------------+--------+
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	583 \| ``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	584 \| \| package \| \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 \| ``download_url`` \| location where the \| URL \| \(4) \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 \| \| package may be downloaded \| \| \|
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 +----------------------+---------------------------+-----------------+--------+
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589 \| ``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	590 +----------------------+---------------------------+-----------------+--------+
50257 e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	591 \| ``platforms`` \| a list of platforms \| list of strings \| \|
e4675113d10e Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from Benjamin Peterson <benjamin@python.org> parents: 49184 diff changeset	592 +----------------------+---------------------------+-----------------+--------+
54761 20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	593 \| ``license`` \| license for the package \| short string \| \(6) \|
20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	594 +----------------------+---------------------------+-----------------+--------+
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596 Notes:
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 (1)
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	599 These fields are required.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601 (2)
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	602 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	603
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 (3)
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	605 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	606
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 (4)
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	608 These fields should not be used if your package is to be compatible with Python
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	609 versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	610 <http://pypi.python.org/pypi>`_.
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	611
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	612 (5)
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	613 The ``long_description`` field is used by PyPI when you are registering a
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	614 package, to build its home page.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615
54761 20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	616 (6)
20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	617 The ``license`` field is a text indicating the license covering the
20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	618 package where the license is not a selection from the "License" Trove
20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	619 classifiers. See the ``Classifier`` field. Notice that
20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	620 there's a ``licence`` distribution option which is deprecated but still
20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	621 acts as an alias for ``license``.
20343aa2a3eb Fixed #6287: documentation for the license field in distutils Tarek Ziadé <ziade.tarek@gmail.com> parents: 53066 diff changeset	622
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 'short string'
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	624 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	625
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626 'long string'
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	627 Multiple lines of plain text in reStructuredText format (see
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	628 http://docutils.sf.net/).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	629
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	630 'list of strings'
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	631 See below.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	633 None of the string values may be Unicode.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635 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	636 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	637 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	638 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	639 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	640 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	641 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	642 "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	643 "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	644 (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	645
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 0.1.0
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	647 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	648
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 1.0.1a2
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	650 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	651
57795 f7f5e1d27e06 #7388: "python".capitalize() in the Doc Ezio Melotti <ezio.melotti@gmail.com> parents: 54761 diff changeset	652 :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	653
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	654 setup(...,
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	655 classifiers=[
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	656 'Development Status :: 4 - Beta',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	657 'Environment :: Console',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	658 'Environment :: Web Environment',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	659 'Intended Audience :: End Users/Desktop',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	660 'Intended Audience :: Developers',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	661 'Intended Audience :: System Administrators',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	662 'License :: OSI Approved :: Python Software Foundation License',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	663 'Operating System :: MacOS :: MacOS X',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	664 'Operating System :: Microsoft :: Windows',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	665 'Operating System :: POSIX',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	666 'Programming Language :: Python',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	667 'Topic :: Communications :: Email',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	668 'Topic :: Office/Business',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	669 'Topic :: Software Development :: Bug Tracking',
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	670 ],
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	671 )
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	672
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	673 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	674 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	675 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	676 :func:`setup` call. ::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677
51883 b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	678 # patch distutils if it can't cope with the "classifiers" or
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	679 # "download_url" keywords
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	680 from sys import version
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	681 if version < '2.2.3':
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	682 from distutils.dist import DistributionMetadata
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	683 DistributionMetadata.classifiers = None
b7b23887fbde more info on long_description Tarek Ziadé <ziade.tarek@gmail.com> parents: 51785 diff changeset	684 DistributionMetadata.download_url = None
42604 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 Debugging the setup script
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	688 ==========================
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	689
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	690 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	691 wants.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	692
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	693 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	694 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	695 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	696 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	697 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	698 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	699 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	700
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 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	702 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	703 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	704 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	705 occurs.

Mercurial > cpython-lru_cache-weakref

annotate Doc/distutils/setupscript.rst @ 58765:2ba7677bfa95 legacy-trunk