3
************************
4
Writing the Setup Script
5
************************
7
The setup script is the centre of all activity in building, distributing, and
8
installing modules using the Distutils. The main purpose of the setup script is
9
to describe your module distribution to the Distutils, so that the various
10
commands that operate on your modules do the right thing. As we saw in section
11
: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
13
developer is supplied as keyword arguments to :func:`setup`.
15
Here's a slightly more involved example, which we'll follow for the next couple
16
of sections: the Distutils' own setup script. (Keep in mind that although the
17
Distutils are included with Python 1.6 and later, they also have an independent
18
existence so that Python 1.5.2 users can use them to install other module
19
distributions. The Distutils' own setup script, shown here, is used to install
20
the package into Python 1.5.2.) ::
24
from distutils.core import setup
26
setup(name='Distutils',
28
description='Python Distribution Utilities',
30
author_email='gward@python.net',
31
url='http://www.python.org/sigs/distutils-sig/',
32
packages=['distutils', 'distutils.command'],
35
There are only two differences between this and the trivial one-file
36
distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
37
specification of pure Python modules by package, rather than by module. This is
38
important 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
40
generate and difficult to maintain. For more information on the additional
41
meta-data, see section :ref:`meta-data`.
43
Note that any pathnames (files or directories) supplied in the setup script
44
should be written using the Unix convention, i.e. slash-separated. The
45
Distutils will take care of converting this platform-neutral representation into
46
whatever is appropriate on your current platform before actually using the
47
pathname. This makes your setup script portable across operating systems, which
48
of course is one of the major goals of the Distutils. In this spirit, all
49
pathnames in this document are slash-separated.
51
This, of course, only applies to pathnames given to Distutils functions. If
52
you, for example, use standard Python functions such as :func:`glob.glob` or
53
:func:`os.listdir` to specify files, you should be careful to write portable
54
code instead of hardcoding path separators::
56
glob.glob(os.path.join('mydir', 'subdir', '*.html'))
57
os.listdir(os.path.join('mydir', 'subdir'))
62
Listing whole packages
63
======================
65
The :option:`packages` option tells the Distutils to process (build, distribute,
66
install, etc.) all pure Python modules found in each package mentioned in the
67
:option:`packages` list. In order to do this, of course, there has to be a
68
correspondence between package names and directories in the filesystem. The
69
default correspondence is the most obvious one, i.e. package :mod:`distutils` is
70
found in the directory :file:`distutils` relative to the distribution root.
71
Thus, when you say ``packages = ['foo']`` in your setup script, you are
72
promising that the Distutils will find a file :file:`foo/__init__.py` (which
73
might be spelled differently on your system, but you get the idea) relative to
74
the directory where your setup script lives. If you break this promise, the
75
Distutils will issue a warning but still process the broken package anyways.
77
If you use a different convention to lay out your source directory, that's no
78
problem: you just have to supply the :option:`package_dir` option to tell the
79
Distutils about your convention. For example, say you keep all Python source
80
under :file:`lib`, so that modules in the "root package" (i.e., not in any
81
package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
82
:file:`lib/foo`, and so forth. Then you would put ::
84
package_dir = {'': 'lib'}
86
in your setup script. The keys to this dictionary are package names, and an
87
empty package name stands for the root package. The values are directory names
88
relative to your distribution root. In this case, when you say ``packages =
89
['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
91
Another possible convention is to put the :mod:`foo` package right in
92
:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
93
written in the setup script as ::
95
package_dir = {'foo': 'lib'}
97
A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
98
applies to all packages below *package*, so the :mod:`foo.bar` case is
99
automatically handled here. In this example, having ``packages = ['foo',
100
'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
101
:file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir`
102
applies recursively, you must explicitly list all packages in
103
:option:`packages`: the Distutils will *not* recursively scan your source tree
104
looking for any directory with an :file:`__init__.py` file.)
109
Listing individual modules
110
==========================
112
For a small module distribution, you might prefer to list all modules rather
113
than listing packages---especially the case of a single module that goes in the
114
"root package" (i.e., no package at all). This simplest case was shown in
115
section :ref:`distutils-simple-example`; here is a slightly more involved example::
117
py_modules = ['mod1', 'pkg.mod2']
119
This describes two modules, one of them in the "root" package, the other in the
120
:mod:`pkg` package. Again, the default package/directory layout implies that
121
these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
122
that :file:`pkg/__init__.py` exists as well. And again, you can override the
123
package/directory correspondence using the :option:`package_dir` option.
126
.. _describing-extensions:
128
Describing extension modules
129
============================
131
Just as writing Python extension modules is a bit more complicated than writing
132
pure Python modules, describing them to the Distutils is a bit more complicated.
133
Unlike pure modules, it's not enough just to list modules or packages and expect
134
the Distutils to go out and find the right files; you have to specify the
135
extension name, source file(s), and any compile/link requirements (include
136
directories, libraries to link with, etc.).
138
.. XXX read over this section
140
All of this is done through another keyword argument to :func:`setup`, the
141
:option:`ext_modules` option. :option:`ext_modules` is just a list of
142
:class:`Extension` instances, each of which describes a single extension module.
143
Suppose your distribution includes a single extension, called :mod:`foo` and
144
implemented by :file:`foo.c`. If no additional instructions to the
145
compiler/linker are needed, describing this extension is quite simple::
147
Extension('foo', ['foo.c'])
149
The :class:`Extension` class can be imported from :mod:`distutils.core` along
150
with :func:`setup`. Thus, the setup script for a module distribution that
151
contains only this one extension and nothing else might be::
153
from distutils.core import setup, Extension
156
ext_modules=[Extension('foo', ['foo.c'])],
159
The :class:`Extension` class (actually, the underlying extension-building
160
machinery implemented by the :command:`build_ext` command) supports a great deal
161
of flexibility in describing Python extensions, which is explained in the
165
Extension names and packages
166
----------------------------
168
The first argument to the :class:`Extension` constructor is always the name of
169
the extension, including any package names. For example, ::
171
Extension('foo', ['src/foo1.c', 'src/foo2.c'])
173
describes an extension that lives in the root package, while ::
175
Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
177
describes the same extension in the :mod:`pkg` package. The source files and
178
resulting object code are identical in both cases; the only difference is where
179
in the filesystem (and therefore where in Python's namespace hierarchy) the
180
resulting extension lives.
182
If you have a number of extensions all in the same package (or all under the
183
same base package), use the :option:`ext_package` keyword argument to
184
:func:`setup`. For example, ::
188
ext_modules=[Extension('foo', ['foo.c']),
189
Extension('subpkg.bar', ['bar.c'])],
192
will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
193
:mod:`pkg.subpkg.bar`.
196
Extension source files
197
----------------------
199
The second argument to the :class:`Extension` constructor is a list of source
200
files. Since the Distutils currently only support C, C++, and Objective-C
201
extensions, these are normally C/C++/Objective-C source files. (Be sure to use
202
appropriate extensions to distinguish C++\ source files: :file:`.cc` and
203
:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
205
However, you can also include SWIG interface (:file:`.i`) files in the list; the
206
:command:`build_ext` command knows how to deal with SWIG extensions: it will run
207
SWIG on the interface file and compile the resulting C/C++ file into your
210
**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
212
This warning notwithstanding, options to SWIG can be currently passed like
216
ext_modules=[Extension('_foo', ['foo.i'],
217
swig_opts=['-modern', '-I../include'])],
221
Or on the commandline like this::
223
> python setup.py build_ext --swig-opts="-modern -I../include"
225
On some platforms, you can include non-source files that are processed by the
226
compiler and included in your extension. Currently, this just means Windows
227
message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
228
Visual C++. These will be compiled to binary resource (:file:`.res`) files and
229
linked into the executable.
235
Three optional arguments to :class:`Extension` will help if you need to specify
236
include directories to search or preprocessor macros to define/undefine:
237
``include_dirs``, ``define_macros``, and ``undef_macros``.
239
For example, if your extension requires header files in the :file:`include`
240
directory under your distribution root, use the ``include_dirs`` option::
242
Extension('foo', ['foo.c'], include_dirs=['include'])
244
You can specify absolute directories there; if you know that your extension will
245
only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
248
Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
250
You should avoid this sort of non-portable usage if you plan to distribute your
251
code: it's probably better to write C code like ::
253
#include <X11/Xlib.h>
255
If you need to include header files from some other Python extension, you can
256
take advantage of the fact that header files are installed in a consistent way
257
by the Distutils :command:`install_header` command. For example, the Numerical
258
Python header files are installed (on a standard Unix installation) to
259
:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
260
according to your platform and Python installation.) Since the Python include
261
directory---\ :file:`/usr/local/include/python1.5` in this case---is always
262
included in the search path when building Python extensions, the best approach
263
is to write C code like ::
265
#include <Numerical/arrayobject.h>
267
If you must put the :file:`Numerical` include directory right into your header
268
search path, though, you can find that directory using the Distutils
269
:mod:`distutils.sysconfig` module::
271
from distutils.sysconfig import get_python_inc
272
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
274
Extension(..., include_dirs=[incdir]),
277
Even though this is quite portable---it will work on any Python installation,
278
regardless of platform---it's probably easier to just write your C code in the
281
You can define and undefine pre-processor macros with the ``define_macros`` and
282
``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
283
tuples, where ``name`` is the name of the macro to define (a string) and
284
``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
285
to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
286
most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
287
just a list of macros to undefine.
292
define_macros=[('NDEBUG', '1'),
293
('HAVE_STRFTIME', None)],
294
undef_macros=['HAVE_FOO', 'HAVE_BAR'])
296
is the equivalent of having this at the top of every C source file::
299
#define HAVE_STRFTIME
307
You can also specify the libraries to link against when building your extension,
308
and the directories to search for those libraries. The ``libraries`` option is
309
a list of libraries to link against, ``library_dirs`` is a list of directories
310
to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
311
directories to search for shared (dynamically loaded) libraries at run-time.
313
For example, if you need to link against libraries known to be in the standard
314
library search path on target systems ::
317
libraries=['gdbm', 'readline'])
319
If you need to link with libraries in a non-standard location, you'll have to
320
include the location in ``library_dirs``::
323
library_dirs=['/usr/X11R6/lib'],
324
libraries=['X11', 'Xt'])
326
(Again, this sort of non-portable construct should be avoided if you intend to
327
distribute your code.)
329
**\*\*** Should mention clib libraries here or somewhere else! **\*\***
335
There are still some other options which can be used to handle special cases.
337
The :option:`extra_objects` option is a list of object files to be passed to the
338
linker. These files must not have extensions, as the default extension for the
341
:option:`extra_compile_args` and :option:`extra_link_args` can be used to
342
specify additional command line options for the respective compiler and linker
345
:option:`export_symbols` is only useful on Windows. It can contain a list of
346
symbols (functions or variables) to be exported. This option is not needed when
347
building compiled extensions: Distutils will automatically add ``initmodule``
348
to the list of exported symbols.
350
The :option:`depends` option is a list of files that the extension depends on
351
(for example header files). The build command will call the compiler on the
352
sources to rebuild extension if any on this files has been modified since the
355
Relationships between Distributions and Packages
356
================================================
358
A distribution may relate to packages in three specific ways:
360
#. It can require packages or modules.
362
#. It can provide packages or modules.
364
#. It can obsolete packages or modules.
366
These relationships can be specified using keyword arguments to the
367
:func:`distutils.core.setup` function.
369
Dependencies on other Python modules and packages can be specified by supplying
370
the *requires* keyword argument to :func:`setup`. The value must be a list of
371
strings. Each string specifies a package that is required, and optionally what
372
versions are sufficient.
374
To specify that any version of a module or package is required, the string
375
should consist entirely of the module or package name. Examples include
376
``'mymodule'`` and ``'xml.parsers.expat'``.
378
If specific versions are required, a sequence of qualifiers can be supplied in
379
parentheses. Each qualifier may consist of a comparison operator and a version
380
number. The accepted comparison operators are::
385
These can be combined by using multiple qualifiers separated by commas (and
386
optional whitespace). In this case, all of the qualifiers must be matched; a
387
logical AND is used to combine the evaluations.
389
Let's look at a bunch of examples:
391
+-------------------------+----------------------------------------------+
392
| Requires Expression | Explanation |
393
+=========================+==============================================+
394
| ``==1.0`` | Only version ``1.0`` is compatible |
395
+-------------------------+----------------------------------------------+
396
| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
397
| | is compatible, except ``1.5.1`` |
398
+-------------------------+----------------------------------------------+
400
Now that we can specify dependencies, we also need to be able to specify what we
401
provide that other distributions can require. This is done using the *provides*
402
keyword argument to :func:`setup`. The value for this keyword is a list of
403
strings, each of which names a Python module or package, and optionally
404
identifies the version. If the version is not specified, it is assumed to match
405
that of the distribution.
409
+---------------------+----------------------------------------------+
410
| Provides Expression | Explanation |
411
+=====================+==============================================+
412
| ``mypkg`` | Provide ``mypkg``, using the distribution |
414
+---------------------+----------------------------------------------+
415
| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of |
416
| | the distribution version |
417
+---------------------+----------------------------------------------+
419
A package can declare that it obsoletes other packages using the *obsoletes*
420
keyword argument. The value for this is similar to that of the *requires*
421
keyword: a list of strings giving module or package specifiers. Each specifier
422
consists of a module or package name optionally followed by one or more version
423
qualifiers. Version qualifiers are given in parentheses after the module or
426
The versions identified by the qualifiers are those that are obsoleted by the
427
distribution being described. If no qualifiers are given, all versions of the
428
named module or package are understood to be obsoleted.
430
.. _distutils-installing-scripts:
435
So far we have been dealing with pure and non-pure Python modules, which are
436
usually not run by themselves but imported by scripts.
438
Scripts are files containing Python source code, intended to be started from the
439
command line. Scripts don't require Distutils to do anything very complicated.
440
The only clever feature is that if the first line of the script starts with
441
``#!`` and contains the word "python", the Distutils will adjust the first line
442
to refer to the current interpreter location. By default, it is replaced with
443
the current interpreter location. The :option:`--executable` (or :option:`-e`)
444
option will allow the interpreter path to be explicitly overridden.
446
The :option:`scripts` option simply is a list of files to be handled in this
447
way. From the PyXML setup script::
450
scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
453
.. versionchanged:: 2.7
454
All the scripts will also be added to the ``MANIFEST``
455
file if no template is provided. See :ref:`manifest`.
457
.. _distutils-installing-package-data:
459
Installing Package Data
460
=======================
462
Often, additional files need to be installed into a package. These files are
463
often data that's closely related to the package's implementation, or text files
464
containing documentation that might be of interest to programmers using the
465
package. These files are called :dfn:`package data`.
467
Package data can be added to packages using the ``package_data`` keyword
468
argument to the :func:`setup` function. The value must be a mapping from
469
package name to a list of relative path names that should be copied into the
470
package. The paths are interpreted as relative to the directory containing the
471
package (information from the ``package_dir`` mapping is used if appropriate);
472
that is, the files are expected to be part of the package in the source
473
directories. They may contain glob patterns as well.
475
The path names may contain directory portions; any necessary directories will be
476
created in the installation.
478
For example, if a package should contain a subdirectory with several data files,
479
the files can be arranged like this in the source tree::
491
The corresponding call to :func:`setup` might be::
495
package_dir={'mypkg': 'src/mypkg'},
496
package_data={'mypkg': ['data/*.dat']},
500
.. versionchanged:: 2.7
501
All the files that match ``package_data`` will be added to the ``MANIFEST``
502
file if no template is provided. See :ref:`manifest`.
505
.. _distutils-additional-files:
507
Installing Additional Files
508
===========================
510
The :option:`data_files` option can be used to specify additional files needed
511
by the module distribution: configuration files, message catalogs, data files,
512
anything which doesn't fit in the previous categories.
514
:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the
518
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
519
('config', ['cfg/data.cfg']),
520
('/etc/init.d', ['init-script'])]
523
Note that you can specify the directory names where the data files will be
524
installed, but you cannot rename the data files themselves.
526
Each (*directory*, *files*) pair in the sequence specifies the installation
527
directory and the files to install there. If *directory* is a relative path, it
528
is interpreted relative to the installation prefix (Python's ``sys.prefix`` for
529
pure-Python packages, ``sys.exec_prefix`` for packages that contain extension
530
modules). Each file name in *files* is interpreted relative to the
531
:file:`setup.py` script at the top of the package source distribution. No
532
directory information from *files* is used to determine the final location of
533
the installed file; only the name of the file is used.
535
You can specify the :option:`data_files` options as a simple sequence of files
536
without specifying a target directory, but this is not recommended, and the
537
:command:`install` command will print a warning in this case. To install data
538
files directly in the target directory, an empty string should be given as the
541
.. versionchanged:: 2.7
542
All the files that match ``data_files`` will be added to the ``MANIFEST``
543
file if no template is provided. See :ref:`manifest`.
552
The setup script may include additional meta-data beyond the name and version.
553
This information includes:
555
+----------------------+---------------------------+-----------------+--------+
556
| Meta-Data | Description | Value | Notes |
557
+======================+===========================+=================+========+
558
| ``name`` | name of the package | short string | \(1) |
559
+----------------------+---------------------------+-----------------+--------+
560
| ``version`` | version of this release | short string | (1)(2) |
561
+----------------------+---------------------------+-----------------+--------+
562
| ``author`` | package author's name | short string | \(3) |
563
+----------------------+---------------------------+-----------------+--------+
564
| ``author_email`` | email address of the | email address | \(3) |
565
| | package author | | |
566
+----------------------+---------------------------+-----------------+--------+
567
| ``maintainer`` | package maintainer's name | short string | \(3) |
568
+----------------------+---------------------------+-----------------+--------+
569
| ``maintainer_email`` | email address of the | email address | \(3) |
570
| | package maintainer | | |
571
+----------------------+---------------------------+-----------------+--------+
572
| ``url`` | home page for the package | URL | \(1) |
573
+----------------------+---------------------------+-----------------+--------+
574
| ``description`` | short, summary | short string | |
575
| | description of the | | |
577
+----------------------+---------------------------+-----------------+--------+
578
| ``long_description`` | longer description of the | long string | \(5) |
580
+----------------------+---------------------------+-----------------+--------+
581
| ``download_url`` | location where the | URL | \(4) |
582
| | package may be downloaded | | |
583
+----------------------+---------------------------+-----------------+--------+
584
| ``classifiers`` | a list of classifiers | list of strings | \(4) |
585
+----------------------+---------------------------+-----------------+--------+
586
| ``platforms`` | a list of platforms | list of strings | |
587
+----------------------+---------------------------+-----------------+--------+
592
These fields are required.
595
It is recommended that versions take the form *major.minor[.patch[.sub]]*.
598
Either the author or the maintainer must be identified.
601
These fields should not be used if your package is to be compatible with Python
602
versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
603
<http://pypi.python.org/pypi>`_.
606
The ``long_description`` field is used by PyPI when you are registering a
607
package, to build its home page.
610
A single line of text, not more than 200 characters.
613
Multiple lines of plain text in reStructuredText format (see
614
http://docutils.sf.net/).
619
Encoding the version information is an art in itself. Python packages generally
620
adhere to the version format *major.minor[.patch][sub]*. The major number is 0
621
for initial, experimental releases of software. It is incremented for releases
622
that represent major milestones in a package. The minor number is incremented
623
when important new features are added to the package. The patch number
624
increments when bug-fix releases are made. Additional trailing version
625
information is sometimes used to indicate sub-releases. These are
626
"a1,a2,...,aN" (for alpha releases, where functionality and API may change),
627
"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
628
(for final pre-release release testing). Some examples:
631
the first, experimental release of a package
634
the second alpha release of the first patch version of 1.0
636
:option:`classifiers` are specified in a python list::
640
'Development Status :: 4 - Beta',
641
'Environment :: Console',
642
'Environment :: Web Environment',
643
'Intended Audience :: End Users/Desktop',
644
'Intended Audience :: Developers',
645
'Intended Audience :: System Administrators',
646
'License :: OSI Approved :: Python Software Foundation License',
647
'Operating System :: MacOS :: MacOS X',
648
'Operating System :: Microsoft :: Windows',
649
'Operating System :: POSIX',
650
'Programming Language :: Python',
651
'Topic :: Communications :: Email',
652
'Topic :: Office/Business',
653
'Topic :: Software Development :: Bug Tracking',
657
If you wish to include classifiers in your :file:`setup.py` file and also wish
658
to remain backwards-compatible with Python releases prior to 2.2.3, then you can
659
include the following code fragment in your :file:`setup.py` before the
660
:func:`setup` call. ::
662
# patch distutils if it can't cope with the "classifiers" or
663
# "download_url" keywords
664
from sys import version
665
if version < '2.2.3':
666
from distutils.dist import DistributionMetadata
667
DistributionMetadata.classifiers = None
668
DistributionMetadata.download_url = None
671
Debugging the setup script
672
==========================
674
Sometimes things go wrong, and the setup script doesn't do what the developer
677
Distutils catches any exceptions when running the setup script, and print a
678
simple error message before the script is terminated. The motivation for this
679
behaviour is to not confuse administrators who don't know much about Python and
680
are trying to install a package. If they get a big long traceback from deep
681
inside the guts of Distutils, they may think the package or the Python
682
installation is broken because they don't read all the way down to the bottom
683
and see that it's a permission problem.
685
On the other hand, this doesn't help the developer to find the cause of the
686
failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set
687
to anything except an empty string, and distutils will now print detailed
688
information what it is doing, and prints the full traceback in case an exception
added
removed
Doc/distutils/setupscript.rst
