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='https://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 ``packages`` option tells the Distutils to process (build, distribute,
66
install, etc.) all pure Python modules found in each package mentioned in the
67
``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 anyway.
77
If you use a different convention to lay out your source directory, that's no
78
problem: you just have to supply the ``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 ``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 ``package_dir``
102
applies recursively, you must explicitly list all packages in
103
``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 ``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
``ext_modules`` option. ``ext_modules`` is just a list of
142
:class:`~distutils.core.Extension` instances, each of which describes a
143
single extension module.
144
Suppose your distribution includes a single extension, called :mod:`foo` and
145
implemented by :file:`foo.c`. If no additional instructions to the
146
compiler/linker are needed, describing this extension is quite simple::
148
Extension('foo', ['foo.c'])
150
The :class:`Extension` class can be imported from :mod:`distutils.core` along
151
with :func:`setup`. Thus, the setup script for a module distribution that
152
contains only this one extension and nothing else might be::
154
from distutils.core import setup, Extension
157
ext_modules=[Extension('foo', ['foo.c'])],
160
The :class:`Extension` class (actually, the underlying extension-building
161
machinery implemented by the :command:`build_ext` command) supports a great deal
162
of flexibility in describing Python extensions, which is explained in the
166
Extension names and packages
167
----------------------------
169
The first argument to the :class:`~distutils.core.Extension` constructor is
170
always the name of the extension, including any package names. For example, ::
172
Extension('foo', ['src/foo1.c', 'src/foo2.c'])
174
describes an extension that lives in the root package, while ::
176
Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
178
describes the same extension in the :mod:`pkg` package. The source files and
179
resulting object code are identical in both cases; the only difference is where
180
in the filesystem (and therefore where in Python's namespace hierarchy) the
181
resulting extension lives.
183
If you have a number of extensions all in the same package (or all under the
184
same base package), use the ``ext_package`` keyword argument to
185
:func:`setup`. For example, ::
189
ext_modules=[Extension('foo', ['foo.c']),
190
Extension('subpkg.bar', ['bar.c'])],
193
will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
194
:mod:`pkg.subpkg.bar`.
197
Extension source files
198
----------------------
200
The second argument to the :class:`~distutils.core.Extension` constructor is
202
files. Since the Distutils currently only support C, C++, and Objective-C
203
extensions, these are normally C/C++/Objective-C source files. (Be sure to use
204
appropriate extensions to distinguish C++ source files: :file:`.cc` and
205
:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
207
However, 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
209
SWIG on the interface file and compile the resulting C/C++ file into your
212
.. XXX SWIG support is rough around the edges and largely untested!
214
This warning notwithstanding, options to SWIG can be currently passed like
218
ext_modules=[Extension('_foo', ['foo.i'],
219
swig_opts=['-modern', '-I../include'])],
223
Or on the commandline like this::
225
> python setup.py build_ext --swig-opts="-modern -I../include"
227
On some platforms, you can include non-source files that are processed by the
228
compiler and included in your extension. Currently, this just means Windows
229
message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
230
Visual C++. These will be compiled to binary resource (:file:`.res`) files and
231
linked into the executable.
237
Three optional arguments to :class:`~distutils.core.Extension` will help if
238
you need to specify include directories to search or preprocessor macros to
239
define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.
241
For example, if your extension requires header files in the :file:`include`
242
directory under your distribution root, use the ``include_dirs`` option::
244
Extension('foo', ['foo.c'], include_dirs=['include'])
246
You can specify absolute directories there; if you know that your extension will
247
only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
250
Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
252
You should avoid this sort of non-portable usage if you plan to distribute your
253
code: it's probably better to write C code like ::
255
#include <X11/Xlib.h>
257
If you need to include header files from some other Python extension, you can
258
take advantage of the fact that header files are installed in a consistent way
259
by the Distutils :command:`install_headers` command. For example, the Numerical
260
Python header files are installed (on a standard Unix installation) to
261
:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
262
according to your platform and Python installation.) Since the Python include
263
directory---\ :file:`/usr/local/include/python1.5` in this case---is always
264
included in the search path when building Python extensions, the best approach
265
is to write C code like ::
267
#include <Numerical/arrayobject.h>
269
If you must put the :file:`Numerical` include directory right into your header
270
search path, though, you can find that directory using the Distutils
271
:mod:`distutils.sysconfig` module::
273
from distutils.sysconfig import get_python_inc
274
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
276
Extension(..., include_dirs=[incdir]),
279
Even though this is quite portable---it will work on any Python installation,
280
regardless of platform---it's probably easier to just write your C code in the
283
You can define and undefine pre-processor macros with the ``define_macros`` and
284
``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
285
tuples, where ``name`` is the name of the macro to define (a string) and
286
``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
287
to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
288
most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
289
just a list of macros to undefine.
294
define_macros=[('NDEBUG', '1'),
295
('HAVE_STRFTIME', None)],
296
undef_macros=['HAVE_FOO', 'HAVE_BAR'])
298
is the equivalent of having this at the top of every C source file::
301
#define HAVE_STRFTIME
309
You can also specify the libraries to link against when building your extension,
310
and the directories to search for those libraries. The ``libraries`` option is
311
a list of libraries to link against, ``library_dirs`` is a list of directories
312
to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
313
directories to search for shared (dynamically loaded) libraries at run-time.
315
For example, if you need to link against libraries known to be in the standard
316
library search path on target systems ::
319
libraries=['gdbm', 'readline'])
321
If you need to link with libraries in a non-standard location, you'll have to
322
include the location in ``library_dirs``::
325
library_dirs=['/usr/X11R6/lib'],
326
libraries=['X11', 'Xt'])
328
(Again, this sort of non-portable construct should be avoided if you intend to
329
distribute your code.)
331
.. XXX Should mention clib libraries here or somewhere else!
337
There are still some other options which can be used to handle special cases.
339
The ``extra_objects`` option is a list of object files to be passed to the
340
linker. These files must not have extensions, as the default extension for the
343
``extra_compile_args`` and ``extra_link_args`` can be used to
344
specify additional command line options for the respective compiler and linker
347
``export_symbols`` is only useful on Windows. It can contain a list of
348
symbols (functions or variables) to be exported. This option is not needed when
349
building compiled extensions: Distutils will automatically add ``initmodule``
350
to the list of exported symbols.
352
The ``depends`` option is a list of files that the extension depends on
353
(for example header files). The build command will call the compiler on the
354
sources to rebuild extension if any on this files has been modified since the
357
Relationships between Distributions and Packages
358
================================================
360
A distribution may relate to packages in three specific ways:
362
#. It can require packages or modules.
364
#. It can provide packages or modules.
366
#. It can obsolete packages or modules.
368
These relationships can be specified using keyword arguments to the
369
:func:`distutils.core.setup` function.
371
Dependencies on other Python modules and packages can be specified by supplying
372
the *requires* keyword argument to :func:`setup`. The value must be a list of
373
strings. Each string specifies a package that is required, and optionally what
374
versions are sufficient.
376
To specify that any version of a module or package is required, the string
377
should consist entirely of the module or package name. Examples include
378
``'mymodule'`` and ``'xml.parsers.expat'``.
380
If specific versions are required, a sequence of qualifiers can be supplied in
381
parentheses. Each qualifier may consist of a comparison operator and a version
382
number. The accepted comparison operators are::
387
These can be combined by using multiple qualifiers separated by commas (and
388
optional whitespace). In this case, all of the qualifiers must be matched; a
389
logical AND is used to combine the evaluations.
391
Let's look at a bunch of examples:
393
+-------------------------+----------------------------------------------+
394
| Requires Expression | Explanation |
395
+=========================+==============================================+
396
| ``==1.0`` | Only version ``1.0`` is compatible |
397
+-------------------------+----------------------------------------------+
398
| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
399
| | is compatible, except ``1.5.1`` |
400
+-------------------------+----------------------------------------------+
402
Now that we can specify dependencies, we also need to be able to specify what we
403
provide that other distributions can require. This is done using the *provides*
404
keyword argument to :func:`setup`. The value for this keyword is a list of
405
strings, each of which names a Python module or package, and optionally
406
identifies the version. If the version is not specified, it is assumed to match
407
that of the distribution.
411
+---------------------+----------------------------------------------+
412
| Provides Expression | Explanation |
413
+=====================+==============================================+
414
| ``mypkg`` | Provide ``mypkg``, using the distribution |
416
+---------------------+----------------------------------------------+
417
| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of |
418
| | the distribution version |
419
+---------------------+----------------------------------------------+
421
A package can declare that it obsoletes other packages using the *obsoletes*
422
keyword argument. The value for this is similar to that of the *requires*
423
keyword: a list of strings giving module or package specifiers. Each specifier
424
consists of a module or package name optionally followed by one or more version
425
qualifiers. Version qualifiers are given in parentheses after the module or
428
The versions identified by the qualifiers are those that are obsoleted by the
429
distribution being described. If no qualifiers are given, all versions of the
430
named module or package are understood to be obsoleted.
432
.. _distutils-installing-scripts:
437
So far we have been dealing with pure and non-pure Python modules, which are
438
usually not run by themselves but imported by scripts.
440
Scripts are files containing Python source code, intended to be started from the
441
command line. Scripts don't require Distutils to do anything very complicated.
442
The only clever feature is that if the first line of the script starts with
443
``#!`` and contains the word "python", the Distutils will adjust the first line
444
to refer to the current interpreter location. By default, it is replaced with
445
the current interpreter location. The :option:`!--executable` (or :option:`!-e`)
446
option will allow the interpreter path to be explicitly overridden.
448
The ``scripts`` option simply is a list of files to be handled in this
449
way. From the PyXML setup script::
452
scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
455
.. versionchanged:: 2.7
456
All the scripts will also be added to the ``MANIFEST``
457
file if no template is provided. See :ref:`manifest`.
459
.. _distutils-installing-package-data:
461
Installing Package Data
462
=======================
464
Often, additional files need to be installed into a package. These files are
465
often data that's closely related to the package's implementation, or text files
466
containing documentation that might be of interest to programmers using the
467
package. These files are called :dfn:`package data`.
469
Package data can be added to packages using the ``package_data`` keyword
470
argument to the :func:`setup` function. The value must be a mapping from
471
package name to a list of relative path names that should be copied into the
472
package. The paths are interpreted as relative to the directory containing the
473
package (information from the ``package_dir`` mapping is used if appropriate);
474
that is, the files are expected to be part of the package in the source
475
directories. They may contain glob patterns as well.
477
The path names may contain directory portions; any necessary directories will be
478
created in the installation.
480
For example, if a package should contain a subdirectory with several data files,
481
the files can be arranged like this in the source tree::
493
The corresponding call to :func:`setup` might be::
497
package_dir={'mypkg': 'src/mypkg'},
498
package_data={'mypkg': ['data/*.dat']},
501
.. versionadded:: 2.4
503
.. versionchanged:: 2.7
504
All the files that match ``package_data`` will be added to the ``MANIFEST``
505
file if no template is provided. See :ref:`manifest`.
508
.. _distutils-additional-files:
510
Installing Additional Files
511
===========================
513
The ``data_files`` option can be used to specify additional files needed
514
by the module distribution: configuration files, message catalogs, data files,
515
anything which doesn't fit in the previous categories.
517
``data_files`` specifies a sequence of (*directory*, *files*) pairs in the
521
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
522
('config', ['cfg/data.cfg']),
523
('/etc/init.d', ['init-script'])]
526
Note that you can specify the directory names where the data files will be
527
installed, but you cannot rename the data files themselves.
529
Each (*directory*, *files*) pair in the sequence specifies the installation
530
directory and the files to install there. If *directory* is a relative path, it
531
is interpreted relative to the installation prefix (Python's ``sys.prefix`` for
532
pure-Python packages, ``sys.exec_prefix`` for packages that contain extension
533
modules). Each file name in *files* is interpreted relative to the
534
:file:`setup.py` script at the top of the package source distribution. No
535
directory information from *files* is used to determine the final location of
536
the installed file; only the name of the file is used.
538
You can specify the ``data_files`` options as a simple sequence of files
539
without specifying a target directory, but this is not recommended, and the
540
:command:`install` command will print a warning in this case. To install data
541
files directly in the target directory, an empty string should be given as the
544
.. versionchanged:: 2.7
545
All the files that match ``data_files`` will be added to the ``MANIFEST``
546
file if no template is provided. See :ref:`manifest`.
555
The setup script may include additional meta-data beyond the name and version.
556
This information includes:
558
+----------------------+---------------------------+-----------------+--------+
559
| Meta-Data | Description | Value | Notes |
560
+======================+===========================+=================+========+
561
| ``name`` | name of the package | short string | \(1) |
562
+----------------------+---------------------------+-----------------+--------+
563
| ``version`` | version of this release | short string | (1)(2) |
564
+----------------------+---------------------------+-----------------+--------+
565
| ``author`` | package author's name | short string | \(3) |
566
+----------------------+---------------------------+-----------------+--------+
567
| ``author_email`` | email address of the | email address | \(3) |
568
| | package author | | |
569
+----------------------+---------------------------+-----------------+--------+
570
| ``maintainer`` | package maintainer's name | short string | \(3) |
571
+----------------------+---------------------------+-----------------+--------+
572
| ``maintainer_email`` | email address of the | email address | \(3) |
573
| | package maintainer | | |
574
+----------------------+---------------------------+-----------------+--------+
575
| ``url`` | home page for the package | URL | \(1) |
576
+----------------------+---------------------------+-----------------+--------+
577
| ``description`` | short, summary | short string | |
578
| | description of the | | |
580
+----------------------+---------------------------+-----------------+--------+
581
| ``long_description`` | longer description of the | long string | \(5) |
583
+----------------------+---------------------------+-----------------+--------+
584
| ``download_url`` | location where the | URL | \(4) |
585
| | package may be downloaded | | |
586
+----------------------+---------------------------+-----------------+--------+
587
| ``classifiers`` | a list of classifiers | list of strings | \(4) |
588
+----------------------+---------------------------+-----------------+--------+
589
| ``platforms`` | a list of platforms | list of strings | |
590
+----------------------+---------------------------+-----------------+--------+
591
| ``license`` | license for the package | short string | \(6) |
592
+----------------------+---------------------------+-----------------+--------+
597
These fields are required.
600
It is recommended that versions take the form *major.minor[.patch[.sub]]*.
603
Either the author or the maintainer must be identified. If maintainer is
604
provided, distutils lists it as the author in :file:`PKG-INFO`.
607
These fields should not be used if your package is to be compatible with Python
608
versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
609
<https://pypi.python.org/pypi>`_.
612
The ``long_description`` field is used by PyPI when you are
613
:ref:`registering <package-register>` a package, to
614
:ref:`build its home page <package-display>`.
617
The ``license`` field is a text indicating the license covering the
618
package where the license is not a selection from the "License" Trove
619
classifiers. See the ``Classifier`` field. Notice that
620
there's a ``licence`` distribution option which is deprecated but still
621
acts as an alias for ``license``.
624
A single line of text, not more than 200 characters.
627
Multiple lines of plain text in reStructuredText format (see
628
http://docutils.sourceforge.net/).
633
None of the string values may be Unicode.
635
Encoding the version information is an art in itself. Python packages generally
636
adhere to the version format *major.minor[.patch][sub]*. The major number is 0
637
for initial, experimental releases of software. It is incremented for releases
638
that represent major milestones in a package. The minor number is incremented
639
when important new features are added to the package. The patch number
640
increments when bug-fix releases are made. Additional trailing version
641
information is sometimes used to indicate sub-releases. These are
642
"a1,a2,...,aN" (for alpha releases, where functionality and API may change),
643
"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
644
(for final pre-release release testing). Some examples:
647
the first, experimental release of a package
650
the second alpha release of the first patch version of 1.0
652
``classifiers`` are specified in a Python list::
656
'Development Status :: 4 - Beta',
657
'Environment :: Console',
658
'Environment :: Web Environment',
659
'Intended Audience :: End Users/Desktop',
660
'Intended Audience :: Developers',
661
'Intended Audience :: System Administrators',
662
'License :: OSI Approved :: Python Software Foundation License',
663
'Operating System :: MacOS :: MacOS X',
664
'Operating System :: Microsoft :: Windows',
665
'Operating System :: POSIX',
666
'Programming Language :: Python',
667
'Topic :: Communications :: Email',
668
'Topic :: Office/Business',
669
'Topic :: Software Development :: Bug Tracking',
673
If you wish to include classifiers in your :file:`setup.py` file and also wish
674
to remain backwards-compatible with Python releases prior to 2.2.3, then you can
675
include the following code fragment in your :file:`setup.py` before the
676
:func:`setup` call. ::
678
# patch distutils if it can't cope with the "classifiers" or
679
# "download_url" keywords
680
from sys import version
681
if version < '2.2.3':
682
from distutils.dist import DistributionMetadata
683
DistributionMetadata.classifiers = None
684
DistributionMetadata.download_url = None
687
.. _debug-setup-script:
689
Debugging the setup script
690
==========================
692
Sometimes things go wrong, and the setup script doesn't do what the developer
695
Distutils catches any exceptions when running the setup script, and print a
696
simple error message before the script is terminated. The motivation for this
697
behaviour is to not confuse administrators who don't know much about Python and
698
are trying to install a package. If they get a big long traceback from deep
699
inside the guts of Distutils, they may think the package or the Python
700
installation is broken because they don't read all the way down to the bottom
701
and see that it's a permission problem.
703
On the other hand, this doesn't help the developer to find the cause of the
704
failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set
705
to anything except an empty string, and distutils will now print detailed
706
information about what it is doing, dump the full traceback when an exception
707
occurs, and print the whole command line when an external program (like a C
added
removed
python-2.7.12-docs-html/_sources/distutils/setupscript.txt
