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

annotate Doc/packaging/setupscript.rst @ 73798:6cde416ef03b

Credit Per Øyvind Karlsen for the initial implementation of the lzma module (issue #6715).

author	Nadeem Vawda <nadeem.vawda@gmail.com>
date	Thu, 01 Dec 2011 01:18:27 +0200
parents	f84040b11211
children

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

Mercurial > cpython-lru_cache-weakref

annotate Doc/packaging/setupscript.rst @ 73798:6cde416ef03b