rest25/distutils/setupscript.rst => rest262/distutils/setupscript.rst
3************************
4Writing the Setup Script
5************************
6
7The setup script is the centre of all activity in building, distributing, and
8installing modules using the Distutils.  The main purpose of the setup script is
9to describe your module distribution to the Distutils, so that the various
10commands that operate on your modules do the right thing.  As we saw in section
n11-:ref:`simple-example` above, the setup script consists mainly of a call to
n11+:ref:`distutils-simple-example` above, the setup script consists mainly of a call to
12:func:`setup`, and most information supplied to the Distutils by the module
13developer is supplied as keyword arguments to :func:`setup`.
14
15Here's a slightly more involved example, which we'll follow for the next couple
16of sections: the Distutils' own setup script.  (Keep in mind that although the
17Distutils are included with Python 1.6 and later, they also have an independent
18existence so that Python 1.5.2 users can use them to install other module
19distributions.  The Distutils' own setup script, shown here, is used to install
28         description='Python Distribution Utilities',
29         author='Greg Ward',
30         author_email='gward@python.net',
31         url='http://www.python.org/sigs/distutils-sig/',
32         packages=['distutils', 'distutils.command'],
33        )
34
35There are only two differences between this and the trivial one-file
n36-distribution presented in section :ref:`simple-example`: more metadata, and the
n36+distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
37specification of pure Python modules by package, rather than by module.  This is
38important since the Distutils consist of a couple of dozen modules split into
39(so far) two packages; an explicit list of every module would be tedious to
40generate and difficult to maintain.  For more information on the additional
41meta-data, see section :ref:`meta-data`.
42
43Note that any pathnames (files or directories) supplied in the setup script
44should be written using the Unix convention, i.e. slash-separated.  The
45Distutils will take care of converting this platform-neutral representation into
46whatever is appropriate on your current platform before actually using the
47pathname.  This makes your setup script portable across operating systems, which
48of course is one of the major goals of the Distutils.  In this spirit, all
n49-pathnames in this document are slash-separated.  (Mac OS 9 programmers should
n49+pathnames in this document are slash-separated.
50-keep in mind that the *absence* of a leading slash indicates a relative path,
51-the opposite of the Mac OS convention with colons.)
52
53This, of course, only applies to pathnames given to Distutils functions.  If
54you, for example, use standard Python functions such as :func:`glob.glob` or
55:func:`os.listdir` to specify files, you should be careful to write portable
56code instead of hardcoding path separators::
57
58   glob.glob(os.path.join('mydir', 'subdir', '*.html'))
59   os.listdir(os.path.join('mydir', 'subdir'))
109.. _listing-modules:
110
111Listing individual modules
112==========================
113
114For a small module distribution, you might prefer to list all modules rather
115than listing packages---especially the case of a single module that goes in the
116"root package" (i.e., no package at all).  This simplest case was shown in
n117-section :ref:`simple-example`; here is a slightly more involved example::
n115+section :ref:`distutils-simple-example`; here is a slightly more involved example::
118
119   py_modules = ['mod1', 'pkg.mod2']
120
121This describes two modules, one of them in the "root" package, the other in the
122:mod:`pkg` package.  Again, the default package/directory layout implies that
123these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
124that :file:`pkg/__init__.py` exists as well. And again, you can override the
125package/directory correspondence using the :option:`package_dir` option.
132
133Just as writing Python extension modules is a bit more complicated than writing
134pure Python modules, describing them to the Distutils is a bit more complicated.
135Unlike pure modules, it's not enough just to list modules or packages and expect
136the Distutils to go out and find the right files; you have to specify the
137extension name, source file(s), and any compile/link requirements (include
138directories, libraries to link with, etc.).
139
n140-.. % XXX read over this section
n138+.. XXX read over this section
141
142All of this is done through another keyword argument to :func:`setup`, the
143:option:`ext_modules` option.  :option:`ext_modules` is just a list of
144:class:`Extension` instances, each of which describes a single extension module.
145Suppose your distribution includes a single extension, called :mod:`foo` and
146implemented by :file:`foo.c`.  If no additional instructions to the
147compiler/linker are needed, describing this extension is quite simple::
148
180resulting object code are identical in both cases; the only difference is where
181in the filesystem (and therefore where in Python's namespace hierarchy) the
182resulting extension lives.
183
184If you have a number of extensions all in the same package (or all under the
185same base package), use the :option:`ext_package` keyword argument to
186:func:`setup`.  For example, ::
187
n188-   setup(...
n186+   setup(...,
189         ext_package='pkg',
190         ext_modules=[Extension('foo', ['foo.c']),
191                      Extension('subpkg.bar', ['bar.c'])],
192        )
193
194will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
195:mod:`pkg.subpkg.bar`.
196
204appropriate extensions to distinguish C++\ source files: :file:`.cc` and
205:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
206
207However, you can also include SWIG interface (:file:`.i`) files in the list; the
208:command:`build_ext` command knows how to deal with SWIG extensions: it will run
209SWIG on the interface file and compile the resulting C/C++ file into your
210extension.
211
n212-**\*\*** SWIG support is rough around the edges and largely untested; especially
n210+**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
213-SWIG support for C++ extensions!  Explain in more detail here when the interface
211+ 
214-firms up. **\*\***
212+This warning notwithstanding, options to SWIG can be currently passed like
213+this::
214+ 
215+   setup(...,
216+         ext_modules=[Extension('_foo', ['foo.i'],
217+                                swig_opts=['-modern', '-I../include'])],
218+         py_modules=['foo'],
219+        )
220+ 
221+Or on the commandline like this::
222+ 
223+   > python setup.py build_ext --swig-opts="-modern -I../include"
215
216On some platforms, you can include non-source files that are processed by the
217compiler and included in your extension.  Currently, this just means Windows
218message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
219Visual C++. These will be compiled to binary resource (:file:`.res`) files and
220linked into the executable.
221
222
394Some examples:
395
396+---------------------+----------------------------------------------+
397| Provides Expression | Explanation                                  |
398+=====================+==============================================+
399| ``mypkg``           | Provide ``mypkg``, using the distribution    |
400|                     | version                                      |
401+---------------------+----------------------------------------------+
n402-| ``mypkg (1.1``      | Provide ``mypkg`` version 1.1, regardless of |
n411+| ``mypkg (1.1)``     | Provide ``mypkg`` version 1.1, regardless of |
403|                     | the distribution version                     |
404+---------------------+----------------------------------------------+
405
406A package can declare that it obsoletes other packages using the *obsoletes*
407keyword argument.  The value for this is similar to that of the *requires*
408keyword: a list of strings giving module or package specifiers.  Each specifier
409consists of a module or package name optionally followed by one or more version
410qualifiers.  Version qualifiers are given in parentheses after the module or
427``#!`` and contains the word "python", the Distutils will adjust the first line
428to refer to the current interpreter location. By default, it is replaced with
429the current interpreter location.  The :option:`--executable` (or :option:`-e`)
430option will allow the interpreter path to be explicitly overridden.
431
432The :option:`scripts` option simply is a list of files to be handled in this
433way.  From the PyXML setup script::
434
n435-   setup(... 
n444+   setup(...,
436         scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
437         )
438
439
440Installing Package Data
441=======================
442
443Often, additional files need to be installed into a package.  These files are
485
486The :option:`data_files` option can be used to specify additional files needed
487by the module distribution: configuration files, message catalogs, data files,
488anything which doesn't fit in the previous categories.
489
490:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the
491following way::
492
n493-   setup(...
n502+   setup(...,
494         data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
495                     ('config', ['cfg/data.cfg']),
496                     ('/etc/init.d', ['init-script'])]
497        )
498
499Note that you can specify the directory names where the data files will be
500installed, but you cannot rename the data files themselves.
501
549| ``long_description`` | longer description of the | long string     |        |
550|                      | package                   |                 |        |
551+----------------------+---------------------------+-----------------+--------+
552| ``download_url``     | location where the        | URL             | \(4)   |
553|                      | package may be downloaded |                 |        |
554+----------------------+---------------------------+-----------------+--------+
555| ``classifiers``      | a list of classifiers     | list of strings | \(4)   |
556+----------------------+---------------------------+-----------------+--------+
n566+| ``platforms``        | a list of platforms       | list of strings |        |
567++----------------------+---------------------------+-----------------+--------+
557
558Notes:
559
560(1)
561   These fields are required.
562
563(2)
564   It is recommended that versions take the form *major.minor[.patch[.sub]]*.
565
566(3)
567   Either the author or the maintainer must be identified.
568
569(4)
570   These fields should not be used if your package is to be compatible with Python
571   versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
n572-   <http://www.python.org/pypi>`_.
n583+   <http://pypi.python.org/pypi>`_.
573
574'short string'
575   A single line of text, not more than 200 characters.
576
577'long string'
578   Multiple lines of plain text in reStructuredText format (see
n579-   `<http://docutils.sf.net/>`_).
n590+   http://docutils.sf.net/).
580
581'list of strings'
582   See below.
583
584None of the string values may be Unicode.
585
586Encoding the version information is an art in itself. Python packages generally
587adhere to the version format *major.minor[.patch][sub]*. The major number is 0
5970.1.0
598   the first, experimental release of a package
599
6001.0.1a2
601   the second alpha release of the first patch version of 1.0
602
603:option:`classifiers` are specified in a python list::
604
t605-   setup(...
t616+   setup(...,
606         classifiers=[
607             'Development Status :: 4 - Beta',
608             'Environment :: Console',
609             'Environment :: Web Environment',
610             'Intended Audience :: End Users/Desktop',
611             'Intended Audience :: Developers',
612             'Intended Audience :: System Administrators',
613             'License :: OSI Approved :: Python Software Foundation License',
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op