| ************************ |
| Writing the Setup Script |
| ************************ |
| |
| The setup script is the centre of all activity in building, distributing, and |
| installing modules using the Distutils. The main purpose of the setup script is |
| to describe your module distribution to the Distutils, so that the various |
| commands that operate on your modules do the right thing. As we saw in section |
n | :ref:`simple-example` above, the setup script consists mainly of a call to |
n | :ref:`distutils-simple-example` above, the setup script consists mainly of a call to |
| :func:`setup`, and most information supplied to the Distutils by the module |
| developer is supplied as keyword arguments to :func:`setup`. |
| |
| Here's a slightly more involved example, which we'll follow for the next couple |
| of sections: the Distutils' own setup script. (Keep in mind that although the |
| Distutils are included with Python 1.6 and later, they also have an independent |
| existence so that Python 1.5.2 users can use them to install other module |
| distributions. The Distutils' own setup script, shown here, is used to install |
| description='Python Distribution Utilities', |
| author='Greg Ward', |
| author_email='gward@python.net', |
| url='http://www.python.org/sigs/distutils-sig/', |
| packages=['distutils', 'distutils.command'], |
| ) |
| |
| There are only two differences between this and the trivial one-file |
n | distribution presented in section :ref:`simple-example`: more metadata, and the |
n | distribution presented in section :ref:`distutils-simple-example`: more metadata, and the |
| specification of pure Python modules by package, rather than by module. This is |
| important since the Distutils consist of a couple of dozen modules split into |
| (so far) two packages; an explicit list of every module would be tedious to |
| generate and difficult to maintain. For more information on the additional |
| meta-data, see section :ref:`meta-data`. |
| |
| Note that any pathnames (files or directories) supplied in the setup script |
| should be written using the Unix convention, i.e. slash-separated. The |
| Distutils will take care of converting this platform-neutral representation into |
| whatever is appropriate on your current platform before actually using the |
| pathname. This makes your setup script portable across operating systems, which |
| of course is one of the major goals of the Distutils. In this spirit, all |
n | pathnames in this document are slash-separated. (Mac OS 9 programmers should |
n | pathnames in this document are slash-separated. |
| keep in mind that the *absence* of a leading slash indicates a relative path, |
| the opposite of the Mac OS convention with colons.) |
| |
| This, of course, only applies to pathnames given to Distutils functions. If |
| you, for example, use standard Python functions such as :func:`glob.glob` or |
| :func:`os.listdir` to specify files, you should be careful to write portable |
| code instead of hardcoding path separators:: |
| |
| glob.glob(os.path.join('mydir', 'subdir', '*.html')) |
| os.listdir(os.path.join('mydir', 'subdir')) |
| .. _listing-modules: |
| |
| Listing individual modules |
| ========================== |
| |
| For a small module distribution, you might prefer to list all modules rather |
| than listing packages---especially the case of a single module that goes in the |
| "root package" (i.e., no package at all). This simplest case was shown in |
n | section :ref:`simple-example`; here is a slightly more involved example:: |
n | section :ref:`distutils-simple-example`; here is a slightly more involved example:: |
| |
| py_modules = ['mod1', 'pkg.mod2'] |
| |
| This describes two modules, one of them in the "root" package, the other in the |
| :mod:`pkg` package. Again, the default package/directory layout implies that |
| these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and |
| that :file:`pkg/__init__.py` exists as well. And again, you can override the |
| package/directory correspondence using the :option:`package_dir` option. |
| |
| Just as writing Python extension modules is a bit more complicated than writing |
| pure Python modules, describing them to the Distutils is a bit more complicated. |
| Unlike pure modules, it's not enough just to list modules or packages and expect |
| the Distutils to go out and find the right files; you have to specify the |
| extension name, source file(s), and any compile/link requirements (include |
| directories, libraries to link with, etc.). |
| |
n | .. % XXX read over this section |
n | .. XXX read over this section |
| |
| All of this is done through another keyword argument to :func:`setup`, the |
| :option:`ext_modules` option. :option:`ext_modules` is just a list of |
| :class:`Extension` instances, each of which describes a single extension module. |
| Suppose your distribution includes a single extension, called :mod:`foo` and |
| implemented by :file:`foo.c`. If no additional instructions to the |
| compiler/linker are needed, describing this extension is quite simple:: |
| |
| resulting object code are identical in both cases; the only difference is where |
| in the filesystem (and therefore where in Python's namespace hierarchy) the |
| resulting extension lives. |
| |
| If you have a number of extensions all in the same package (or all under the |
| same base package), use the :option:`ext_package` keyword argument to |
| :func:`setup`. For example, :: |
| |
n | setup(... |
n | setup(..., |
| ext_package='pkg', |
| ext_modules=[Extension('foo', ['foo.c']), |
| Extension('subpkg.bar', ['bar.c'])], |
| ) |
| |
| will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to |
| :mod:`pkg.subpkg.bar`. |
| |
| appropriate extensions to distinguish C++\ source files: :file:`.cc` and |
| :file:`.cpp` seem to be recognized by both Unix and Windows compilers.) |
| |
| However, you can also include SWIG interface (:file:`.i`) files in the list; the |
| :command:`build_ext` command knows how to deal with SWIG extensions: it will run |
| SWIG on the interface file and compile the resulting C/C++ file into your |
| extension. |
| |
n | **\*\*** SWIG support is rough around the edges and largely untested; especially |
n | **\*\*** SWIG support is rough around the edges and largely untested! **\*\*** |
| SWIG support for C++ extensions! Explain in more detail here when the interface |
| |
| firms up. **\*\*** |
| This warning notwithstanding, options to SWIG can be currently passed like |
| this:: |
| |
| setup(..., |
| ext_modules=[Extension('_foo', ['foo.i'], |
| swig_opts=['-modern', '-I../include'])], |
| py_modules=['foo'], |
| ) |
| |
| Or on the commandline like this:: |
| |
| > python setup.py build_ext --swig-opts="-modern -I../include" |
| |
| On some platforms, you can include non-source files that are processed by the |
| compiler and included in your extension. Currently, this just means Windows |
| message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for |
| Visual C++. These will be compiled to binary resource (:file:`.res`) files and |
| linked into the executable. |
| |
| |
| Some examples: |
| |
| +---------------------+----------------------------------------------+ |
| | Provides Expression | Explanation | |
| +=====================+==============================================+ |
| | ``mypkg`` | Provide ``mypkg``, using the distribution | |
| | | version | |
| +---------------------+----------------------------------------------+ |
n | | ``mypkg (1.1`` | Provide ``mypkg`` version 1.1, regardless of | |
n | | ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of | |
| | | the distribution version | |
| +---------------------+----------------------------------------------+ |
| |
| A package can declare that it obsoletes other packages using the *obsoletes* |
| keyword argument. The value for this is similar to that of the *requires* |
| keyword: a list of strings giving module or package specifiers. Each specifier |
| consists of a module or package name optionally followed by one or more version |
| qualifiers. Version qualifiers are given in parentheses after the module or |
| ``#!`` and contains the word "python", the Distutils will adjust the first line |
| to refer to the current interpreter location. By default, it is replaced with |
| the current interpreter location. The :option:`--executable` (or :option:`-e`) |
| option will allow the interpreter path to be explicitly overridden. |
| |
| The :option:`scripts` option simply is a list of files to be handled in this |
| way. From the PyXML setup script:: |
| |
n | setup(... |
n | setup(..., |
| scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] |
| ) |
| |
| |
| Installing Package Data |
| ======================= |
| |
| Often, additional files need to be installed into a package. These files are |
| |
| The :option:`data_files` option can be used to specify additional files needed |
| by the module distribution: configuration files, message catalogs, data files, |
| anything which doesn't fit in the previous categories. |
| |
| :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the |
| following way:: |
| |
n | setup(... |
n | setup(..., |
| data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), |
| ('config', ['cfg/data.cfg']), |
| ('/etc/init.d', ['init-script'])] |
| ) |
| |
| Note that you can specify the directory names where the data files will be |
| installed, but you cannot rename the data files themselves. |
| |
| | ``long_description`` | longer description of the | long string | | |
| | | package | | | |
| +----------------------+---------------------------+-----------------+--------+ |
| | ``download_url`` | location where the | URL | \(4) | |
| | | package may be downloaded | | | |
| +----------------------+---------------------------+-----------------+--------+ |
| | ``classifiers`` | a list of classifiers | list of strings | \(4) | |
| +----------------------+---------------------------+-----------------+--------+ |
n | | ``platforms`` | a list of platforms | list of strings | | |
| +----------------------+---------------------------+-----------------+--------+ |
| |
| Notes: |
| |
| (1) |
| These fields are required. |
| |
| (2) |
| It is recommended that versions take the form *major.minor[.patch[.sub]]*. |
| |
| (3) |
| Either the author or the maintainer must be identified. |
| |
| (4) |
| These fields should not be used if your package is to be compatible with Python |
| versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website |
n | <http://www.python.org/pypi>`_. |
n | <http://pypi.python.org/pypi>`_. |
| |
| 'short string' |
| A single line of text, not more than 200 characters. |
| |
| 'long string' |
| Multiple lines of plain text in reStructuredText format (see |
n | `<http://docutils.sf.net/>`_). |
n | http://docutils.sf.net/). |
| |
| 'list of strings' |
| See below. |
| |
| None of the string values may be Unicode. |
| |
| Encoding the version information is an art in itself. Python packages generally |
| adhere to the version format *major.minor[.patch][sub]*. The major number is 0 |
| 0.1.0 |
| the first, experimental release of a package |
| |
| 1.0.1a2 |
| the second alpha release of the first patch version of 1.0 |
| |
| :option:`classifiers` are specified in a python list:: |
| |
t | setup(... |
t | setup(..., |
| classifiers=[ |
| 'Development Status :: 4 - Beta', |
| 'Environment :: Console', |
| 'Environment :: Web Environment', |
| 'Intended Audience :: End Users/Desktop', |
| 'Intended Audience :: Developers', |
| 'Intended Audience :: System Administrators', |
| 'License :: OSI Approved :: Python Software Foundation License', |