diff options
Diffstat (limited to 'Doc/dist/dist.tex')
| -rw-r--r-- | Doc/dist/dist.tex | 3811 |
1 files changed, 0 insertions, 3811 deletions
diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex deleted file mode 100644 index a33227f..0000000 --- a/Doc/dist/dist.tex +++ /dev/null @@ -1,3811 +0,0 @@ -\documentclass{manual} -\usepackage{distutils} - -% $Id$ - -% TODO -% Document extension.read_setup_file -% Document build_clib command -% - -\title{Distributing Python Modules} - -\input{boilerplate} - -\author{Greg Ward\\ - Anthony Baxter} -\authoraddress{ - \strong{Python Software Foundation}\\ - Email: \email{distutils-sig@python.org} -} - -\makeindex -\makemodindex - -\begin{document} - -\maketitle - -\input{copyright} - -\begin{abstract} - \noindent - This document describes the Python Distribution Utilities - (``Distutils'') from the module developer's point of view, describing - how to use the Distutils to make Python modules and extensions easily - available to a wider audience with very little overhead for - build/release/install mechanics. -\end{abstract} - -% The ugly "%begin{latexonly}" pseudo-environment suppresses the table -% of contents for HTML generation. -% -%begin{latexonly} -\tableofcontents -%end{latexonly} - - -\chapter{An Introduction to Distutils} -\label{intro} - -This document covers using the Distutils to distribute your Python -modules, concentrating on the role of developer/distributor: if -you're looking for information on installing Python modules, you -should refer to the \citetitle[../inst/inst.html]{Installing Python -Modules} manual. - - -\section{Concepts \& Terminology} -\label{concepts} - -Using the Distutils is quite simple, both for module developers and for -users/administrators installing third-party modules. As a developer, -your responsibilities (apart from writing solid, well-documented and -well-tested code, of course!) are: -\begin{itemize} -\item write a setup script (\file{setup.py} by convention) -\item (optional) write a setup configuration file -\item create a source distribution -\item (optional) create one or more built (binary) distributions -\end{itemize} -Each of these tasks is covered in this document. - -Not all module developers have access to a multitude of platforms, so -it's not always feasible to expect them to create a multitude of built -distributions. It is hoped that a class of intermediaries, called -\emph{packagers}, will arise to address this need. Packagers will take -source distributions released by module developers, build them on one or -more platforms, and release the resulting built distributions. Thus, -users on the most popular platforms will be able to install most popular -Python module distributions in the most natural way for their platform, -without having to run a single setup script or compile a line of code. - - -\section{A Simple Example} -\label{simple-example} - -The setup script is usually quite simple, although since it's written -in Python, there are no arbitrary limits to what you can do with it, -though you should be careful about putting arbitrarily expensive -operations in your setup script. Unlike, say, Autoconf-style configure -scripts, the setup script may be run multiple times in the course of -building and installing your module distribution. - -If all you want to do is distribute a module called \module{foo}, -contained in a file \file{foo.py}, then your setup script can be as -simple as this: - -\begin{verbatim} -from distutils.core import setup -setup(name='foo', - version='1.0', - py_modules=['foo'], - ) -\end{verbatim} - -Some observations: -\begin{itemize} -\item most information that you supply to the Distutils is supplied as - keyword arguments to the \function{setup()} function -\item those keyword arguments fall into two categories: package - metadata (name, version number) and information about what's in the - package (a list of pure Python modules, in this case) -\item modules are specified by module name, not filename (the same will - hold true for packages and extensions) -\item it's recommended that you supply a little more metadata, in - particular your name, email address and a URL for the project - (see section~\ref{setup-script} for an example) -\end{itemize} - -To create a source distribution for this module, you would create a -setup script, \file{setup.py}, containing the above code, and run: - -\begin{verbatim} -python setup.py sdist -\end{verbatim} - -which will create an archive file (e.g., tarball on \UNIX, ZIP file on -Windows) containing your setup script \file{setup.py}, and your module -\file{foo.py}. The archive file will be named \file{foo-1.0.tar.gz} (or -\file{.zip}), and will unpack into a directory \file{foo-1.0}. - -If an end-user wishes to install your \module{foo} module, all she has -to do is download \file{foo-1.0.tar.gz} (or \file{.zip}), unpack it, -and---from the \file{foo-1.0} directory---run - -\begin{verbatim} -python setup.py install -\end{verbatim} - -which will ultimately copy \file{foo.py} to the appropriate directory -for third-party modules in their Python installation. - -This simple example demonstrates some fundamental concepts of the -Distutils. First, both developers and installers have the same basic -user interface, i.e. the setup script. The difference is which -Distutils \emph{commands} they use: the \command{sdist} command is -almost exclusively for module developers, while \command{install} is -more often for installers (although most developers will want to install -their own code occasionally). - -If you want to make things really easy for your users, you can create -one or more built distributions for them. For instance, if you are -running on a Windows machine, and want to make things easy for other -Windows users, you can create an executable installer (the most -appropriate type of built distribution for this platform) with the -\command{bdist\_wininst} command. For example: - -\begin{verbatim} -python setup.py bdist_wininst -\end{verbatim} - -will create an executable installer, \file{foo-1.0.win32.exe}, in the -current directory. - -Other useful built distribution formats are RPM, implemented by the -\command{bdist\_rpm} command, Solaris \program{pkgtool} -(\command{bdist\_pkgtool}), and HP-UX \program{swinstall} -(\command{bdist_sdux}). For example, the following command will -create an RPM file called \file{foo-1.0.noarch.rpm}: - -\begin{verbatim} -python setup.py bdist_rpm -\end{verbatim} - -(The \command{bdist\_rpm} command uses the \command{rpm} executable, -therefore this has to be run on an RPM-based system such as Red Hat -Linux, SuSE Linux, or Mandrake Linux.) - -You can find out what distribution formats are available at any time by -running - -\begin{verbatim} -python setup.py bdist --help-formats -\end{verbatim} - - -\section{General Python terminology} -\label{python-terms} - -If you're reading this document, you probably have a good idea of what -modules, extensions, and so forth are. Nevertheless, just to be sure -that everyone is operating from a common starting point, we offer the -following glossary of common Python terms: -\begin{description} -\item[module] the basic unit of code reusability in Python: a block of - code imported by some other code. Three types of modules concern us - here: pure Python modules, extension modules, and packages. - -\item[pure Python module] a module written in Python and contained in a - single \file{.py} file (and possibly associated \file{.pyc} and/or - \file{.pyo} files). Sometimes referred to as a ``pure module.'' - -\item[extension module] a module written in the low-level language of - the Python implementation: C/\Cpp{} for Python, Java for Jython. - Typically contained in a single dynamically loadable pre-compiled - file, e.g. a shared object (\file{.so}) file for Python extensions on - \UNIX, a DLL (given the \file{.pyd} extension) for Python extensions - on Windows, or a Java class file for Jython extensions. (Note that - currently, the Distutils only handles C/\Cpp{} extensions for Python.) - -\item[package] a module that contains other modules; typically contained - in a directory in the filesystem and distinguished from other - directories by the presence of a file \file{\_\_init\_\_.py}. - -\item[root package] the root of the hierarchy of packages. (This isn't - really a package, since it doesn't have an \file{\_\_init\_\_.py} - file. But we have to call it something.) The vast majority of the - standard library is in the root package, as are many small, standalone - third-party modules that don't belong to a larger module collection. - Unlike regular packages, modules in the root package can be found in - many directories: in fact, every directory listed in \code{sys.path} - contributes modules to the root package. -\end{description} - - -\section{Distutils-specific terminology} -\label{distutils-term} - -The following terms apply more specifically to the domain of -distributing Python modules using the Distutils: -\begin{description} -\item[module distribution] a collection of Python modules distributed - together as a single downloadable resource and meant to be installed - \emph{en masse}. Examples of some well-known module distributions are - Numeric Python, PyXML, PIL (the Python Imaging Library), or - mxBase. (This would be called a \emph{package}, except that term - is already taken in the Python context: a single module distribution - may contain zero, one, or many Python packages.) - -\item[pure module distribution] a module distribution that contains only - pure Python modules and packages. Sometimes referred to as a ``pure - distribution.'' - -\item[non-pure module distribution] a module distribution that contains - at least one extension module. Sometimes referred to as a ``non-pure - distribution.'' - -\item[distribution root] the top-level directory of your source tree (or - source distribution); the directory where \file{setup.py} exists. Generally - \file{setup.py} will be run from this directory. -\end{description} - - -\chapter{Writing the Setup Script} -\label{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~\ref{simple-example} above, -the setup script consists mainly of a call to \function{setup()}, and -most information supplied to the Distutils by the module developer is -supplied as keyword arguments to \function{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 the package into Python 1.5.2.) - -\begin{verbatim} -#!/usr/bin/env python - -from distutils.core import setup - -setup(name='Distutils', - version='1.0', - description='Python Distribution Utilities', - author='Greg Ward', - author_email='gward@python.net', - url='http://www.python.org/sigs/distutils-sig/', - packages=['distutils', 'distutils.command'], - ) -\end{verbatim} - -There are only two differences between this and the trivial one-file -distribution presented in section~\ref{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 pathnames in -this document are slash-separated. (Mac OS 9 programmers should keep in -mind that the \emph{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 -\function{glob.glob()} or \function{os.listdir()} to specify files, you -should be careful to write portable code instead of hardcoding path -separators: - -\begin{verbatim} - glob.glob(os.path.join('mydir', 'subdir', '*.html')) - os.listdir(os.path.join('mydir', 'subdir')) -\end{verbatim} - - -\section{Listing whole packages} -\label{listing-packages} - -The \option{packages} option tells the Distutils to process (build, -distribute, install, etc.) all pure Python modules found in each package -mentioned in the \option{packages} list. In order to do this, of -course, there has to be a correspondence between package names and -directories in the filesystem. The default correspondence is the most -obvious one, i.e. package \module{distutils} is found in the directory -\file{distutils} relative to the distribution root. Thus, when you say -\code{packages = ['foo']} in your setup script, you are promising that -the Distutils will find a file \file{foo/\_\_init\_\_.py} (which might -be spelled differently on your system, but you get the idea) relative to -the directory where your setup script lives. If you break this -promise, the Distutils will issue a warning but still process the broken -package anyways. - -If you use a different convention to lay out your source directory, -that's no problem: you just have to supply the \option{package\_dir} -option to tell the Distutils about your convention. For example, say -you keep all Python source under \file{lib}, so that modules in the -``root package'' (i.e., not in any package at all) are in -\file{lib}, modules in the \module{foo} package are in \file{lib/foo}, -and so forth. Then you would put - -\begin{verbatim} -package_dir = {'': 'lib'} -\end{verbatim} - -in your setup script. The keys to this dictionary are package names, -and an empty package name stands for the root package. The values are -directory names relative to your distribution root. In this case, when -you say \code{packages = ['foo']}, you are promising that the file -\file{lib/foo/\_\_init\_\_.py} exists. - -Another possible convention is to put the \module{foo} package right in -\file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This -would be written in the setup script as - -\begin{verbatim} -package_dir = {'foo': 'lib'} -\end{verbatim} - -A \code{\var{package}: \var{dir}} entry in the \option{package\_dir} -dictionary implicitly applies to all packages below \var{package}, so -the \module{foo.bar} case is automatically handled here. In this -example, having \code{packages = ['foo', 'foo.bar']} tells the Distutils -to look for \file{lib/\_\_init\_\_.py} and -\file{lib/bar/\_\_init\_\_.py}. (Keep in mind that although -\option{package\_dir} applies recursively, you must explicitly list all -packages in \option{packages}: the Distutils will \emph{not} recursively -scan your source tree looking for any directory with an -\file{\_\_init\_\_.py} file.) - - -\section{Listing individual modules} -\label{listing-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 section~\ref{simple-example}; here is a -slightly more involved example: - -\begin{verbatim} -py_modules = ['mod1', 'pkg.mod2'] -\end{verbatim} - -This describes two modules, one of them in the ``root'' package, the -other in the \module{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. - - -\section{Describing extension modules} -\label{describing-extensions} - -% XXX read over this section -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.). - -All of this is done through another keyword argument to -\function{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 \module{foo} and implemented by \file{foo.c}. If no -additional instructions to the compiler/linker are needed, describing -this extension is quite simple: - -\begin{verbatim} -Extension('foo', ['foo.c']) -\end{verbatim} - -The \class{Extension} class can be imported from -\module{distutils.core} along with \function{setup()}. Thus, the setup -script for a module distribution that contains only this one extension -and nothing else might be: - -\begin{verbatim} -from distutils.core import setup, Extension -setup(name='foo', - version='1.0', - ext_modules=[Extension('foo', ['foo.c'])], - ) -\end{verbatim} - -The \class{Extension} class (actually, the underlying extension-building -machinery implemented by the \command{build\_ext} command) supports a -great deal of flexibility in describing Python extensions, which is -explained in the following sections. - - -\subsection{Extension names and packages} - -The first argument to the \class{Extension} constructor is always the -name of the extension, including any package names. For example, - -\begin{verbatim} -Extension('foo', ['src/foo1.c', 'src/foo2.c']) -\end{verbatim} - -describes an extension that lives in the root package, while - -\begin{verbatim} -Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) -\end{verbatim} - -describes the same extension in the \module{pkg} package. The source -files and 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 \function{setup()}. For example, - -\begin{verbatim} -setup(... - ext_package='pkg', - ext_modules=[Extension('foo', ['foo.c']), - Extension('subpkg.bar', ['bar.c'])], - ) -\end{verbatim} - -will compile \file{foo.c} to the extension \module{pkg.foo}, and -\file{bar.c} to \module{pkg.subpkg.bar}. - - -\subsection{Extension source files} - -The second argument to the \class{Extension} constructor is a list of -source files. Since the Distutils currently only support C, \Cpp, and -Objective-C extensions, these are normally C/\Cpp/Objective-C source -files. (Be sure to use appropriate extensions to distinguish \Cpp\ -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/\Cpp{} file into your extension. - -\XXX{SWIG support is rough around the edges and largely untested!} - -This warning notwithstanding, options to SWIG can be currently passed -like this: - -\begin{verbatim} -setup(... - ext_modules=[Extension('_foo', ['foo.i'], - swig_opts=['-modern', '-I../include'])], - py_modules=['foo'], - ) -\end{verbatim} - -Or on the commandline like this: - -\begin{verbatim} -> python setup.py build_ext --swig-opts="-modern -I../include" -\end{verbatim} - -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 \Cpp. These will be compiled to binary resource -(\file{.res}) files and linked into the executable. - - -\subsection{Preprocessor options} - -Three optional arguments to \class{Extension} will help if you need to -specify include directories to search or preprocessor macros to -define/undefine: \code{include\_dirs}, \code{define\_macros}, and -\code{undef\_macros}. - -For example, if your extension requires header files in the -\file{include} directory under your distribution root, use the -\code{include\_dirs} option: - -\begin{verbatim} -Extension('foo', ['foo.c'], include_dirs=['include']) -\end{verbatim} - -You can specify absolute directories there; if you know that your -extension will only be built on \UNIX{} systems with X11R6 installed to -\file{/usr}, you can get away with - -\begin{verbatim} -Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) -\end{verbatim} - -You should avoid this sort of non-portable usage if you plan to -distribute your code: it's probably better to write C code like -\begin{verbatim} -#include <X11/Xlib.h> -\end{verbatim} - -If you need to include header files from some other Python extension, -you can take advantage of the fact that header files are installed in a -consistent way by the Distutils \command{install\_header} command. For -example, the Numerical Python header files are installed (on a standard -\UNIX{} installation) to \file{/usr/local/include/python1.5/Numerical}. -(The exact location will differ according to your platform and Python -installation.) Since the Python include -directory---\file{/usr/local/include/python1.5} in this case---is always -included in the search path when building Python extensions, the best -approach is to write C code like -\begin{verbatim} -#include <Numerical/arrayobject.h> -\end{verbatim} -If you must put the \file{Numerical} include directory right into your -header search path, though, you can find that directory using the -Distutils \refmodule{distutils.sysconfig} module: - -\begin{verbatim} -from distutils.sysconfig import get_python_inc -incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') -setup(..., - Extension(..., include_dirs=[incdir]), - ) -\end{verbatim} - -Even though this is quite portable---it will work on any Python -installation, regardless of platform---it's probably easier to just -write your C code in the sensible way. - -You can define and undefine pre-processor macros with the -\code{define\_macros} and \code{undef\_macros} options. -\code{define\_macros} takes a list of \code{(name, value)} tuples, where -\code{name} is the name of the macro to define (a string) and -\code{value} is its value: either a string or \code{None}. (Defining a -macro \code{FOO} to \code{None} is the equivalent of a bare -\code{\#define FOO} in your C source: with most compilers, this sets -\code{FOO} to the string \code{1}.) \code{undef\_macros} is just -a list of macros to undefine. - -For example: - -\begin{verbatim} -Extension(..., - define_macros=[('NDEBUG', '1'), - ('HAVE_STRFTIME', None)], - undef_macros=['HAVE_FOO', 'HAVE_BAR']) -\end{verbatim} - -is the equivalent of having this at the top of every C source file: - -\begin{verbatim} -#define NDEBUG 1 -#define HAVE_STRFTIME -#undef HAVE_FOO -#undef HAVE_BAR -\end{verbatim} - - -\subsection{Library options} - -You can also specify the libraries to link against when building your -extension, and the directories to search for those libraries. The -\code{libraries} option is a list of libraries to link against, -\code{library\_dirs} is a list of directories to search for libraries at -link-time, and \code{runtime\_library\_dirs} is a list of directories to -search for shared (dynamically loaded) libraries at run-time. - -For example, if you need to link against libraries known to be in the -standard library search path on target systems - -\begin{verbatim} -Extension(..., - libraries=['gdbm', 'readline']) -\end{verbatim} - -If you need to link with libraries in a non-standard location, you'll -have to include the location in \code{library\_dirs}: - -\begin{verbatim} -Extension(..., - library_dirs=['/usr/X11R6/lib'], - libraries=['X11', 'Xt']) -\end{verbatim} - -(Again, this sort of non-portable construct should be avoided if you -intend to distribute your code.) - -\XXX{Should mention clib libraries here or somewhere else!} - -\subsection{Other options} - -There are still some other options which can be used to handle special -cases. - -The \option{extra\_objects} option is a list of object files to be passed -to the linker. These files must not have extensions, as the default -extension for the compiler is used. - -\option{extra\_compile\_args} and \option{extra\_link\_args} can be used -to specify additional command line options for the respective compiler and -linker command lines. - -\option{export\_symbols} is only useful on Windows. It can contain a list -of symbols (functions or variables) to be exported. This option -is not needed when building compiled extensions: Distutils -will automatically add \code{initmodule} -to the list of exported symbols. - -\section{Relationships between Distributions and Packages} - -A distribution may relate to packages in three specific ways: - -\begin{enumerate} - \item It can require packages or modules. - - \item It can provide packages or modules. - - \item It can obsolete packages or modules. -\end{enumerate} - -These relationships can be specified using keyword arguments to the -\function{distutils.core.setup()} function. - -Dependencies on other Python modules and packages can be specified by -supplying the \var{requires} keyword argument to \function{setup()}. -The value must be a list of strings. Each string specifies a package -that is required, and optionally what versions are sufficient. - -To specify that any version of a module or package is required, the -string should consist entirely of the module or package name. -Examples include \code{'mymodule'} and \code{'xml.parsers.expat'}. - -If specific versions are required, a sequence of qualifiers can be -supplied in parentheses. Each qualifier may consist of a comparison -operator and a version number. The accepted comparison operators are: - -\begin{verbatim} -< > == -<= >= != -\end{verbatim} - -These can be combined by using multiple qualifiers separated by commas -(and optional whitespace). In this case, all of the qualifiers must -be matched; a logical AND is used to combine the evaluations. - -Let's look at a bunch of examples: - -\begin{tableii}{l|l}{code}{Requires Expression}{Explanation} - \lineii{==1.0} {Only version \code{1.0} is compatible} - \lineii{>1.0, !=1.5.1, <2.0} {Any version after \code{1.0} and before - \code{2.0} is compatible, except - \code{1.5.1}} -\end{tableii} - -Now that we can specify dependencies, we also need to be able to -specify what we provide that other distributions can require. This is -done using the \var{provides} keyword argument to \function{setup()}. -The value for this keyword is a list of strings, each of which names a -Python module or package, and optionally identifies the version. If -the version is not specified, it is assumed to match that of the -distribution. - -Some examples: - -\begin{tableii}{l|l}{code}{Provides Expression}{Explanation} - \lineii{mypkg} {Provide \code{mypkg}, using the distribution version} - \lineii{mypkg (1.1)} {Provide \code{mypkg} version 1.1, regardless of the - distribution version} -\end{tableii} - -A package can declare that it obsoletes other packages using the -\var{obsoletes} keyword argument. The value for this is similar to -that of the \var{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 package name. - -The versions identified by the qualifiers are those that are obsoleted -by the distribution being described. If no qualifiers are given, all -versions of the named module or package are understood to be -obsoleted. - - -\section{Installing Scripts} - -So far we have been dealing with pure and non-pure Python modules, -which are usually not run by themselves but imported by scripts. - -Scripts are files containing Python source code, intended to be -started from the command line. Scripts don't require Distutils to do -anything very complicated. The only clever feature is that if the -first line of the script starts with \code{\#!} 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 \longprogramopt{executable} (or -\programopt{-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: - -\begin{verbatim} -setup(... - scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] - ) -\end{verbatim} - - -\section{Installing Package Data} - -Often, additional files need to be installed into a package. These -files are often data that's closely related to the package's -implementation, or text files containing documentation that might be -of interest to programmers using the package. These files are called -\dfn{package data}. - -Package data can be added to packages using the \code{package_data} -keyword argument to the \function{setup()} function. The value must -be a mapping from package name to a list of relative path names that -should be copied into the package. The paths are interpreted as -relative to the directory containing the package (information from the -\code{package_dir} mapping is used if appropriate); that is, the files -are expected to be part of the package in the source directories. -They may contain glob patterns as well. - -The path names may contain directory portions; any necessary -directories will be created in the installation. - -For example, if a package should contain a subdirectory with several -data files, the files can be arranged like this in the source tree: - -\begin{verbatim} -setup.py -src/ - mypkg/ - __init__.py - module.py - data/ - tables.dat - spoons.dat - forks.dat -\end{verbatim} - -The corresponding call to \function{setup()} might be: - -\begin{verbatim} -setup(..., - packages=['mypkg'], - package_dir={'mypkg': 'src/mypkg'}, - package_data={'mypkg': ['data/*.dat']}, - ) -\end{verbatim} - - -\versionadded{2.4} - - -\section{Installing Additional Files} - -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 (\var{directory}, -\var{files}) pairs in the following way: - -\begin{verbatim} -setup(... - data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), - ('config', ['cfg/data.cfg']), - ('/etc/init.d', ['init-script'])] - ) -\end{verbatim} - -Note that you can specify the directory names where the data files -will be installed, but you cannot rename the data files themselves. - -Each (\var{directory}, \var{files}) pair in the sequence specifies the -installation directory and the files to install there. If -\var{directory} is a relative path, it is interpreted relative to the -installation prefix (Python's \code{sys.prefix} for pure-Python -packages, \code{sys.exec_prefix} for packages that contain extension -modules). Each file name in \var{files} is interpreted relative to -the \file{setup.py} script at the top of the package source -distribution. No directory information from \var{files} is used to -determine the final location of the installed file; only the name of -the file is used. - -You can specify the \option{data\_files} options as a simple sequence -of files without specifying a target directory, but this is not recommended, -and the \command{install} command will print a warning in this case. -To install data files directly in the target directory, an empty -string should be given as the directory. - -\section{Additional meta-data} -\label{meta-data} - -The setup script may include additional meta-data beyond the name and -version. This information includes: - -\begin{tableiv}{l|l|l|c}{code}% - {Meta-Data}{Description}{Value}{Notes} - \lineiv{name}{name of the package} - {short string}{(1)} - \lineiv{version}{version of this release} - {short string}{(1)(2)} - \lineiv{author}{package author's name} - {short string}{(3)} - \lineiv{author_email}{email address of the package author} - {email address}{(3)} - \lineiv{maintainer}{package maintainer's name} - {short string}{(3)} - \lineiv{maintainer_email}{email address of the package maintainer} - {email address}{(3)} - \lineiv{url}{home page for the package} - {URL}{(1)} - \lineiv{description}{short, summary description of the package} - {short string}{} - \lineiv{long_description}{longer description of the package} - {long string}{} - \lineiv{download_url}{location where the package may be downloaded} - {URL}{(4)} - \lineiv{classifiers}{a list of classifiers} - {list of strings}{(4)} -\end{tableiv} - -\noindent Notes: -\begin{description} -\item[(1)] These fields are required. -\item[(2)] It is recommended that versions take the form - \emph{major.minor\optional{.patch\optional{.sub}}}. -\item[(3)] Either the author or the maintainer must be identified. -\item[(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 \ulink{PyPI website}{http://www.python.org/pypi}. - -\item['short string'] A single line of text, not more than 200 characters. -\item['long string'] Multiple lines of plain text in reStructuredText - format (see \url{http://docutils.sf.net/}). -\item['list of strings'] See below. -\end{description} - -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 -\emph{major.minor\optional{.patch}\optional{sub}}. The major number is -0 for -initial, experimental releases of software. It is incremented for -releases that represent major milestones in a package. The minor -number is incremented when important new features are added to the -package. The patch number increments when bug-fix releases are -made. Additional trailing version information is sometimes used to -indicate sub-releases. These are "a1,a2,...,aN" (for alpha releases, -where functionality and API may change), "b1,b2,...,bN" (for beta -releases, which only fix bugs) and "pr1,pr2,...,prN" (for final -pre-release release testing). Some examples: - -\begin{description} -\item[0.1.0] the first, experimental release of a package -\item[1.0.1a2] the second alpha release of the first patch version of 1.0 -\end{description} - -\option{classifiers} are specified in a python list: - -\begin{verbatim} -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', - 'Operating System :: MacOS :: MacOS X', - 'Operating System :: Microsoft :: Windows', - 'Operating System :: POSIX', - 'Programming Language :: Python', - 'Topic :: Communications :: Email', - 'Topic :: Office/Business', - 'Topic :: Software Development :: Bug Tracking', - ], - ) -\end{verbatim} - -If you wish to include classifiers in your \file{setup.py} file and also -wish to remain backwards-compatible with Python releases prior to 2.2.3, -then you can include the following code fragment in your \file{setup.py} -before the \function{setup()} call. - -\begin{verbatim} -# patch distutils if it can't cope with the "classifiers" or -# "download_url" keywords -from sys import version -if version < '2.2.3': - from distutils.dist import DistributionMetadata - DistributionMetadata.classifiers = None - DistributionMetadata.download_url = None -\end{verbatim} - - -\section{Debugging the setup script} - -Sometimes things go wrong, and the setup script doesn't do what the -developer wants. - -Distutils catches any exceptions when running the setup script, and -print a simple error message before the script is terminated. The -motivation for this behaviour is to not confuse administrators who -don't know much about Python and are trying to install a package. If -they get a big long traceback from deep inside the guts of Distutils, -they may think the package or the Python installation is broken -because they don't read all the way down to the bottom and see that -it's a permission problem. - -On the other hand, this doesn't help the developer to find the cause -of the failure. For this purpose, the DISTUTILS_DEBUG environment -variable can be set to anything except an empty string, and distutils -will now print detailed information what it is doing, and prints the -full traceback in case an exception occurs. - -\chapter{Writing the Setup Configuration File} -\label{setup-config} - -Often, it's not possible to write down everything needed to build a -distribution \emph{a priori}: you may need to get some information from -the user, or from the user's system, in order to proceed. As long as -that information is fairly simple---a list of directories to search for -C header files or libraries, for example---then providing a -configuration file, \file{setup.cfg}, for users to edit is a cheap and -easy way to solicit it. Configuration files also let you provide -default values for any command option, which the installer can then -override either on the command-line or by editing the config file. - -% (If you have more advanced needs, such as determining which extensions -% to build based on what capabilities are present on the target system, -% then you need the Distutils ``auto-configuration'' facility. This -% started to appear in Distutils 0.9 but, as of this writing, isn't mature -% or stable enough yet for real-world use.) - -The setup configuration file is a useful middle-ground between the setup -script---which, ideally, would be opaque to installers\footnote{This - ideal probably won't be achieved until auto-configuration is fully - supported by the Distutils.}---and the command-line to the setup -script, which is outside of your control and entirely up to the -installer. In fact, \file{setup.cfg} (and any other Distutils -configuration files present on the target system) are processed after -the contents of the setup script, but before the command-line. This has -several useful consequences: -\begin{itemize} -\item installers can override some of what you put in \file{setup.py} by - editing \file{setup.cfg} -\item you can provide non-standard defaults for options that are not - easily set in \file{setup.py} -\item installers can override anything in \file{setup.cfg} using the - command-line options to \file{setup.py} -\end{itemize} - -The basic syntax of the configuration file is simple: - -\begin{verbatim} -[command] -option=value -... -\end{verbatim} - -where \var{command} is one of the Distutils commands (e.g. -\command{build\_py}, \command{install}), and \var{option} is one of -the options that command supports. Any number of options can be -supplied for each command, and any number of command sections can be -included in the file. Blank lines are ignored, as are comments, which -run from a \character{\#} character until the end of the line. Long -option values can be split across multiple lines simply by indenting -the continuation lines. - -You can find out the list of options supported by a particular command -with the universal \longprogramopt{help} option, e.g. - -\begin{verbatim} -> python setup.py --help build_ext -[...] -Options for 'build_ext' command: - --build-lib (-b) directory for compiled extension modules - --build-temp (-t) directory for temporary files (build by-products) - --inplace (-i) ignore build-lib and put compiled extensions into the - source directory alongside your pure Python modules - --include-dirs (-I) list of directories to search for header files - --define (-D) C preprocessor macros to define - --undef (-U) C preprocessor macros to undefine - --swig-opts list of SWIG command line options -[...] -\end{verbatim} - -Note that an option spelled \longprogramopt{foo-bar} on the command-line -is spelled \option{foo\_bar} in configuration files. - -For example, say you want your extensions to be built -``in-place''---that is, you have an extension \module{pkg.ext}, and you -want the compiled extension file (\file{ext.so} on \UNIX, say) to be put -in the same source directory as your pure Python modules -\module{pkg.mod1} and \module{pkg.mod2}. You can always use the -\longprogramopt{inplace} option on the command-line to ensure this: - -\begin{verbatim} -python setup.py build_ext --inplace -\end{verbatim} - -But this requires that you always specify the \command{build\_ext} -command explicitly, and remember to provide \longprogramopt{inplace}. -An easier way is to ``set and forget'' this option, by encoding it in -\file{setup.cfg}, the configuration file for this distribution: - -\begin{verbatim} -[build_ext] -inplace=1 -\end{verbatim} - -This will affect all builds of this module distribution, whether or not -you explicitly specify \command{build\_ext}. If you include -\file{setup.cfg} in your source distribution, it will also affect -end-user builds---which is probably a bad idea for this option, since -always building extensions in-place would break installation of the -module distribution. In certain peculiar cases, though, modules are -built right in their installation directory, so this is conceivably a -useful ability. (Distributing extensions that expect to be built in -their installation directory is almost always a bad idea, though.) - -Another example: certain commands take a lot of options that don't -change from run to run; for example, \command{bdist\_rpm} needs to know -everything required to generate a ``spec'' file for creating an RPM -distribution. Some of this information comes from the setup script, and -some is automatically generated by the Distutils (such as the list of -files installed). But some of it has to be supplied as options to -\command{bdist\_rpm}, which would be very tedious to do on the -command-line for every run. Hence, here is a snippet from the -Distutils' own \file{setup.cfg}: - -\begin{verbatim} -[bdist_rpm] -release = 1 -packager = Greg Ward <gward@python.net> -doc_files = CHANGES.txt - README.txt - USAGE.txt - doc/ - examples/ -\end{verbatim} - -Note that the \option{doc\_files} option is simply a -whitespace-separated string split across multiple lines for readability. - - -\begin{seealso} - \seetitle[../inst/config-syntax.html]{Installing Python - Modules}{More information on the configuration files is - available in the manual for system administrators.} -\end{seealso} - - -\chapter{Creating a Source Distribution} -\label{source-dist} - -As shown in section~\ref{simple-example}, you use the -\command{sdist} command to create a source distribution. In the -simplest case, - -\begin{verbatim} -python setup.py sdist -\end{verbatim} - -(assuming you haven't specified any \command{sdist} options in the setup -script or config file), \command{sdist} creates the archive of the -default format for the current platform. The default format is a gzip'ed -tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows. - -You can specify as many formats as you like using the -\longprogramopt{formats} option, for example: - -\begin{verbatim} -python setup.py sdist --formats=gztar,zip -\end{verbatim} - -to create a gzipped tarball and a zip file. The available formats are: - -\begin{tableiii}{l|l|c}{code}% - {Format}{Description}{Notes} - \lineiii{zip}{zip file (\file{.zip})}{(1),(3)} - \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(2),(4)} - \lineiii{bztar}{bzip2'ed tar file (\file{.tar.bz2})}{(4)} - \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)} - \lineiii{tar}{tar file (\file{.tar})}{(4)} -\end{tableiii} - -\noindent Notes: -\begin{description} -\item[(1)] default on Windows -\item[(2)] default on \UNIX -\item[(3)] requires either external \program{zip} utility or - \module{zipfile} module (part of the standard Python library since - Python~1.6) -\item[(4)] requires external utilities: \program{tar} and possibly one - of \program{gzip}, \program{bzip2}, or \program{compress} -\end{description} - - - -\section{Specifying the files to distribute} -\label{manifest} - -If you don't supply an explicit list of files (or instructions on how to -generate one), the \command{sdist} command puts a minimal default set -into the source distribution: -\begin{itemize} -\item all Python source files implied by the \option{py\_modules} and - \option{packages} options -\item all C source files mentioned in the \option{ext\_modules} or - \option{libraries} options (\XXX{getting C library sources currently - broken---no \method{get_source_files()} method in \file{build_clib.py}!}) -\item scripts identified by the \option{scripts} option -\item anything that looks like a test script: \file{test/test*.py} - (currently, the Distutils don't do anything with test scripts except - include them in source distributions, but in the future there will be - a standard for testing Python module distributions) -\item \file{README.txt} (or \file{README}), \file{setup.py} (or whatever - you called your setup script), and \file{setup.cfg} -\end{itemize} - -Sometimes this is enough, but usually you will want to specify -additional files to distribute. The typical way to do this is to write -a \emph{manifest template}, called \file{MANIFEST.in} by default. The -manifest template is just a list of instructions for how to generate -your manifest file, \file{MANIFEST}, which is the exact list of files to -include in your source distribution. The \command{sdist} command -processes this template and generates a manifest based on its -instructions and what it finds in the filesystem. - -If you prefer to roll your own manifest file, the format is simple: one -filename per line, regular files (or symlinks to them) only. If you do -supply your own \file{MANIFEST}, you must specify everything: the -default set of files described above does not apply in this case. - -The manifest template has one command per line, where each command -specifies a set of files to include or exclude from the source -distribution. For an example, again we turn to the Distutils' own -manifest template: - -\begin{verbatim} -include *.txt -recursive-include examples *.txt *.py -prune examples/sample?/build -\end{verbatim} - -The meanings should be fairly clear: include all files in the -distribution root matching \file{*.txt}, all files anywhere under the -\file{examples} directory matching \file{*.txt} or \file{*.py}, and -exclude all directories matching \file{examples/sample?/build}. All of -this is done \emph{after} the standard include set, so you can exclude -files from the standard set with explicit instructions in the manifest -template. (Or, you can use the \longprogramopt{no-defaults} option to -disable the standard set entirely.) There are several other commands -available in the manifest template mini-language; see -section~\ref{sdist-cmd}. - -The order of commands in the manifest template matters: initially, we -have the list of default files as described above, and each command in -the template adds to or removes from that list of files. Once we have -fully processed the manifest template, we remove files that should not -be included in the source distribution: -\begin{itemize} -\item all files in the Distutils ``build'' tree (default \file{build/}) -\item all files in directories named \file{RCS}, \file{CVS} or \file{.svn} -\end{itemize} -Now we have our complete list of files, which is written to the manifest -for future reference, and then used to build the source distribution -archive(s). - -You can disable the default set of included files with the -\longprogramopt{no-defaults} option, and you can disable the standard -exclude set with \longprogramopt{no-prune}. - -Following the Distutils' own manifest template, let's trace how the -\command{sdist} command builds the list of files to include in the -Distutils source distribution: -\begin{enumerate} -\item include all Python source files in the \file{distutils} and - \file{distutils/command} subdirectories (because packages - corresponding to those two directories were mentioned in the - \option{packages} option in the setup script---see - section~\ref{setup-script}) -\item include \file{README.txt}, \file{setup.py}, and \file{setup.cfg} - (standard files) -\item include \file{test/test*.py} (standard files) -\item include \file{*.txt} in the distribution root (this will find - \file{README.txt} a second time, but such redundancies are weeded out - later) -\item include anything matching \file{*.txt} or \file{*.py} in the - sub-tree under \file{examples}, -\item exclude all files in the sub-trees starting at directories - matching \file{examples/sample?/build}---this may exclude files - included by the previous two steps, so it's important that the - \code{prune} command in the manifest template comes after the - \code{recursive-include} command -\item exclude the entire \file{build} tree, and any \file{RCS}, - \file{CVS} and \file{.svn} directories -\end{enumerate} -Just like in the setup script, file and directory names in the manifest -template should always be slash-separated; the Distutils will take care -of converting them to the standard representation on your platform. -That way, the manifest template is portable across operating systems. - - -\section{Manifest-related options} -\label{manifest-options} - -The normal course of operations for the \command{sdist} command is as -follows: -\begin{itemize} -\item if the manifest file, \file{MANIFEST} doesn't exist, read - \file{MANIFEST.in} and create the manifest -\item if neither \file{MANIFEST} nor \file{MANIFEST.in} exist, create a - manifest with just the default file set -\item if either \file{MANIFEST.in} or the setup script (\file{setup.py}) - are more recent than \file{MANIFEST}, recreate \file{MANIFEST} by - reading \file{MANIFEST.in} -\item use the list of files now in \file{MANIFEST} (either just - generated or read in) to create the source distribution archive(s) -\end{itemize} -There are a couple of options that modify this behaviour. First, use -the \longprogramopt{no-defaults} and \longprogramopt{no-prune} to -disable the standard ``include'' and ``exclude'' sets. - -Second, you might want to force the manifest to be regenerated---for -example, if you have added or removed files or directories that match an -existing pattern in the manifest template, you should regenerate the -manifest: - -\begin{verbatim} -python setup.py sdist --force-manifest -\end{verbatim} - -Or, you might just want to (re)generate the manifest, but not create a -source distribution: - -\begin{verbatim} -python setup.py sdist --manifest-only -\end{verbatim} - -\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}. -\programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and -\programopt{-f} for \longprogramopt{force-manifest}. - - -\chapter{Creating Built Distributions} -\label{built-dist} - -A ``built distribution'' is what you're probably used to thinking of -either as a ``binary package'' or an ``installer'' (depending on your -background). It's not necessarily binary, though, because it might -contain only Python source code and/or byte-code; and we don't call it a -package, because that word is already spoken for in Python. (And -``installer'' is a term specific to the world of mainstream desktop -systems.) - -A built distribution is how you make life as easy as possible for -installers of your module distribution: for users of RPM-based Linux -systems, it's a binary RPM; for Windows users, it's an executable -installer; for Debian-based Linux users, it's a Debian package; and so -forth. Obviously, no one person will be able to create built -distributions for every platform under the sun, so the Distutils are -designed to enable module developers to concentrate on their -specialty---writing code and creating source distributions---while an -intermediary species called \emph{packagers} springs up to turn source -distributions into built distributions for as many platforms as there -are packagers. - -Of course, the module developer could be his own packager; or the -packager could be a volunteer ``out there'' somewhere who has access to -a platform which the original developer does not; or it could be -software periodically grabbing new source distributions and turning them -into built distributions for as many platforms as the software has -access to. Regardless of who they are, a packager uses the -setup script and the \command{bdist} command family to generate built -distributions. - -As a simple example, if I run the following command in the Distutils -source tree: - -\begin{verbatim} -python setup.py bdist -\end{verbatim} - -then the Distutils builds my module distribution (the Distutils itself -in this case), does a ``fake'' installation (also in the \file{build} -directory), and creates the default type of built distribution for my -platform. The default format for built distributions is a ``dumb'' tar -file on \UNIX, and a simple executable installer on Windows. (That tar -file is considered ``dumb'' because it has to be unpacked in a specific -location to work.) - -Thus, the above command on a \UNIX{} system creates -\file{Distutils-1.0.\filevar{plat}.tar.gz}; unpacking this tarball -from the right place installs the Distutils just as though you had -downloaded the source distribution and run \code{python setup.py - install}. (The ``right place'' is either the root of the filesystem or -Python's \filevar{prefix} directory, depending on the options given to -the \command{bdist\_dumb} command; the default is to make dumb -distributions relative to \filevar{prefix}.) - -Obviously, for pure Python distributions, this isn't any simpler than -just running \code{python setup.py install}---but for non-pure -distributions, which include extensions that would need to be -compiled, it can mean the difference between someone being able to use -your extensions or not. And creating ``smart'' built distributions, -such as an RPM package or an executable installer for Windows, is far -more convenient for users even if your distribution doesn't include -any extensions. - -The \command{bdist} command has a \longprogramopt{formats} option, -similar to the \command{sdist} command, which you can use to select the -types of built distribution to generate: for example, - -\begin{verbatim} -python setup.py bdist --format=zip -\end{verbatim} - -would, when run on a \UNIX{} system, create -\file{Distutils-1.0.\filevar{plat}.zip}---again, this archive would be -unpacked from the root directory to install the Distutils. - -The available formats for built distributions are: - -\begin{tableiii}{l|l|c}{code}% - {Format}{Description}{Notes} - \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(1),(3)} - \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(3)} - \lineiii{tar}{tar file (\file{.tar})}{(3)} - \lineiii{zip}{zip file (\file{.zip})}{(4)} - \lineiii{rpm}{RPM}{(5)} - \lineiii{pkgtool}{Solaris \program{pkgtool}}{} - \lineiii{sdux}{HP-UX \program{swinstall}}{} - \lineiii{rpm}{RPM}{(5)} -% \lineiii{srpm}{source RPM}{(5) \XXX{to do!}} - \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(4)} -\end{tableiii} - -\noindent Notes: -\begin{description} -\item[(1)] default on \UNIX -\item[(2)] default on Windows \XXX{to-do!} -\item[(3)] requires external utilities: \program{tar} and possibly one - of \program{gzip}, \program{bzip2}, or \program{compress} -\item[(4)] requires either external \program{zip} utility or - \module{zipfile} module (part of the standard Python library since - Python~1.6) -\item[(5)] requires external \program{rpm} utility, version 3.0.4 or - better (use \code{rpm --version} to find out which version you have) -\end{description} - -You don't have to use the \command{bdist} command with the -\longprogramopt{formats} option; you can also use the command that -directly implements the format you're interested in. Some of these -\command{bdist} ``sub-commands'' actually generate several similar -formats; for instance, the \command{bdist\_dumb} command generates all -the ``dumb'' archive formats (\code{tar}, \code{ztar}, \code{gztar}, and -\code{zip}), and \command{bdist\_rpm} generates both binary and source -RPMs. The \command{bdist} sub-commands, and the formats generated by -each, are: - -\begin{tableii}{l|l}{command}% - {Command}{Formats} - \lineii{bdist\_dumb}{tar, ztar, gztar, zip} - \lineii{bdist\_rpm}{rpm, srpm} - \lineii{bdist\_wininst}{wininst} -\end{tableii} - -The following sections give details on the individual \command{bdist\_*} -commands. - - -\section{Creating dumb built distributions} -\label{creating-dumb} - -\XXX{Need to document absolute vs. prefix-relative packages here, but - first I have to implement it!} - - -\section{Creating RPM packages} -\label{creating-rpms} - -The RPM format is used by many popular Linux distributions, including -Red Hat, SuSE, and Mandrake. If one of these (or any of the other -RPM-based Linux distributions) is your usual environment, creating RPM -packages for other users of that same distribution is trivial. -Depending on the complexity of your module distribution and differences -between Linux distributions, you may also be able to create RPMs that -work on different RPM-based distributions. - -The usual way to create an RPM of your module distribution is to run the -\command{bdist\_rpm} command: - -\begin{verbatim} -python setup.py bdist_rpm -\end{verbatim} - -or the \command{bdist} command with the \longprogramopt{format} option: - -\begin{verbatim} -python setup.py bdist --formats=rpm -\end{verbatim} - -The former allows you to specify RPM-specific options; the latter allows -you to easily specify multiple formats in one run. If you need to do -both, you can explicitly specify multiple \command{bdist\_*} commands -and their options: - -\begin{verbatim} -python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \ - bdist_wininst --target_version="2.0" -\end{verbatim} - -Creating RPM packages is driven by a \file{.spec} file, much as using -the Distutils is driven by the setup script. To make your life easier, -the \command{bdist\_rpm} command normally creates a \file{.spec} file -based on the information you supply in the setup script, on the command -line, and in any Distutils configuration files. Various options and -sections in the \file{.spec} file are derived from options in the setup -script as follows: - -\begin{tableii}{l|l}{textrm}% - {RPM \file{.spec} file option or section}{Distutils setup script option} - \lineii{Name}{\option{name}} - \lineii{Summary (in preamble)}{\option{description}} - \lineii{Version}{\option{version}} - \lineii{Vendor}{\option{author} and \option{author\_email}, or \\& - \option{maintainer} and \option{maintainer\_email}} - \lineii{Copyright}{\option{licence}} - \lineii{Url}{\option{url}} - \lineii{\%description (section)}{\option{long\_description}} -\end{tableii} - -Additionally, there are many options in \file{.spec} files that don't have -corresponding options in the setup script. Most of these are handled -through options to the \command{bdist\_rpm} command as follows: - -\begin{tableiii}{l|l|l}{textrm}% - {RPM \file{.spec} file option or section}% - {\command{bdist\_rpm} option}% - {default value} - \lineiii{Release}{\option{release}}{``1''} - \lineiii{Group}{\option{group}}{``Development/Libraries''} - \lineiii{Vendor}{\option{vendor}}{(see above)} - \lineiii{Packager}{\option{packager}}{(none)} - \lineiii{Provides}{\option{provides}}{(none)} - \lineiii{Requires}{\option{requires}}{(none)} - \lineiii{Conflicts}{\option{conflicts}}{(none)} - \lineiii{Obsoletes}{\option{obsoletes}}{(none)} - \lineiii{Distribution}{\option{distribution\_name}}{(none)} - \lineiii{BuildRequires}{\option{build\_requires}}{(none)} - \lineiii{Icon}{\option{icon}}{(none)} -\end{tableiii} - -Obviously, supplying even a few of these options on the command-line -would be tedious and error-prone, so it's usually best to put them in -the setup configuration file, \file{setup.cfg}---see -section~\ref{setup-config}. If you distribute or package many Python -module distributions, you might want to put options that apply to all of -them in your personal Distutils configuration file -(\file{\textasciitilde/.pydistutils.cfg}). - -There are three steps to building a binary RPM package, all of which are -handled automatically by the Distutils: - -\begin{enumerate} -\item create a \file{.spec} file, which describes the package (analogous - to the Distutils setup script; in fact, much of the information in the - setup script winds up in the \file{.spec} file) -\item create the source RPM -\item create the ``binary'' RPM (which may or may not contain binary - code, depending on whether your module distribution contains Python - extensions) -\end{enumerate} - -Normally, RPM bundles the last two steps together; when you use the -Distutils, all three steps are typically bundled together. - -If you wish, you can separate these three steps. You can use the -\longprogramopt{spec-only} option to make \command{bdist_rpm} just -create the \file{.spec} file and exit; in this case, the \file{.spec} -file will be written to the ``distribution directory''---normally -\file{dist/}, but customizable with the \longprogramopt{dist-dir} -option. (Normally, the \file{.spec} file winds up deep in the ``build -tree,'' in a temporary directory created by \command{bdist_rpm}.) - -% \XXX{this isn't implemented yet---is it needed?!} -% You can also specify a custom \file{.spec} file with the -% \longprogramopt{spec-file} option; used in conjunction with -% \longprogramopt{spec-only}, this gives you an opportunity to customize -% the \file{.spec} file manually: -% -% \ begin{verbatim} -% > python setup.py bdist_rpm --spec-only -% # ...edit dist/FooBar-1.0.spec -% > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec -% \ end{verbatim} -% -% (Although a better way to do this is probably to override the standard -% \command{bdist\_rpm} command with one that writes whatever else you want -% to the \file{.spec} file.) - - -\section{Creating Windows Installers} -\label{creating-wininst} - -Executable installers are the natural format for binary distributions -on Windows. They display a nice graphical user interface, display -some information about the module distribution to be installed taken -from the metadata in the setup script, let the user select a few -options, and start or cancel the installation. - -Since the metadata is taken from the setup script, creating Windows -installers is usually as easy as running: - -\begin{verbatim} -python setup.py bdist_wininst -\end{verbatim} - -or the \command{bdist} command with the \longprogramopt{formats} option: - -\begin{verbatim} -python setup.py bdist --formats=wininst -\end{verbatim} - -If you have a pure module distribution (only containing pure Python -modules and packages), the resulting installer will be version -independent and have a name like \file{foo-1.0.win32.exe}. These -installers can even be created on \UNIX{} or Mac OS platforms. - -If you have a non-pure distribution, the extensions can only be -created on a Windows platform, and will be Python version dependent. -The installer filename will reflect this and now has the form -\file{foo-1.0.win32-py2.0.exe}. You have to create a separate installer -for every Python version you want to support. - -The installer will try to compile pure modules into bytecode after -installation on the target system in normal and optimizing mode. If -you don't want this to happen for some reason, you can run the -\command{bdist_wininst} command with the -\longprogramopt{no-target-compile} and/or the -\longprogramopt{no-target-optimize} option. - -By default the installer will display the cool ``Python Powered'' logo -when it is run, but you can also supply your own bitmap which must be -a Windows \file{.bmp} file with the \longprogramopt{bitmap} option. - -The installer will also display a large title on the desktop -background window when it is run, which is constructed from the name -of your distribution and the version number. This can be changed to -another text by using the \longprogramopt{title} option. - -The installer file will be written to the ``distribution directory'' ---- normally \file{dist/}, but customizable with the -\longprogramopt{dist-dir} option. - -\subsection{The Postinstallation script} -\label{postinstallation-script} - -Starting with Python 2.3, a postinstallation script can be specified -which the \longprogramopt{install-script} option. The basename of the -script must be specified, and the script filename must also be listed -in the scripts argument to the setup function. - -This script will be run at installation time on the target system -after all the files have been copied, with \code{argv[1]} set to -\programopt{-install}, and again at uninstallation time before the -files are removed with \code{argv[1]} set to \programopt{-remove}. - -The installation script runs embedded in the windows installer, every -output (\code{sys.stdout}, \code{sys.stderr}) is redirected into a -buffer and will be displayed in the GUI after the script has finished. - -Some functions especially useful in this context are available as -additional built-in functions in the installation script. - -\begin{funcdesc}{directory_created}{path} -\funcline{file_created}{path} - These functions should be called when a directory or file is created - by the postinstall script at installation time. It will register - \var{path} with the uninstaller, so that it will be removed when the - distribution is uninstalled. To be safe, directories are only removed - if they are empty. -\end{funcdesc} - -\begin{funcdesc}{get_special_folder_path}{csidl_string} - This function can be used to retrieve special folder locations on - Windows like the Start Menu or the Desktop. It returns the full - path to the folder. \var{csidl_string} must be one of the following - strings: - -\begin{verbatim} -"CSIDL_APPDATA" - -"CSIDL_COMMON_STARTMENU" -"CSIDL_STARTMENU" - -"CSIDL_COMMON_DESKTOPDIRECTORY" -"CSIDL_DESKTOPDIRECTORY" - -"CSIDL_COMMON_STARTUP" -"CSIDL_STARTUP" - -"CSIDL_COMMON_PROGRAMS" -"CSIDL_PROGRAMS" - -"CSIDL_FONTS" -\end{verbatim} - - If the folder cannot be retrieved, \exception{OSError} is raised. - - Which folders are available depends on the exact Windows version, - and probably also the configuration. For details refer to - Microsoft's documentation of the - \cfunction{SHGetSpecialFolderPath()} function. -\end{funcdesc} - -\begin{funcdesc}{create_shortcut}{target, description, - filename\optional{, - arguments\optional{, - workdir\optional{, - iconpath\optional{, iconindex}}}}} - This function creates a shortcut. - \var{target} is the path to the program to be started by the shortcut. - \var{description} is the description of the shortcut. - \var{filename} is the title of the shortcut that the user will see. - \var{arguments} specifies the command line arguments, if any. - \var{workdir} is the working directory for the program. - \var{iconpath} is the file containing the icon for the shortcut, - and \var{iconindex} is the index of the icon in the file - \var{iconpath}. Again, for details consult the Microsoft - documentation for the \class{IShellLink} interface. -\end{funcdesc} - -\chapter{Registering with the Package Index} -\label{package-index} - -The Python Package Index (PyPI) holds meta-data describing distributions -packaged with distutils. The distutils command \command{register} is -used to submit your distribution's meta-data to the index. It is invoked -as follows: - -\begin{verbatim} -python setup.py register -\end{verbatim} - -Distutils will respond with the following prompt: - -\begin{verbatim} -running register -We need to know who you are, so please choose either: - 1. use your existing login, - 2. register as a new user, - 3. have the server generate a new password for you (and email it to you), or - 4. quit -Your selection [default 1]: -\end{verbatim} - -\noindent Note: if your username and password are saved locally, you will -not see this menu. - -If you have not registered with PyPI, then you will need to do so now. You -should choose option 2, and enter your details as required. Soon after -submitting your details, you will receive an email which will be used to -confirm your registration. - -Once you are registered, you may choose option 1 from the menu. You will -be prompted for your PyPI username and password, and \command{register} -will then submit your meta-data to the index. - -You may submit any number of versions of your distribution to the index. If -you alter the meta-data for a particular version, you may submit it again -and the index will be updated. - -PyPI holds a record for each (name, version) combination submitted. The -first user to submit information for a given name is designated the Owner -of that name. They may submit changes through the \command{register} -command or through the web interface. They may also designate other users -as Owners or Maintainers. Maintainers may edit the package information, but -not designate other Owners or Maintainers. - -By default PyPI will list all versions of a given package. To hide certain -versions, the Hidden property should be set to yes. This must be edited -through the web interface. - -\section{The .pypirc file} -\label{pypirc} - -The format of the \file{.pypirc} file is formated as follows: - -\begin{verbatim} -[server-login] -repository: <repository-url> -username: <username> -password: <password> -\end{verbatim} - -\var{repository} can be ommitted and defaults to -\code{http://www.python.org/pypi}. - -\chapter{Uploading Packages to the Package Index} -\label{package-upload} - -\versionadded{2.5} - -The Python Package Index (PyPI) not only stores the package info, but also -the package data if the author of the package wishes to. The distutils -command \command{upload} pushes the distribution files to PyPI. - -The command is invoked immediately after building one or more distribution -files. For example, the command - -\begin{verbatim} -python setup.py sdist bdist_wininst upload -\end{verbatim} - -will cause the source distribution and the Windows installer to be -uploaded to PyPI. Note that these will be uploaded even if they are -built using an earlier invocation of \file{setup.py}, but that only -distributions named on the command line for the invocation including -the \command{upload} command are uploaded. - -The \command{upload} command uses the username, password, and repository -URL from the \file{\$HOME/.pypirc} file (see section~\ref{pypirc} for -more on this file). - -You can use the \longprogramopt{sign} option to tell \command{upload} to -sign each uploaded file using GPG (GNU Privacy Guard). The -\program{gpg} program must be available for execution on the system -\envvar{PATH}. You can also specify which key to use for signing -using the \longprogramopt{identity=\var{name}} option. - -Other \command{upload} options include -\longprogramopt{repository=\var{url}} (which lets you override the -repository setting from \file{\$HOME/.pypirc}), and -\longprogramopt{show-response} (which displays the full response text -from the PyPI server for help in debugging upload problems). - -\chapter{Examples} -\label{examples} - -This chapter provides a number of basic examples to help get started -with distutils. Additional information about using distutils can be -found in the Distutils Cookbook. - -\begin{seealso} - \seelink{http://www.python.org/cgi-bin/moinmoin/DistutilsCookbook} - {Distutils Cookbook} - {Collection of recipes showing how to achieve more control - over distutils.} -\end{seealso} - - -\section{Pure Python distribution (by module)} -\label{pure-mod} - -If you're just distributing a couple of modules, especially if they -don't live in a particular package, you can specify them individually -using the \option{py\_modules} option in the setup script. - -In the simplest case, you'll have two files to worry about: a setup -script and the single module you're distributing, \file{foo.py} in this -example: -\begin{verbatim} -<root>/ - setup.py - foo.py -\end{verbatim} -(In all diagrams in this section, \var{\textless root\textgreater} -will refer to the distribution root directory.) A minimal setup script -to describe this situation would be: -\begin{verbatim} -from distutils.core import setup -setup(name='foo', - version='1.0', - py_modules=['foo'], - ) -\end{verbatim} -Note that the name of the distribution is specified independently with -the \option{name} option, and there's no rule that says it has to be the -same as the name of the sole module in the distribution (although that's -probably a good convention to follow). However, the distribution name -is used to generate filenames, so you should stick to letters, digits, -underscores, and hyphens. - -Since \option{py\_modules} is a list, you can of course specify multiple -modules, eg. if you're distributing modules \module{foo} and -\module{bar}, your setup might look like this: -\begin{verbatim} -<root>/ - setup.py - foo.py - bar.py -\end{verbatim} -and the setup script might be -\begin{verbatim} -from distutils.core import setup -setup(name='foobar', - version='1.0', - py_modules=['foo', 'bar'], - ) -\end{verbatim} - -You can put module source files into another directory, but if you have -enough modules to do that, it's probably easier to specify modules by -package rather than listing them individually. - - -\section{Pure Python distribution (by package)} -\label{pure-pkg} - -If you have more than a couple of modules to distribute, especially if -they are in multiple packages, it's probably easier to specify whole -packages rather than individual modules. This works even if your -modules are not in a package; you can just tell the Distutils to process -modules from the root package, and that works the same as any other -package (except that you don't have to have an \file{\_\_init\_\_.py} -file). - -The setup script from the last example could also be written as -\begin{verbatim} -from distutils.core import setup -setup(name='foobar', - version='1.0', - packages=[''], - ) -\end{verbatim} -(The empty string stands for the root package.) - -If those two files are moved into a subdirectory, but remain in the root -package, e.g.: -\begin{verbatim} -<root>/ - setup.py - src/ foo.py - bar.py -\end{verbatim} -then you would still specify the root package, but you have to tell the -Distutils where source files in the root package live: -\begin{verbatim} -from distutils.core import setup -setup(name='foobar', - version='1.0', - package_dir={'': 'src'}, - packages=[''], - ) -\end{verbatim} - -More typically, though, you will want to distribute multiple modules in -the same package (or in sub-packages). For example, if the \module{foo} -and \module{bar} modules belong in package \module{foobar}, one way to -layout your source tree is -\begin{verbatim} -<root>/ - setup.py - foobar/ - __init__.py - foo.py - bar.py -\end{verbatim} -This is in fact the default layout expected by the Distutils, and the -one that requires the least work to describe in your setup script: -\begin{verbatim} -from distutils.core import setup -setup(name='foobar', - version='1.0', - packages=['foobar'], - ) -\end{verbatim} - -If you want to put modules in directories not named for their package, -then you need to use the \option{package\_dir} option again. For -example, if the \file{src} directory holds modules in the -\module{foobar} package: -\begin{verbatim} -<root>/ - setup.py - src/ - __init__.py - foo.py - bar.py -\end{verbatim} -an appropriate setup script would be -\begin{verbatim} -from distutils.core import setup -setup(name='foobar', - version='1.0', - package_dir={'foobar': 'src'}, - packages=['foobar'], - ) -\end{verbatim} - -Or, you might put modules from your main package right in the -distribution root: -\begin{verbatim} -<root>/ - setup.py - __init__.py - foo.py - bar.py -\end{verbatim} -in which case your setup script would be -\begin{verbatim} -from distutils.core import setup -setup(name='foobar', - version='1.0', - package_dir={'foobar': ''}, - packages=['foobar'], - ) -\end{verbatim} -(The empty string also stands for the current directory.) - -If you have sub-packages, they must be explicitly listed in -\option{packages}, but any entries in \option{package\_dir} -automatically extend to sub-packages. (In other words, the Distutils -does \emph{not} scan your source tree, trying to figure out which -directories correspond to Python packages by looking for -\file{\_\_init\_\_.py} files.) Thus, if the default layout grows a -sub-package: -\begin{verbatim} -<root>/ - setup.py - foobar/ - __init__.py - foo.py - bar.py - subfoo/ - __init__.py - blah.py -\end{verbatim} -then the corresponding setup script would be -\begin{verbatim} -from distutils.core import setup -setup(name='foobar', - version='1.0', - packages=['foobar', 'foobar.subfoo'], - ) -\end{verbatim} -(Again, the empty string in \option{package\_dir} stands for the current -directory.) - - -\section{Single extension module} -\label{single-ext} - -Extension modules are specified using the \option{ext\_modules} option. -\option{package\_dir} has no effect on where extension source files are -found; it only affects the source for pure Python modules. The simplest -case, a single extension module in a single C source file, is: -\begin{verbatim} -<root>/ - setup.py - foo.c -\end{verbatim} -If the \module{foo} extension belongs in the root package, the setup -script for this could be -\begin{verbatim} -from distutils.core import setup -from distutils.extension import Extension -setup(name='foobar', - version='1.0', - ext_modules=[Extension('foo', ['foo.c'])], - ) -\end{verbatim} - -If the extension actually belongs in a package, say \module{foopkg}, -then - -With exactly the same source tree layout, this extension can be put in -the \module{foopkg} package simply by changing the name of the -extension: -\begin{verbatim} -from distutils.core import setup -from distutils.extension import Extension -setup(name='foobar', - version='1.0', - ext_modules=[Extension('foopkg.foo', ['foo.c'])], - ) -\end{verbatim} - - -%\section{Multiple extension modules} -%\label{multiple-ext} - - -%\section{Putting it all together} - - -\chapter{Extending Distutils \label{extending}} - -Distutils can be extended in various ways. Most extensions take the -form of new commands or replacements for existing commands. New -commands may be written to support new types of platform-specific -packaging, for example, while replacements for existing commands may -be made to modify details of how the command operates on a package. - -Most extensions of the distutils are made within \file{setup.py} -scripts that want to modify existing commands; many simply add a few -file extensions that should be copied into packages in addition to -\file{.py} files as a convenience. - -Most distutils command implementations are subclasses of the -\class{Command} class from \refmodule{distutils.cmd}. New commands -may directly inherit from \class{Command}, while replacements often -derive from \class{Command} indirectly, directly subclassing the -command they are replacing. Commands are required to derive from -\class{Command}. - - -%\section{Extending existing commands} -%\label{extend-existing} - - -%\section{Writing new commands} -%\label{new-commands} - -%\XXX{Would an uninstall command be a good example here?} - -\section{Integrating new commands} - -There are different ways to integrate new command implementations into -distutils. The most difficult is to lobby for the inclusion of the -new features in distutils itself, and wait for (and require) a version -of Python that provides that support. This is really hard for many -reasons. - -The most common, and possibly the most reasonable for most needs, is -to include the new implementations with your \file{setup.py} script, -and cause the \function{distutils.core.setup()} function use them: - -\begin{verbatim} -from distutils.command.build_py import build_py as _build_py -from distutils.core import setup - -class build_py(_build_py): - """Specialized Python source builder.""" - - # implement whatever needs to be different... - -setup(cmdclass={'build_py': build_py}, - ...) -\end{verbatim} - -This approach is most valuable if the new implementations must be used -to use a particular package, as everyone interested in the package -will need to have the new command implementation. - -Beginning with Python 2.4, a third option is available, intended to -allow new commands to be added which can support existing -\file{setup.py} scripts without requiring modifications to the Python -installation. This is expected to allow third-party extensions to -provide support for additional packaging systems, but the commands can -be used for anything distutils commands can be used for. A new -configuration option, \option{command\_packages} (command-line option -\longprogramopt{command-packages}), can be used to specify additional -packages to be searched for modules implementing commands. Like all -distutils options, this can be specified on the command line or in a -configuration file. This option can only be set in the -\code{[global]} section of a configuration file, or before any -commands on the command line. If set in a configuration file, it can -be overridden from the command line; setting it to an empty string on -the command line causes the default to be used. This should never be -set in a configuration file provided with a package. - -This new option can be used to add any number of packages to the list -of packages searched for command implementations; multiple package -names should be separated by commas. When not specified, the search -is only performed in the \module{distutils.command} package. When -\file{setup.py} is run with the option -\longprogramopt{command-packages} \programopt{distcmds,buildcmds}, -however, the packages \module{distutils.command}, \module{distcmds}, -and \module{buildcmds} will be searched in that order. New commands -are expected to be implemented in modules of the same name as the -command by classes sharing the same name. Given the example command -line option above, the command \command{bdist\_openpkg} could be -implemented by the class \class{distcmds.bdist_openpkg.bdist_openpkg} -or \class{buildcmds.bdist_openpkg.bdist_openpkg}. - -\section{Adding new distribution types} - -Commands that create distributions (files in the \file{dist/} -directory) need to add \code{(\var{command}, \var{filename})} pairs to -\code{self.distribution.dist_files} so that \command{upload} can -upload it to PyPI. The \var{filename} in the pair contains no path -information, only the name of the file itself. In dry-run mode, pairs -should still be added to represent what would have been created. - -\chapter{Command Reference} -\label{reference} - - -%\section{Building modules: the \protect\command{build} command family} -%\label{build-cmds} - -%\subsubsection{\protect\command{build}} -%\label{build-cmd} - -%\subsubsection{\protect\command{build\_py}} -%\label{build-py-cmd} - -%\subsubsection{\protect\command{build\_ext}} -%\label{build-ext-cmd} - -%\subsubsection{\protect\command{build\_clib}} -%\label{build-clib-cmd} - - -\section{Installing modules: the \protect\command{install} command family} -\label{install-cmd} - -The install command ensures that the build commands have been run and then -runs the subcommands \command{install\_lib}, -\command{install\_data} and -\command{install\_scripts}. - -%\subsubsection{\protect\command{install\_lib}} -%\label{install-lib-cmd} - -\subsection{\protect\command{install\_data}} -\label{install-data-cmd} -This command installs all data files provided with the distribution. - -\subsection{\protect\command{install\_scripts}} -\label{install-scripts-cmd} -This command installs all (Python) scripts in the distribution. - - -%\subsection{Cleaning up: the \protect\command{clean} command} -%\label{clean-cmd} - - -\section{Creating a source distribution: the - \protect\command{sdist} command} -\label{sdist-cmd} - - -\XXX{fragment moved down from above: needs context!} - -The manifest template commands are: - -\begin{tableii}{ll}{command}{Command}{Description} - \lineii{include \var{pat1} \var{pat2} ... } - {include all files matching any of the listed patterns} - \lineii{exclude \var{pat1} \var{pat2} ... } - {exclude all files matching any of the listed patterns} - \lineii{recursive-include \var{dir} \var{pat1} \var{pat2} ... } - {include all files under \var{dir} matching any of the listed patterns} - \lineii{recursive-exclude \var{dir} \var{pat1} \var{pat2} ...} - {exclude all files under \var{dir} matching any of the listed patterns} - \lineii{global-include \var{pat1} \var{pat2} ...} - {include all files anywhere in the source tree matching\\& - any of the listed patterns} - \lineii{global-exclude \var{pat1} \var{pat2} ...} - {exclude all files anywhere in the source tree matching\\& - any of the listed patterns} - \lineii{prune \var{dir}}{exclude all files under \var{dir}} - \lineii{graft \var{dir}}{include all files under \var{dir}} -\end{tableii} - -The patterns here are \UNIX-style ``glob'' patterns: \code{*} matches any -sequence of regular filename characters, \code{?} matches any single -regular filename character, and \code{[\var{range}]} matches any of the -characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z}, -\code{a-f0-9\_.}). The definition of ``regular filename character'' is -platform-specific: on \UNIX{} it is anything except slash; on Windows -anything except backslash or colon; on Mac OS 9 anything except colon. - -\XXX{Windows support not there yet} - - -%\section{Creating a built distribution: the -% \protect\command{bdist} command family} -%\label{bdist-cmds} - - -%\subsection{\protect\command{bdist}} - -%\subsection{\protect\command{bdist\_dumb}} - -%\subsection{\protect\command{bdist\_rpm}} - -%\subsection{\protect\command{bdist\_wininst}} - - -\chapter{API Reference \label{api-reference}} - -\section{\module{distutils.core} --- Core Distutils functionality} - -\declaremodule{standard}{distutils.core} -\modulesynopsis{The core Distutils functionality} - -The \module{distutils.core} module is the only module that needs to be -installed to use the Distutils. It provides the \function{setup()} (which -is called from the setup script). Indirectly provides the -\class{distutils.dist.Distribution} and \class{distutils.cmd.Command} class. - -\begin{funcdesc}{setup}{arguments} -The basic do-everything function that does most everything you could ever -ask for from a Distutils method. See XXXXX - -The setup function takes a large number of arguments. These -are laid out in the following table. - -\begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type} -\lineiii{name}{The name of the package}{a string} -\lineiii{version}{The version number of the package}{See \refmodule{distutils.version}} -\lineiii{description}{A single line describing the package}{a string} -\lineiii{long_description}{Longer description of the package}{a string} -\lineiii{author}{The name of the package author}{a string} -\lineiii{author_email}{The email address of the package author}{a string} -\lineiii{maintainer}{The name of the current maintainer, if different from the author}{a string} -\lineiii{maintainer_email}{The email address of the current maintainer, if different from the author}{} -\lineiii{url}{A URL for the package (homepage)}{a URL} -\lineiii{download_url}{A URL to download the package}{a URL} -\lineiii{packages}{A list of Python packages that distutils will manipulate}{a list of strings} -\lineiii{py_modules}{A list of Python modules that distutils will manipulate}{a list of strings} -\lineiii{scripts}{A list of standalone script files to be built and installed}{a list of strings} -\lineiii{ext_modules}{A list of Python extensions to be built}{A list of -instances of \class{distutils.core.Extension}} -\lineiii{classifiers}{A list of categories for the package}{The list of available categorizations is at \url{http://cheeseshop.python.org/pypi?:action=list_classifiers}.} -\lineiii{distclass}{the \class{Distribution} class to use}{A subclass of \class{distutils.core.Distribution}} -% What on earth is the use case for script_name? -\lineiii{script_name}{The name of the setup.py script - defaults to \code{sys.argv[0]}}{a string} -\lineiii{script_args}{Arguments to supply to the setup script}{a list of strings} -\lineiii{options}{default options for the setup script}{a string} -\lineiii{license}{The license for the package}{} -\lineiii{keywords}{Descriptive meta-data. See \pep{314}}{} -\lineiii{platforms}{}{} -\lineiii{cmdclass}{A mapping of command names to \class{Command} subclasses}{a dictionary} -\end{tableiii} - -\end{funcdesc} - -\begin{funcdesc}{run_setup}{script_name\optional{, script_args=\code{None}, stop_after=\code{'run'}}} -Run a setup script in a somewhat controlled environment, and return -the \class{distutils.dist.Distribution} instance that drives things. -This is useful if you need to find out the distribution meta-data -(passed as keyword args from \var{script} to \function{setup()}), or -the contents of the config files or command-line. - -\var{script_name} is a file that will be read and run with \function{exec()} -\code{sys.argv[0]} will be replaced with \var{script} for the duration of the -call. \var{script_args} is a list of strings; if supplied, -\code{sys.argv[1:]} will be replaced by \var{script_args} for the duration -of the call. - -\var{stop_after} tells \function{setup()} when to stop processing; possible -values: - -\begin{tableii}{c|l}{value}{value}{description} -\lineii{init}{Stop after the \class{Distribution} instance has been created -and populated with the keyword arguments to \function{setup()}} -\lineii{config}{Stop after config files have been parsed (and their data -stored in the \class{Distribution} instance)} -\lineii{commandline}{Stop after the command-line (\code{sys.argv[1:]} or -\var{script_args}) have been parsed (and the data stored in the -\class{Distribution} instance.)} -\lineii{run}{Stop after all commands have been run (the same as -if \function{setup()} had been called in the usual way). This is the default -value.} -\end{tableii} -\end{funcdesc} - -In addition, the \module{distutils.core} module exposed a number of -classes that live elsewhere. - -\begin{itemize} -\item \class{Extension} from \refmodule{distutils.extension} -\item \class{Command} from \refmodule{distutils.cmd} -\item \class{Distribution} from \refmodule{distutils.dist} -\end{itemize} - -A short description of each of these follows, but see the relevant -module for the full reference. - -\begin{classdesc*}{Extension} - -The Extension class describes a single C or \Cpp extension module in a -setup script. It accepts the following keyword arguments in its -constructor - -\begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type} -\lineiii{name}{the full name of the extension, including any packages ---- ie. \emph{not} a filename or pathname, but Python dotted name}{string} -\lineiii{sources}{list of source filenames, relative to the distribution -root (where the setup script lives), in \UNIX{} form (slash-separated) for -portability. Source files may be C, \Cpp, SWIG (.i), platform-specific -resource files, or whatever else is recognized by the \command{build_ext} -command as source for a Python extension.}{string} -\lineiii{include_dirs}{list of directories to search for C/\Cpp{} header -files (in \UNIX{} form for portability)}{string} -\lineiii{define_macros}{list of macros to define; each macro is defined -using a 2-tuple, where 'value' is either the string to define it to or -\code{None} to define it without a particular value (equivalent of -\code{\#define FOO} in source or \programopt{-DFOO} on \UNIX{} C -compiler command line) }{ (string,string) -tuple or (name,\code{None}) } -\lineiii{undef_macros}{list of macros to undefine explicitly}{string} -\lineiii{library_dirs}{list of directories to search for C/\Cpp{} libraries -at link time }{string} -\lineiii{libraries}{list of library names (not filenames or paths) to -link against }{string} -\lineiii{runtime_library_dirs}{list of directories to search for C/\Cpp{} -libraries at run time (for shared extensions, this is when the extension -is loaded)}{string} -\lineiii{extra_objects}{list of extra files to link with (eg. object -files not implied by 'sources', static library that must be explicitly -specified, binary resource files, etc.)}{string} -\lineiii{extra_compile_args}{any extra platform- and compiler-specific -information to use when compiling the source files in 'sources'. For -platforms and compilers where a command line makes sense, this is -typically a list of command-line arguments, but for other platforms it -could be anything.}{string} -\lineiii{extra_link_args}{any extra platform- and compiler-specific -information to use when linking object files together to create the -extension (or to create a new static Python interpreter). Similar -interpretation as for 'extra_compile_args'.}{string} -\lineiii{export_symbols}{list of symbols to be exported from a shared -extension. Not used on all platforms, and not generally necessary for -Python extensions, which typically export exactly one symbol: \code{init} + -extension_name. }{string} -\lineiii{depends}{list of files that the extension depends on }{string} -\lineiii{language}{extension language (i.e. \code{'c'}, \code{'c++'}, -\code{'objc'}). Will be detected from the source extensions if not provided. -}{string} -\end{tableiii} -\end{classdesc*} - -\begin{classdesc*}{Distribution} -A \class{Distribution} describes how to build, install and package up a -Python software package. - -See the \function{setup()} function for a list of keyword arguments accepted -by the Distribution constructor. \function{setup()} creates a Distribution -instance. -\end{classdesc*} - -\begin{classdesc*}{Command} -A \class{Command} class (or rather, an instance of one of its subclasses) -implement a single distutils command. -\end{classdesc*} - - -\section{\module{distutils.ccompiler} --- CCompiler base class} -\declaremodule{standard}{distutils.ccompiler} -\modulesynopsis{Abstract CCompiler class} - -This module provides the abstract base class for the \class{CCompiler} -classes. A \class{CCompiler} instance can be used for all the compile -and link steps needed to build a single project. Methods are provided to -set options for the compiler --- macro definitions, include directories, -link path, libraries and the like. - -This module provides the following functions. - -\begin{funcdesc}{gen_lib_options}{compiler, library_dirs, runtime_library_dirs, libraries} -Generate linker options for searching library directories and -linking with specific libraries. \var{libraries} and \var{library_dirs} are, -respectively, lists of library names (not filenames!) and search -directories. Returns a list of command-line options suitable for use -with some compiler (depending on the two format strings passed in). -\end{funcdesc} - -\begin{funcdesc}{gen_preprocess_options}{macros, include_dirs} -Generate C pre-processor options (\programopt{-D}, \programopt{-U}, -\programopt{-I}) as used by at least -two types of compilers: the typical \UNIX{} compiler and Visual \Cpp. -\var{macros} is the usual thing, a list of 1- or 2-tuples, where -\code{(\var{name},)} means undefine (\programopt{-U}) macro \var{name}, -and \code{(\var{name}, \var{value})} means define (\programopt{-D}) -macro \var{name} to \var{value}. \var{include_dirs} is just a list of -directory names to be added to the header file search path (\programopt{-I}). -Returns a list of command-line options suitable for either \UNIX{} compilers -or Visual \Cpp. -\end{funcdesc} - -\begin{funcdesc}{get_default_compiler}{osname, platform} -Determine the default compiler to use for the given platform. - -\var{osname} should be one of the standard Python OS names (i.e.\ the -ones returned by \code{os.name}) and \var{platform} the common value -returned by \code{sys.platform} for the platform in question. - -The default values are \code{os.name} and \code{sys.platform} in case the -parameters are not given. -\end{funcdesc} - -\begin{funcdesc}{new_compiler}{plat=\code{None}, compiler=\code{None}, verbose=\code{0}, dry_run=\code{0}, force=\code{0}} -Factory function to generate an instance of some CCompiler subclass -for the supplied platform/compiler combination. \var{plat} defaults -to \code{os.name} (eg. \code{'posix'}, \code{'nt'}), and \var{compiler} -defaults to the default compiler for that platform. Currently only -\code{'posix'} and \code{'nt'} are supported, and the default -compilers are ``traditional \UNIX{} interface'' (\class{UnixCCompiler} -class) and Visual \Cpp (\class{MSVCCompiler} class). Note that it's -perfectly possible to ask for a \UNIX{} compiler object under Windows, -and a Microsoft compiler object under \UNIX---if you supply a value -for \var{compiler}, \var{plat} is ignored. -% Is the posix/nt only thing still true? Mac OS X seems to work, and -% returns a UnixCCompiler instance. How to document this... hmm. -\end{funcdesc} - -\begin{funcdesc}{show_compilers}{} -Print list of available compilers (used by the -\longprogramopt{help-compiler} options to \command{build}, -\command{build_ext}, \command{build_clib}). -\end{funcdesc} - -\begin{classdesc}{CCompiler}{\optional{verbose=\code{0}, dry_run=\code{0}, force=\code{0}}} - -The abstract base class \class{CCompiler} defines the interface that -must be implemented by real compiler classes. The class also has -some utility methods used by several compiler classes. - -The basic idea behind a compiler abstraction class is that each -instance can be used for all the compile/link steps in building a -single project. Thus, attributes common to all of those compile and -link steps --- include directories, macros to define, libraries to link -against, etc. --- are attributes of the compiler instance. To allow for -variability in how individual files are treated, most of those -attributes may be varied on a per-compilation or per-link basis. - -The constructor for each subclass creates an instance of the Compiler -object. Flags are \var{verbose} (show verbose output), \var{dry_run} -(don't actually execute the steps) and \var{force} (rebuild -everything, regardless of dependencies). All of these flags default to -\code{0} (off). Note that you probably don't want to instantiate -\class{CCompiler} or one of its subclasses directly - use the -\function{distutils.CCompiler.new_compiler()} factory function -instead. - -The following methods allow you to manually alter compiler options for -the instance of the Compiler class. - -\begin{methoddesc}{add_include_dir}{dir} -Add \var{dir} to the list of directories that will be searched for -header files. The compiler is instructed to search directories in -the order in which they are supplied by successive calls to -\method{add_include_dir()}. -\end{methoddesc} - -\begin{methoddesc}{set_include_dirs}{dirs} -Set the list of directories that will be searched to \var{dirs} (a -list of strings). Overrides any preceding calls to -\method{add_include_dir()}; subsequent calls to -\method{add_include_dir()} add to the list passed to -\method{set_include_dirs()}. This does not affect any list of -standard include directories that the compiler may search by default. -\end{methoddesc} - -\begin{methoddesc}{add_library}{libname} - -Add \var{libname} to the list of libraries that will be included in -all links driven by this compiler object. Note that \var{libname} -should *not* be the name of a file containing a library, but the -name of the library itself: the actual filename will be inferred by -the linker, the compiler, or the compiler class (depending on the -platform). - -The linker will be instructed to link against libraries in the -order they were supplied to \method{add_library()} and/or -\method{set_libraries()}. It is perfectly valid to duplicate library -names; the linker will be instructed to link against libraries as -many times as they are mentioned. -\end{methoddesc} - -\begin{methoddesc}{set_libraries}{libnames} -Set the list of libraries to be included in all links driven by -this compiler object to \var{libnames} (a list of strings). This does -not affect any standard system libraries that the linker may -include by default. -\end{methoddesc} - -\begin{methoddesc}{add_library_dir}{dir} -Add \var{dir} to the list of directories that will be searched for -libraries specified to \method{add_library()} and -\method{set_libraries()}. The linker will be instructed to search for -libraries in the order they are supplied to \method{add_library_dir()} -and/or \method{set_library_dirs()}. -\end{methoddesc} - -\begin{methoddesc}{set_library_dirs}{dirs} -Set the list of library search directories to \var{dirs} (a list of -strings). This does not affect any standard library search path -that the linker may search by default. -\end{methoddesc} - -\begin{methoddesc}{add_runtime_library_dir}{dir} -Add \var{dir} to the list of directories that will be searched for -shared libraries at runtime. -\end{methoddesc} - -\begin{methoddesc}{set_runtime_library_dirs}{dirs} -Set the list of directories to search for shared libraries at -runtime to \var{dirs} (a list of strings). This does not affect any -standard search path that the runtime linker may search by -default. -\end{methoddesc} - -\begin{methoddesc}{define_macro}{name\optional{, value=\code{None}}} -Define a preprocessor macro for all compilations driven by this -compiler object. The optional parameter \var{value} should be a -string; if it is not supplied, then the macro will be defined -without an explicit value and the exact outcome depends on the -compiler used (XXX true? does ANSI say anything about this?) -\end{methoddesc} - -\begin{methoddesc}{undefine_macro}{name} -Undefine a preprocessor macro for all compilations driven by -this compiler object. If the same macro is defined by -\method{define_macro()} and undefined by \method{undefine_macro()} -the last call takes precedence (including multiple redefinitions or -undefinitions). If the macro is redefined/undefined on a -per-compilation basis (ie. in the call to \method{compile()}), then that -takes precedence. -\end{methoddesc} - -\begin{methoddesc}{add_link_object}{object} -Add \var{object} to the list of object files (or analogues, such as -explicitly named library files or the output of ``resource -compilers'') to be included in every link driven by this compiler -object. -\end{methoddesc} - -\begin{methoddesc}{set_link_objects}{objects} -Set the list of object files (or analogues) to be included in -every link to \var{objects}. This does not affect any standard object -files that the linker may include by default (such as system -libraries). -\end{methoddesc} - -The following methods implement methods for autodetection of compiler -options, providing some functionality similar to GNU \program{autoconf}. - -\begin{methoddesc}{detect_language}{sources} -Detect the language of a given file, or list of files. Uses the -instance attributes \member{language_map} (a dictionary), and -\member{language_order} (a list) to do the job. -\end{methoddesc} - -\begin{methoddesc}{find_library_file}{dirs, lib\optional{, debug=\code{0}}} -Search the specified list of directories for a static or shared -library file \var{lib} and return the full path to that file. If -\var{debug} is true, look for a debugging version (if that makes sense on -the current platform). Return \code{None} if \var{lib} wasn't found in any of -the specified directories. -\end{methoddesc} - -\begin{methoddesc}{has_function}{funcname \optional{, includes=\code{None}, include_dirs=\code{None}, libraries=\code{None}, library_dirs=\code{None}}} -Return a boolean indicating whether \var{funcname} is supported on -the current platform. The optional arguments can be used to -augment the compilation environment by providing additional include -files and paths and libraries and paths. -\end{methoddesc} - -\begin{methoddesc}{library_dir_option}{dir} -Return the compiler option to add \var{dir} to the list of -directories searched for libraries. -\end{methoddesc} - -\begin{methoddesc}{library_option}{lib} -Return the compiler option to add \var{dir} to the list of libraries -linked into the shared library or executable. -\end{methoddesc} - -\begin{methoddesc}{runtime_library_dir_option}{dir} -Return the compiler option to add \var{dir} to the list of -directories searched for runtime libraries. -\end{methoddesc} - -\begin{methoddesc}{set_executables}{**args} -Define the executables (and options for them) that will be run -to perform the various stages of compilation. The exact set of -executables that may be specified here depends on the compiler -class (via the 'executables' class attribute), but most will have: - -\begin{tableii}{l|l}{attribute}{attribute}{description} -\lineii{compiler}{the C/\Cpp{} compiler} -\lineii{linker_so}{linker used to create shared objects and libraries} -\lineii{linker_exe}{linker used to create binary executables} -\lineii{archiver}{static library creator} -\end{tableii} - -On platforms with a command-line (\UNIX, DOS/Windows), each of these -is a string that will be split into executable name and (optional) -list of arguments. (Splitting the string is done similarly to how -\UNIX{} shells operate: words are delimited by spaces, but quotes and -backslashes can override this. See -\function{distutils.util.split_quoted()}.) -\end{methoddesc} - -The following methods invoke stages in the build process. - -\begin{methoddesc}{compile}{sources\optional{, output_dir=\code{None}, macros=\code{None}, include_dirs=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, depends=\code{None}}} -Compile one or more source files. Generates object files (e.g. -transforms a \file{.c} file to a \file{.o} file.) - -\var{sources} must be a list of filenames, most likely C/\Cpp -files, but in reality anything that can be handled by a -particular compiler and compiler class (eg. \class{MSVCCompiler} can -handle resource files in \var{sources}). Return a list of object -filenames, one per source filename in \var{sources}. Depending on -the implementation, not all source files will necessarily be -compiled, but all corresponding object filenames will be -returned. - -If \var{output_dir} is given, object files will be put under it, while -retaining their original path component. That is, \file{foo/bar.c} -normally compiles to \file{foo/bar.o} (for a \UNIX{} implementation); if -\var{output_dir} is \var{build}, then it would compile to -\file{build/foo/bar.o}. - -\var{macros}, if given, must be a list of macro definitions. A macro -definition is either a \code{(\var{name}, \var{value})} 2-tuple or a -\code{(\var{name},)} 1-tuple. -The former defines a macro; if the value is \code{None}, the macro is -defined without an explicit value. The 1-tuple case undefines a -macro. Later definitions/redefinitions/undefinitions take -precedence. - -\var{include_dirs}, if given, must be a list of strings, the -directories to add to the default include file search path for this -compilation only. - -\var{debug} is a boolean; if true, the compiler will be instructed to -output debug symbols in (or alongside) the object file(s). - -\var{extra_preargs} and \var{extra_postargs} are implementation-dependent. -On platforms that have the notion of a command-line (e.g. \UNIX, -DOS/Windows), they are most likely lists of strings: extra -command-line arguments to prepend/append to the compiler command -line. On other platforms, consult the implementation class -documentation. In any event, they are intended as an escape hatch -for those occasions when the abstract compiler framework doesn't -cut the mustard. - -\var{depends}, if given, is a list of filenames that all targets -depend on. If a source file is older than any file in -depends, then the source file will be recompiled. This -supports dependency tracking, but only at a coarse -granularity. - -Raises \exception{CompileError} on failure. -\end{methoddesc} - -\begin{methoddesc}{create_static_lib}{objects, output_libname\optional{, output_dir=\code{None}, debug=\code{0}, target_lang=\code{None}}} -Link a bunch of stuff together to create a static library file. -The ``bunch of stuff'' consists of the list of object files supplied -as \var{objects}, the extra object files supplied to -\method{add_link_object()} and/or \method{set_link_objects()}, the libraries -supplied to \method{add_library()} and/or \method{set_libraries()}, and the -libraries supplied as \var{libraries} (if any). - -\var{output_libname} should be a library name, not a filename; the -filename will be inferred from the library name. \var{output_dir} is -the directory where the library file will be put. XXX defaults to what? - -\var{debug} is a boolean; if true, debugging information will be -included in the library (note that on most platforms, it is the -compile step where this matters: the \var{debug} flag is included here -just for consistency). - -\var{target_lang} is the target language for which the given objects -are being compiled. This allows specific linkage time treatment of -certain languages. - -Raises \exception{LibError} on failure. -\end{methoddesc} - -\begin{methoddesc}{link}{target_desc, objects, output_filename\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}} -Link a bunch of stuff together to create an executable or -shared library file. - -The ``bunch of stuff'' consists of the list of object files supplied -as \var{objects}. \var{output_filename} should be a filename. If -\var{output_dir} is supplied, \var{output_filename} is relative to it -(i.e. \var{output_filename} can provide directory components if -needed). - -\var{libraries} is a list of libraries to link against. These are -library names, not filenames, since they're translated into -filenames in a platform-specific way (eg. \var{foo} becomes \file{libfoo.a} -on \UNIX{} and \file{foo.lib} on DOS/Windows). However, they can include a -directory component, which means the linker will look in that -specific directory rather than searching all the normal locations. - -\var{library_dirs}, if supplied, should be a list of directories to -search for libraries that were specified as bare library names -(ie. no directory component). These are on top of the system -default and those supplied to \method{add_library_dir()} and/or -\method{set_library_dirs()}. \var{runtime_library_dirs} is a list of -directories that will be embedded into the shared library and used -to search for other shared libraries that *it* depends on at -run-time. (This may only be relevant on \UNIX.) - -\var{export_symbols} is a list of symbols that the shared library will -export. (This appears to be relevant only on Windows.) - -\var{debug} is as for \method{compile()} and \method{create_static_lib()}, -with the slight distinction that it actually matters on most platforms (as -opposed to \method{create_static_lib()}, which includes a \var{debug} flag -mostly for form's sake). - -\var{extra_preargs} and \var{extra_postargs} are as for \method{compile()} -(except of course that they supply command-line arguments for the -particular linker being used). - -\var{target_lang} is the target language for which the given objects -are being compiled. This allows specific linkage time treatment of -certain languages. - -Raises \exception{LinkError} on failure. -\end{methoddesc} - -\begin{methoddesc}{link_executable}{objects, output_progname\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, target_lang=\code{None}}} -Link an executable. -\var{output_progname} is the name of the file executable, -while \var{objects} are a list of object filenames to link in. Other arguments -are as for the \method{link} method. -\end{methoddesc} - -\begin{methoddesc}{link_shared_lib}{objects, output_libname\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}} -Link a shared library. \var{output_libname} is the name of the output -library, while \var{objects} is a list of object filenames to link in. -Other arguments are as for the \method{link} method. -\end{methoddesc} - -\begin{methoddesc}{link_shared_object}{objects, output_filename\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}} -Link a shared object. \var{output_filename} is the name of the shared object -that will be created, while \var{objects} is a list of object filenames -to link in. Other arguments are as for the \method{link} method. -\end{methoddesc} - -\begin{methoddesc}{preprocess}{source\optional{, output_file=\code{None}, macros=\code{None}, include_dirs=\code{None}, extra_preargs=\code{None}, extra_postargs=\code{None}}} -Preprocess a single C/\Cpp{} source file, named in \var{source}. -Output will be written to file named \var{output_file}, or \var{stdout} if -\var{output_file} not supplied. \var{macros} is a list of macro -definitions as for \method{compile()}, which will augment the macros set -with \method{define_macro()} and \method{undefine_macro()}. -\var{include_dirs} is a list of directory names that will be added to the -default list, in the same way as \method{add_include_dir()}. - -Raises \exception{PreprocessError} on failure. -\end{methoddesc} - -The following utility methods are defined by the \class{CCompiler} class, -for use by the various concrete subclasses. - -\begin{methoddesc}{executable_filename}{basename\optional{, strip_dir=\code{0}, output_dir=\code{''}}} -Returns the filename of the executable for the given \var{basename}. -Typically for non-Windows platforms this is the same as the basename, -while Windows will get a \file{.exe} added. -\end{methoddesc} - -\begin{methoddesc}{library_filename}{libname\optional{, lib_type=\code{'static'}, strip_dir=\code{0}, output_dir=\code{''}}} -Returns the filename for the given library name on the current platform. -On \UNIX{} a library with \var{lib_type} of \code{'static'} will typically -be of the form \file{liblibname.a}, while a \var{lib_type} of \code{'dynamic'} -will be of the form \file{liblibname.so}. -\end{methoddesc} - -\begin{methoddesc}{object_filenames}{source_filenames\optional{, strip_dir=\code{0}, output_dir=\code{''}}} -Returns the name of the object files for the given source files. -\var{source_filenames} should be a list of filenames. -\end{methoddesc} - -\begin{methoddesc}{shared_object_filename}{basename\optional{, strip_dir=\code{0}, output_dir=\code{''}}} -Returns the name of a shared object file for the given file name \var{basename}. -\end{methoddesc} - -\begin{methoddesc}{execute}{func, args\optional{, msg=\code{None}, level=\code{1}}} -Invokes \function{distutils.util.execute()} This method invokes a -Python function \var{func} with the given arguments \var{args}, after -logging and taking into account the \var{dry_run} flag. XXX see also. -\end{methoddesc} - -\begin{methoddesc}{spawn}{cmd} -Invokes \function{distutils.util.spawn()}. This invokes an external -process to run the given command. XXX see also. -\end{methoddesc} - -\begin{methoddesc}{mkpath}{name\optional{, mode=\code{511}}} - -Invokes \function{distutils.dir_util.mkpath()}. This creates a directory -and any missing ancestor directories. XXX see also. -\end{methoddesc} - -\begin{methoddesc}{move_file}{src, dst} -Invokes \method{distutils.file_util.move_file()}. Renames \var{src} to -\var{dst}. XXX see also. -\end{methoddesc} - -\begin{methoddesc}{announce}{msg\optional{, level=\code{1}}} -Write a message using \function{distutils.log.debug()}. XXX see also. -\end{methoddesc} - -\begin{methoddesc}{warn}{msg} -Write a warning message \var{msg} to standard error. -\end{methoddesc} - -\begin{methoddesc}{debug_print}{msg} -If the \var{debug} flag is set on this \class{CCompiler} instance, print -\var{msg} to standard output, otherwise do nothing. -\end{methoddesc} - -\end{classdesc} - -%\subsection{Compiler-specific modules} -% -%The following modules implement concrete subclasses of the abstract -%\class{CCompiler} class. They should not be instantiated directly, but should -%be created using \function{distutils.ccompiler.new_compiler()} factory -%function. - -\section{\module{distutils.unixccompiler} --- Unix C Compiler} -\declaremodule{standard}{distutils.unixccompiler} -\modulesynopsis{UNIX C Compiler} - -This module provides the \class{UnixCCompiler} class, a subclass of -\class{CCompiler} that handles the typical \UNIX-style command-line -C compiler: - -\begin{itemize} -\item macros defined with \programopt{-D\var{name}\optional{=value}} -\item macros undefined with \programopt{-U\var{name}} -\item include search directories specified with - \programopt{-I\var{dir}} -\item libraries specified with \programopt{-l\var{lib}} -\item library search directories specified with \programopt{-L\var{dir}} -\item compile handled by \program{cc} (or similar) executable with - \programopt{-c} option: compiles \file{.c} to \file{.o} -\item link static library handled by \program{ar} command (possibly - with \program{ranlib}) -\item link shared library handled by \program{cc} \programopt{-shared} -\end{itemize} - -\section{\module{distutils.msvccompiler} --- Microsoft Compiler} -\declaremodule{standard}{distutils.msvccompiler} -\modulesynopsis{Microsoft Compiler} - -This module provides \class{MSVCCompiler}, an implementation of the abstract -\class{CCompiler} class for Microsoft Visual Studio. Typically, extension -modules need to be compiled with the same compiler that was used to compile -Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For -Python 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 -and Itanium binaries are created using the Platform SDK. - -\class{MSVCCompiler} will normally choose the right compiler, linker etc. -on its own. To override this choice, the environment variables -\var{DISTUTILS\_USE\_SDK} and \var{MSSdk} must be both set. \var{MSSdk} -indicates that the current environment has been setup by the SDK's -\code{SetEnv.Cmd} script, or that the environment variables had been -registered when the SDK was installed; \var{DISTUTILS\_USE\_SDK} indicates -that the distutils user has made an explicit choice to override the -compiler selection by \class{MSVCCompiler}. - -\section{\module{distutils.bcppcompiler} --- Borland Compiler} -\declaremodule{standard}{distutils.bcppcompiler} -This module provides \class{BorlandCCompiler}, an subclass of the abstract \class{CCompiler} class for the Borland \Cpp{} compiler. - -\section{\module{distutils.cygwincompiler} --- Cygwin Compiler} -\declaremodule{standard}{distutils.cygwinccompiler} - -This module provides the \class{CygwinCCompiler} class, a subclass of \class{UnixCCompiler} that -handles the Cygwin port of the GNU C compiler to Windows. It also contains -the Mingw32CCompiler class which handles the mingw32 port of GCC (same as -cygwin in no-cygwin mode). - -\section{\module{distutils.emxccompiler} --- OS/2 EMX Compiler} -\declaremodule{standard}{distutils.emxccompiler} -\modulesynopsis{OS/2 EMX Compiler support} - -This module provides the EMXCCompiler class, a subclass of \class{UnixCCompiler} that handles the EMX port of the GNU C compiler to OS/2. - -\section{\module{distutils.mwerkscompiler} --- Metrowerks CodeWarrior support} -\declaremodule{standard}{distutils.mwerkscompiler} -\modulesynopsis{Metrowerks CodeWarrior support} - -Contains \class{MWerksCompiler}, an implementation of the abstract -\class{CCompiler} class for MetroWerks CodeWarrior on the pre-Mac OS X Macintosh. -Needs work to support CW on Windows or Mac OS X. - - -%\subsection{Utility modules} -% -%The following modules all provide general utility functions. They haven't -%all been documented yet. - -\section{\module{distutils.archive_util} --- - Archiving utilities} -\declaremodule[distutils.archiveutil]{standard}{distutils.archive_util} -\modulesynopsis{Utility functions for creating archive files (tarballs, zip files, ...)} - -This module provides a few functions for creating archive files, such as -tarballs or zipfiles. - -\begin{funcdesc}{make_archive}{base_name, format\optional{, root_dir=\code{None}, base_dir=\code{None}, verbose=\code{0}, dry_run=\code{0}}} -Create an archive file (eg. \code{zip} or \code{tar}). \var{base_name} -is the name of the file to create, minus any format-specific extension; -\var{format} is the archive format: one of \code{zip}, \code{tar}, -\code{ztar}, or \code{gztar}. -\var{root_dir} is a directory that will be the root directory of the -archive; ie. we typically \code{chdir} into \var{root_dir} before -creating the archive. \var{base_dir} is the directory where we start -archiving from; ie. \var{base_dir} will be the common prefix of all files and -directories in the archive. \var{root_dir} and \var{base_dir} both default -to the current directory. Returns the name of the archive file. - -\warning{This should be changed to support bz2 files} -\end{funcdesc} - -\begin{funcdesc}{make_tarball}{base_name, base_dir\optional{, compress=\code{'gzip'}, verbose=\code{0}, dry_run=\code{0}}}'Create an (optional compressed) archive as a tar file from all files in and under \var{base_dir}. \var{compress} must be \code{'gzip'} (the default), -\code{'compress'}, \code{'bzip2'}, or \code{None}. Both \program{tar} -and the compression utility named by \var{compress} must be on the -default program search path, so this is probably \UNIX-specific. The -output tar file will be named \file{\var{base_dir}.tar}, possibly plus -the appropriate compression extension (\file{.gz}, \file{.bz2} or -\file{.Z}). Return the output filename. - -\warning{This should be replaced with calls to the \module{tarfile} module.} -\end{funcdesc} - -\begin{funcdesc}{make_zipfile}{base_name, base_dir\optional{, verbose=\code{0}, dry_run=\code{0}}} -Create a zip file from all files in and under \var{base_dir}. The output -zip file will be named \var{base_dir} + \file{.zip}. Uses either the -\module{zipfile} Python module (if available) or the InfoZIP \file{zip} -utility (if installed and found on the default search path). If neither -tool is available, raises \exception{DistutilsExecError}. -Returns the name of the output zip file. -\end{funcdesc} - -\section{\module{distutils.dep_util} --- Dependency checking} -\declaremodule[distutils.deputil]{standard}{distutils.dep_util} -\modulesynopsis{Utility functions for simple dependency checking} - -This module provides functions for performing simple, timestamp-based -dependency of files and groups of files; also, functions based entirely -on such timestamp dependency analysis. - -\begin{funcdesc}{newer}{source, target} -Return true if \var{source} exists and is more recently modified than -\var{target}, or if \var{source} exists and \var{target} doesn't. -Return false if both exist and \var{target} is the same age or newer -than \var{source}. -Raise \exception{DistutilsFileError} if \var{source} does not exist. -\end{funcdesc} - -\begin{funcdesc}{newer_pairwise}{sources, targets} -Walk two filename lists in parallel, testing if each source is newer -than its corresponding target. Return a pair of lists (\var{sources}, -\var{targets}) where source is newer than target, according to the semantics -of \function{newer()} -%% equivalent to a listcomp... -\end{funcdesc} - -\begin{funcdesc}{newer_group}{sources, target\optional{, missing=\code{'error'}}} -Return true if \var{target} is out-of-date with respect to any file -listed in \var{sources} In other words, if \var{target} exists and is newer -than every file in \var{sources}, return false; otherwise return true. -\var{missing} controls what we do when a source file is missing; the -default (\code{'error'}) is to blow up with an \exception{OSError} from -inside \function{os.stat()}; -if it is \code{'ignore'}, we silently drop any missing source files; if it is -\code{'newer'}, any missing source files make us assume that \var{target} is -out-of-date (this is handy in ``dry-run'' mode: it'll make you pretend to -carry out commands that wouldn't work because inputs are missing, but -that doesn't matter because you're not actually going to run the -commands). -\end{funcdesc} - -\section{\module{distutils.dir_util} --- Directory tree operations} -\declaremodule[distutils.dirutil]{standard}{distutils.dir_util} -\modulesynopsis{Utility functions for operating on directories and directory trees} - -This module provides functions for operating on directories and trees -of directories. - -\begin{funcdesc}{mkpath}{name\optional{, mode=\code{0777}, verbose=\code{0}, dry_run=\code{0}}} -Create a directory and any missing ancestor directories. If the -directory already exists (or if \var{name} is the empty string, which -means the current directory, which of course exists), then do -nothing. Raise \exception{DistutilsFileError} if unable to create some -directory along the way (eg. some sub-path exists, but is a file -rather than a directory). If \var{verbose} is true, print a one-line -summary of each mkdir to stdout. Return the list of directories -actually created. -\end{funcdesc} - -\begin{funcdesc}{create_tree}{base_dir, files\optional{, mode=\code{0777}, verbose=\code{0}, dry_run=\code{0}}} -Create all the empty directories under \var{base_dir} needed to -put \var{files} there. \var{base_dir} is just the a name of a directory -which doesn't necessarily exist yet; \var{files} is a list of filenames -to be interpreted relative to \var{base_dir}. \var{base_dir} + the -directory portion of every file in \var{files} will be created if it -doesn't already exist. \var{mode}, \var{verbose} and \var{dry_run} flags -are as for \function{mkpath()}. -\end{funcdesc} - -\begin{funcdesc}{copy_tree}{src, dst\optional{preserve_mode=\code{1}, preserve_times=\code{1}, preserve_symlinks=\code{0}, update=\code{0}, verbose=\code{0}, dry_run=\code{0}}} -Copy an entire directory tree \var{src} to a new location \var{dst}. Both -\var{src} and \var{dst} must be directory names. If \var{src} is not a -directory, raise \exception{DistutilsFileError}. If \var{dst} does -not exist, it is created with \function{mkpath()}. The end result of the -copy is that every file in \var{src} is copied to \var{dst}, and -directories under \var{src} are recursively copied to \var{dst}. -Return the list of files that were copied or might have been copied, -using their output name. The return value is unaffected by \var{update} -or \var{dry_run}: it is simply the list of all files under \var{src}, -with the names changed to be under \var{dst}. - -\var{preserve_mode} and \var{preserve_times} are the same as for -\function{copy_file} in \refmodule[distutils.fileutil]{distutils.file_util}; -note that they only apply to regular files, not to directories. If -\var{preserve_symlinks} is true, symlinks will be copied as symlinks -(on platforms that support them!); otherwise (the default), the -destination of the symlink will be copied. \var{update} and -\var{verbose} are the same as for -\function{copy_file()}. -\end{funcdesc} - -\begin{funcdesc}{remove_tree}{directory\optional{verbose=\code{0}, dry_run=\code{0}}} -Recursively remove \var{directory} and all files and directories underneath -it. Any errors are ignored (apart from being reported to \code{sys.stdout} if -\var{verbose} is true). -\end{funcdesc} - -\XXX{Some of this could be replaced with the shutil module?} - -\section{\module{distutils.file_util} --- Single file operations} -\declaremodule[distutils.fileutil]{standard}{distutils.file_util} -\modulesynopsis{Utility functions for operating on single files} - -This module contains some utility functions for operating on individual files. - -\begin{funcdesc}{copy_file}{src, dst\optional{preserve_mode=\code{1}, preserve_times=\code{1}, update=\code{0}, link=\code{None}, verbose=\code{0}, dry_run=\code{0}}} -Copy file \var{src} to \var{dst}. If \var{dst} is a directory, then -\var{src} is copied there with the same name; otherwise, it must be a -filename. (If the file exists, it will be ruthlessly clobbered.) If -\var{preserve_mode} is true (the default), the file's mode (type and -permission bits, or whatever is analogous on the current platform) is -copied. If \var{preserve_times} is true (the default), the last-modified -and last-access times are copied as well. If \var{update} is true, -\var{src} will only be copied if \var{dst} does not exist, or if -\var{dst} does exist but is older than \var{src}. - -\var{link} allows you to make hard links (using \function{os.link}) or -symbolic links (using \function{os.symlink}) instead of copying: set it -to \code{'hard'} or \code{'sym'}; if it is \code{None} (the default), -files are copied. Don't set \var{link} on systems that don't support -it: \function{copy_file()} doesn't check if hard or symbolic linking is -available. It uses \function{_copy_file_contents()} to copy file contents. - -Return a tuple \samp{(dest_name, copied)}: \var{dest_name} is the actual -name of the output file, and \var{copied} is true if the file was copied -(or would have been copied, if \var{dry_run} true). -% XXX if the destination file already exists, we clobber it if -% copying, but blow up if linking. Hmmm. And I don't know what -% macostools.copyfile() does. Should definitely be consistent, and -% should probably blow up if destination exists and we would be -% changing it (ie. it's not already a hard/soft link to src OR -% (not update) and (src newer than dst)). -\end{funcdesc} - -\begin{funcdesc}{move_file}{src, dst\optional{verbose, dry_run}} -Move file \var{src} to \var{dst}. If \var{dst} is a directory, the file will -be moved into it with the same name; otherwise, \var{src} is just renamed -to \var{dst}. Returns the new full name of the file. -\warning{Handles cross-device moves on \UNIX{} using \function{copy_file()}. -What about other systems???} -\end{funcdesc} - -\begin{funcdesc}{write_file}{filename, contents} -Create a file called \var{filename} and write \var{contents} (a -sequence of strings without line terminators) to it. -\end{funcdesc} - -\section{\module{distutils.util} --- Miscellaneous other utility functions} -\declaremodule{standard}{distutils.util} -\modulesynopsis{Miscellaneous other utility functions} - -This module contains other assorted bits and pieces that don't fit into -any other utility module. - -\begin{funcdesc}{get_platform}{} -Return a string that identifies the current platform. This is used -mainly to distinguish platform-specific build directories and -platform-specific built distributions. Typically includes the OS name -and version and the architecture (as supplied by 'os.uname()'), -although the exact information included depends on the OS; eg. for IRIX -the architecture isn't particularly important (IRIX only runs on SGI -hardware), but for Linux the kernel version isn't particularly -important. - -Examples of returned values: -\begin{itemize} -\item \code{linux-i586} -\item \code{linux-alpha} -\item \code{solaris-2.6-sun4u} -\item \code{irix-5.3} -\item \code{irix64-6.2} -\end{itemize} - -For non-\POSIX{} platforms, currently just returns \code{sys.platform}. -% XXX isn't this also provided by some other non-distutils module? -\end{funcdesc} - -\begin{funcdesc}{convert_path}{pathname} -Return 'pathname' as a name that will work on the native filesystem, -i.e. split it on '/' and put it back together again using the current -directory separator. Needed because filenames in the setup script are -always supplied in \UNIX{} style, and have to be converted to the local -convention before we can actually use them in the filesystem. Raises -\exception{ValueError} on non-\UNIX-ish systems if \var{pathname} either -starts or ends with a slash. -\end{funcdesc} - -\begin{funcdesc}{change_root}{new_root, pathname} -Return \var{pathname} with \var{new_root} prepended. If \var{pathname} is -relative, this is equivalent to \samp{os.path.join(new_root,pathname)} -Otherwise, it requires making \var{pathname} relative and then joining the -two, which is tricky on DOS/Windows. -\end{funcdesc} - -\begin{funcdesc}{check_environ}{} -Ensure that 'os.environ' has all the environment variables we -guarantee that users can use in config files, command-line options, -etc. Currently this includes: -\begin{itemize} -\item \envvar{HOME} - user's home directory (\UNIX{} only) -\item \envvar{PLAT} - description of the current platform, including - hardware and OS (see \function{get_platform()}) -\end{itemize} -\end{funcdesc} - -\begin{funcdesc}{subst_vars}{s, local_vars} -Perform shell/Perl-style variable substitution on \var{s}. Every -occurrence of \code{\$} followed by a name is considered a variable, and -variable is substituted by the value found in the \var{local_vars} -dictionary, or in \code{os.environ} if it's not in \var{local_vars}. -\var{os.environ} is first checked/augmented to guarantee that it contains -certain values: see \function{check_environ()}. Raise \exception{ValueError} -for any variables not found in either \var{local_vars} or \code{os.environ}. - -Note that this is not a fully-fledged string interpolation function. A -valid \code{\$variable} can consist only of upper and lower case letters, -numbers and an underscore. No \{ \} or ( ) style quoting is available. -\end{funcdesc} - -\begin{funcdesc}{grok_environment_error}{exc\optional{, prefix=\samp{'error: '}}} -Generate a useful error message from an \exception{EnvironmentError} -(\exception{IOError} or \exception{OSError}) exception object. -Handles Python 1.5.1 and later styles, and does what it can to deal with -exception objects that don't have a filename (which happens when the error -is due to a two-file operation, such as \function{rename()} or -\function{link()}). Returns the error message as a string prefixed -with \var{prefix}. -\end{funcdesc} - -\begin{funcdesc}{split_quoted}{s} -Split a string up according to \UNIX{} shell-like rules for quotes and -backslashes. In short: words are delimited by spaces, as long as those -spaces are not escaped by a backslash, or inside a quoted string. -Single and double quotes are equivalent, and the quote characters can -be backslash-escaped. The backslash is stripped from any two-character -escape sequence, leaving only the escaped character. The quote -characters are stripped from any quoted string. Returns a list of -words. -% Should probably be moved into the standard library. -\end{funcdesc} - -\begin{funcdesc}{execute}{func, args\optional{, msg=\code{None}, verbose=\code{0}, dry_run=\code{0}}} -Perform some action that affects the outside world (for instance, -writing to the filesystem). Such actions are special because they -are disabled by the \var{dry_run} flag. This method takes -care of all that bureaucracy for you; all you have to do is supply the -function to call and an argument tuple for it (to embody the -``external action'' being performed), and an optional message to -print. -\end{funcdesc} - -\begin{funcdesc}{strtobool}{val} -Convert a string representation of truth to true (1) or false (0). - -True values are \code{y}, \code{yes}, \code{t}, \code{true}, \code{on} -and \code{1}; false values are \code{n}, \code{no}, \code{f}, \code{false}, -\code{off} and \code{0}. Raises \exception{ValueError} if \var{val} -is anything else. -\end{funcdesc} - -\begin{funcdesc}{byte_compile}{py_files\optional{, - optimize=\code{0}, force=\code{0}, - prefix=\code{None}, base_dir=\code{None}, - verbose=\code{1}, dry_run=\code{0}, - direct=\code{None}}} -Byte-compile a collection of Python source files to either \file{.pyc} -or \file{.pyo} files in the same directory. \var{py_files} is a list of files -to compile; any files that don't end in \file{.py} are silently skipped. -\var{optimize} must be one of the following: -\begin{itemize} -\item \code{0} - don't optimize (generate \file{.pyc}) -\item \code{1} - normal optimization (like \samp{python -O}) -\item \code{2} - extra optimization (like \samp{python -OO}) -\end{itemize} - -If \var{force} is true, all files are recompiled regardless of -timestamps. - -The source filename encoded in each bytecode file defaults to the -filenames listed in \var{py_files}; you can modify these with \var{prefix} and -\var{basedir}. \var{prefix} is a string that will be stripped off of each -source filename, and \var{base_dir} is a directory name that will be -prepended (after \var{prefix} is stripped). You can supply either or both -(or neither) of \var{prefix} and \var{base_dir}, as you wish. - -If \var{dry_run} is true, doesn't actually do anything that would -affect the filesystem. - -Byte-compilation is either done directly in this interpreter process -with the standard \module{py_compile} module, or indirectly by writing a -temporary script and executing it. Normally, you should let -\function{byte_compile()} figure out to use direct compilation or not (see -the source for details). The \var{direct} flag is used by the script -generated in indirect mode; unless you know what you're doing, leave -it set to \code{None}. -\end{funcdesc} - -\begin{funcdesc}{rfc822_escape}{header} -Return a version of \var{header} escaped for inclusion in an -\rfc{822} header, by ensuring there are 8 spaces space after each newline. -Note that it does no other modification of the string. -% this _can_ be replaced -\end{funcdesc} - -%\subsection{Distutils objects} - -\section{\module{distutils.dist} --- The Distribution class} -\declaremodule{standard}{distutils.dist} -\modulesynopsis{Provides the Distribution class, which represents the - module distribution being built/installed/distributed} - -This module provides the \class{Distribution} class, which represents -the module distribution being built/installed/distributed. - - -\section{\module{distutils.extension} --- The Extension class} -\declaremodule{standard}{distutils.extension} -\modulesynopsis{Provides the Extension class, used to describe - C/\Cpp{} extension modules in setup scripts} - -This module provides the \class{Extension} class, used to describe -C/\Cpp{} extension modules in setup scripts. - -%\subsection{Ungrouped modules} -%The following haven't been moved into a more appropriate section yet. - -\section{\module{distutils.debug} --- Distutils debug mode} -\declaremodule{standard}{distutils.debug} -\modulesynopsis{Provides the debug flag for distutils} - -This module provides the DEBUG flag. - -\section{\module{distutils.errors} --- Distutils exceptions} -\declaremodule{standard}{distutils.errors} -\modulesynopsis{Provides standard distutils exceptions} - -Provides exceptions used by the Distutils modules. Note that Distutils -modules may raise standard exceptions; in particular, SystemExit is -usually raised for errors that are obviously the end-user's fault -(eg. bad command-line arguments). - -This module is safe to use in \samp{from ... import *} mode; it only exports -symbols whose names start with \code{Distutils} and end with \code{Error}. - -\section{\module{distutils.fancy_getopt} - --- Wrapper around the standard getopt module} -\declaremodule[distutils.fancygetopt]{standard}{distutils.fancy_getopt} -\modulesynopsis{Additional \module{getopt} functionality} - -This module provides a wrapper around the standard \module{getopt} -module that provides the following additional features: - -\begin{itemize} -\item short and long options are tied together -\item options have help strings, so \function{fancy_getopt} could potentially -create a complete usage summary -\item options set attributes of a passed-in object -\item boolean options can have ``negative aliases'' --- eg. if -\longprogramopt{quiet} is the ``negative alias'' of -\longprogramopt{verbose}, then \longprogramopt{quiet} on the command -line sets \var{verbose} to false. - -\end{itemize} - -\XXX{Should be replaced with \module{optik} (which is also now -known as \module{optparse} in Python 2.3 and later).} - -\begin{funcdesc}{fancy_getopt}{options, negative_opt, object, args} -Wrapper function. \var{options} is a list of -\samp{(long_option, short_option, help_string)} 3-tuples as described in the -constructor for \class{FancyGetopt}. \var{negative_opt} should be a dictionary -mapping option names to option names, both the key and value should be in the -\var{options} list. \var{object} is an object which will be used to store -values (see the \method{getopt()} method of the \class{FancyGetopt} class). -\var{args} is the argument list. Will use \code{sys.argv[1:]} if you -pass \code{None} as \var{args}. -\end{funcdesc} - -\begin{funcdesc}{wrap_text}{text, width} -Wraps \var{text} to less than \var{width} wide. - -\warning{Should be replaced with \module{textwrap} (which is available -in Python 2.3 and later).} -\end{funcdesc} - -\begin{classdesc}{FancyGetopt}{\optional{option_table=\code{None}}} -The option_table is a list of 3-tuples: \samp{(long_option, -short_option, help_string)} - -If an option takes an argument, its \var{long_option} should have \code{'='} -appended; \var{short_option} should just be a single character, no \code{':'} -in any case. \var{short_option} should be \code{None} if a \var{long_option} -doesn't have a corresponding \var{short_option}. All option tuples must have -long options. -\end{classdesc} - -The \class{FancyGetopt} class provides the following methods: - -\begin{methoddesc}{getopt}{\optional{args=\code{None}, object=\code{None}}} -Parse command-line options in args. Store as attributes on \var{object}. - -If \var{args} is \code{None} or not supplied, uses \code{sys.argv[1:]}. If -\var{object} is \code{None} or not supplied, creates a new \class{OptionDummy} -instance, stores option values there, and returns a tuple \samp{(args, -object)}. If \var{object} is supplied, it is modified in place and -\function{getopt()} just returns \var{args}; in both cases, the returned -\var{args} is a modified copy of the passed-in \var{args} list, which -is left untouched. -% and args returned are? -\end{methoddesc} - -\begin{methoddesc}{get_option_order}{} -Returns the list of \samp{(option, value)} tuples processed by the -previous run of \method{getopt()} Raises \exception{RuntimeError} if -\method{getopt()} hasn't been called yet. -\end{methoddesc} - -\begin{methoddesc}{generate_help}{\optional{header=\code{None}}} -Generate help text (a list of strings, one per suggested line of -output) from the option table for this \class{FancyGetopt} object. - -If supplied, prints the supplied \var{header} at the top of the help. -\end{methoddesc} - -\section{\module{distutils.filelist} --- The FileList class} -\declaremodule{standard}{distutils.filelist} -\modulesynopsis{The \class{FileList} class, used for poking about the - file system and building lists of files.} - -This module provides the \class{FileList} class, used for poking about -the filesystem and building lists of files. - - -\section{\module{distutils.log} --- Simple PEP 282-style logging} -\declaremodule{standard}{distutils.log} -\modulesynopsis{A simple logging mechanism, \pep{282}-style} - -\warning{Should be replaced with standard \module{logging} module.} - -%\subsubsection{\module{} --- } -%\declaremodule{standard}{distutils.magic} -%\modulesynopsis{ } - - -\section{\module{distutils.spawn} --- Spawn a sub-process} -\declaremodule{standard}{distutils.spawn} -\modulesynopsis{Provides the spawn() function} - -This module provides the \function{spawn()} function, a front-end to -various platform-specific functions for launching another program in a -sub-process. -Also provides \function{find_executable()} to search the path for a given -executable name. - - -\input{sysconfig} - - -\section{\module{distutils.text_file} --- The TextFile class} -\declaremodule[distutils.textfile]{standard}{distutils.text_file} -\modulesynopsis{provides the TextFile class, a simple interface to text files} - -This module provides the \class{TextFile} class, which gives an interface -to text files that (optionally) takes care of stripping comments, ignoring -blank lines, and joining lines with backslashes. - -\begin{classdesc}{TextFile}{\optional{filename=\code{None}, file=\code{None}, **options}} -This class provides a file-like object that takes care of all -the things you commonly want to do when processing a text file -that has some line-by-line syntax: strip comments (as long as \code{\#} -is your comment character), skip blank lines, join adjacent lines by -escaping the newline (ie. backslash at end of line), strip -leading and/or trailing whitespace. All of these are optional -and independently controllable. - -The class provides a \method{warn()} method so you can generate -warning messages that report physical line number, even if the -logical line in question spans multiple physical lines. Also -provides \method{unreadline()} for implementing line-at-a-time lookahead. - -\class{TextFile} instances are create with either \var{filename}, \var{file}, -or both. \exception{RuntimeError} is raised if both are \code{None}. -\var{filename} should be a string, and \var{file} a file object (or -something that provides \method{readline()} and \method{close()} -methods). It is recommended that you supply at least \var{filename}, -so that \class{TextFile} can include it in warning messages. If -\var{file} is not supplied, \class{TextFile} creates its own using the -\function{open()} built-in function. - -The options are all boolean, and affect the values returned by -\method{readline()} - -\begin{tableiii}{c|l|l}{option name}{option name}{description}{default} -\lineiii{strip_comments}{ -strip from \character{\#} to end-of-line, as well as any whitespace -leading up to the \character{\#}---unless it is escaped by a backslash} -{true} -\lineiii{lstrip_ws}{ -strip leading whitespace from each line before returning it} -{false} -\lineiii{rstrip_ws}{ -strip trailing whitespace (including line terminator!) from -each line before returning it.} -{true} -\lineiii{skip_blanks}{ -skip lines that are empty *after* stripping comments and -whitespace. (If both lstrip_ws and rstrip_ws are false, -then some lines may consist of solely whitespace: these will -*not* be skipped, even if \var{skip_blanks} is true.)} -{true} -\lineiii{join_lines}{ -if a backslash is the last non-newline character on a line -after stripping comments and whitespace, join the following line -to it to form one logical line; if N consecutive lines end -with a backslash, then N+1 physical lines will be joined to -form one logical line.} -{false} -\lineiii{collapse_join}{ -strip leading whitespace from lines that are joined to their -predecessor; only matters if \samp{(join_lines and not lstrip_ws)}} -{false} -\end{tableiii} - -Note that since \var{rstrip_ws} can strip the trailing newline, the -semantics of \method{readline()} must differ from those of the builtin file -object's \method{readline()} method! In particular, \method{readline()} -returns \code{None} for end-of-file: an empty string might just be a -blank line (or an all-whitespace line), if \var{rstrip_ws} is true -but \var{skip_blanks} is not. - -\begin{methoddesc}{open}{filename} -Open a new file \var{filename}. This overrides any \var{file} or -\var{filename} constructor arguments. -\end{methoddesc} - -\begin{methoddesc}{close}{} -Close the current file and forget everything we know about it (including -the filename and the current line number). -\end{methoddesc} - -\begin{methoddesc}{warn}{msg\optional{,line=\code{None}}} -Print (to stderr) a warning message tied to the current logical -line in the current file. If the current logical line in the -file spans multiple physical lines, the warning refers to the -whole range, such as \samp{"lines 3-5"}. If \var{line} is supplied, -it overrides the current line number; it may be a list or tuple -to indicate a range of physical lines, or an integer for a -single physical line. -\end{methoddesc} - -\begin{methoddesc}{readline}{} -Read and return a single logical line from the current file (or -from an internal buffer if lines have previously been ``unread'' -with \method{unreadline()}). If the \var{join_lines} option -is true, this may involve reading multiple physical lines -concatenated into a single string. Updates the current line number, -so calling \method{warn()} after \method{readline()} emits a warning -about the physical line(s) just read. Returns \code{None} on end-of-file, -since the empty string can occur if \var{rstrip_ws} is true but -\var{strip_blanks} is not. -\end{methoddesc} -\begin{methoddesc}{readlines}{} -Read and return the list of all logical lines remaining in the current file. -This updates the current line number to the last line of the file. -\end{methoddesc} -\begin{methoddesc}{unreadline}{line} -Push \var{line} (a string) onto an internal buffer that will be -checked by future \method{readline()} calls. Handy for implementing -a parser with line-at-a-time lookahead. Note that lines that are ``unread'' -with \method{unreadline} are not subsequently re-cleansed (whitespace -stripped, or whatever) when read with \method{readline}. If multiple -calls are made to \method{unreadline} before a call to \method{readline}, -the lines will be returned most in most recent first order. -\end{methoddesc} - -\end{classdesc} - - -\section{\module{distutils.version} --- Version number classes} -\declaremodule{standard}{distutils.version} -\modulesynopsis{implements classes that represent module version numbers. } - -% todo - -%\section{Distutils Commands} -% -%This part of Distutils implements the various Distutils commands, such -%as \code{build}, \code{install} \&c. Each command is implemented as a -%separate module, with the command name as the name of the module. - -\section{\module{distutils.cmd} --- Abstract base class for Distutils commands} -\declaremodule{standard}{distutils.cmd} -\modulesynopsis{This module provides the abstract base class Command. This -class is subclassed by the modules in the \refmodule{distutils.command} -subpackage. } - -This module supplies the abstract base class \class{Command}. - -\begin{classdesc}{Command}{dist} -Abstract base class for defining command classes, the ``worker bees'' -of the Distutils. A useful analogy for command classes is to think of -them as subroutines with local variables called \var{options}. The -options are declared in \method{initialize_options()} and defined -(given their final values) in \method{finalize_options()}, both of -which must be defined by every command class. The distinction between -the two is necessary because option values might come from the outside -world (command line, config file, ...), and any options dependent on -other options must be computed after these outside influences have -been processed --- hence \method{finalize_options()}. The body of the -subroutine, where it does all its work based on the values of its -options, is the \method{run()} method, which must also be implemented -by every command class. - -The class constructor takes a single argument \var{dist}, a -\class{Distribution} instance. -\end{classdesc} - - -\section{\module{distutils.command} --- Individual Distutils commands} -\declaremodule{standard}{distutils.command} -\modulesynopsis{This subpackage contains one module for each standard Distutils command.} - -%\subsubsection{Individual Distutils commands} - -% todo - -\section{\module{distutils.command.bdist} --- Build a binary installer} -\declaremodule{standard}{distutils.command.bdist} -\modulesynopsis{Build a binary installer for a package} - -% todo - -\section{\module{distutils.command.bdist_packager} --- Abstract base class for packagers} -\declaremodule[distutils.command.bdistpackager]{standard}{distutils.command.bdist_packager} -\modulesynopsis{Abstract base class for packagers} - -% todo - -\section{\module{distutils.command.bdist_dumb} --- Build a ``dumb'' installer} -\declaremodule[distutils.command.bdistdumb]{standard}{distutils.command.bdist_dumb} -\modulesynopsis{Build a ``dumb'' installer - a simple archive of files} - -% todo - -\section{\module{distutils.command.bdist_msi} --- Build a Microsoft Installer binary package} -\declaremodule[distutils.command.bdistmsi]{standard}{distutils.command.bdist_msi} -\modulesynopsis{Build a binary distribution as a Windows MSI file} - -% todo - -\section{\module{distutils.command.bdist_rpm} --- Build a binary distribution as a Redhat RPM and SRPM} -\declaremodule[distutils.command.bdistrpm]{standard}{distutils.command.bdist_rpm} -\modulesynopsis{Build a binary distribution as a Redhat RPM and SRPM} - -% todo - -\section{\module{distutils.command.bdist_wininst} --- Build a Windows installer} -\declaremodule[distutils.command.bdistwininst]{standard}{distutils.command.bdist_wininst} -\modulesynopsis{Build a Windows installer} - -% todo - -\section{\module{distutils.command.sdist} --- Build a source distribution} -\declaremodule{standard}{distutils.command.sdist} -\modulesynopsis{Build a source distribution} - -% todo - -\section{\module{distutils.command.build} --- Build all files of a package} -\declaremodule{standard}{distutils.command.build} -\modulesynopsis{Build all files of a package} - -% todo - -\section{\module{distutils.command.build_clib} --- Build any C libraries in a package} -\declaremodule[distutils.command.buildclib]{standard}{distutils.command.build_clib} -\modulesynopsis{Build any C libraries in a package} - -% todo - -\section{\module{distutils.command.build_ext} --- Build any extensions in a package} -\declaremodule[distutils.command.buildext]{standard}{distutils.command.build_ext} -\modulesynopsis{Build any extensions in a package} - -% todo - -\section{\module{distutils.command.build_py} --- Build the .py/.pyc files of a package} -\declaremodule[distutils.command.buildpy]{standard}{distutils.command.build_py} -\modulesynopsis{Build the .py/.pyc files of a package} - -% todo - -\section{\module{distutils.command.build_scripts} --- Build the scripts of a package} -\declaremodule[distutils.command.buildscripts]{standard}{distutils.command.build_scripts} -\modulesynopsis{Build the scripts of a package} - -% todo - -\section{\module{distutils.command.clean} --- Clean a package build area} -\declaremodule{standard}{distutils.command.clean} -\modulesynopsis{Clean a package build area} - -% todo - -\section{\module{distutils.command.config} --- Perform package configuration} -\declaremodule{standard}{distutils.command.config} -\modulesynopsis{Perform package configuration} - -% todo - -\section{\module{distutils.command.install} --- Install a package} -\declaremodule{standard}{distutils.command.install} -\modulesynopsis{Install a package} - -% todo - -\section{\module{distutils.command.install_data} - --- Install data files from a package} -\declaremodule[distutils.command.installdata]{standard}{distutils.command.install_data} -\modulesynopsis{Install data files from a package} - -% todo - -\section{\module{distutils.command.install_headers} - --- Install C/\Cpp{} header files from a package} -\declaremodule[distutils.command.installheaders]{standard}{distutils.command.install_headers} -\modulesynopsis{Install C/\Cpp{} header files from a package} - -% todo - -\section{\module{distutils.command.install_lib} - --- Install library files from a package} -\declaremodule[distutils.command.installlib]{standard}{distutils.command.install_lib} -\modulesynopsis{Install library files from a package} - -% todo - -\section{\module{distutils.command.install_scripts} - --- Install script files from a package} -\declaremodule[distutils.command.installscripts]{standard}{distutils.command.install_scripts} -\modulesynopsis{Install script files from a package} - -% todo - -\section{\module{distutils.command.register} - --- Register a module with the Python Package Index} -\declaremodule{standard}{distutils.command.register} -\modulesynopsis{Register a module with the Python Package Index} - -The \code{register} command registers the package with the Python Package -Index. This is described in more detail in \pep{301}. -% todo - -\section{Creating a new Distutils command} - -This section outlines the steps to create a new Distutils command. - -A new command lives in a module in the \module{distutils.command} -package. There is a sample template in that directory called -\file{command_template}. Copy this file to a new module with the -same name as the new command you're implementing. This module should -implement a class with the same name as the module (and the command). -So, for instance, to create the command \code{peel_banana} (so that users -can run \samp{setup.py peel_banana}), you'd copy \file{command_template} -to \file{distutils/command/peel_banana.py}, then edit it so that it's -implementing the class \class{peel_banana}, a subclass of -\class{distutils.cmd.Command}. - -Subclasses of \class{Command} must define the following methods. - -\begin{methoddesc}[Command]{initialize_options()} -Set default values for all the options that this command -supports. Note that these defaults may be overridden by other -commands, by the setup script, by config files, or by the -command-line. Thus, this is not the place to code dependencies -between options; generally, \method{initialize_options()} implementations -are just a bunch of \samp{self.foo = None} assignments. -\end{methoddesc} - -\begin{methoddesc}[Command]{finalize_options}{} -Set final values for all the options that this command supports. -This is always called as late as possible, ie. after any option -assignments from the command-line or from other commands have been -done. Thus, this is the place to to code option dependencies: if -\var{foo} depends on \var{bar}, then it is safe to set \var{foo} from -\var{bar} as long as \var{foo} still has the same value it was assigned in -\method{initialize_options()}. -\end{methoddesc} -\begin{methoddesc}[Command]{run}{} -A command's raison d'etre: carry out the action it exists to -perform, controlled by the options initialized in -\method{initialize_options()}, customized by other commands, the setup -script, the command-line, and config files, and finalized in -\method{finalize_options()}. All terminal output and filesystem -interaction should be done by \method{run()}. -\end{methoddesc} - -\var{sub_commands} formalizes the notion of a ``family'' of commands, -eg. \code{install} as the parent with sub-commands \code{install_lib}, -\code{install_headers}, etc. The parent of a family of commands -defines \var{sub_commands} as a class attribute; it's a list of -2-tuples \samp{(command_name, predicate)}, with \var{command_name} a string -and \var{predicate} an unbound method, a string or None. -\var{predicate} is a method of the parent command that -determines whether the corresponding command is applicable in the -current situation. (Eg. we \code{install_headers} is only applicable if -we have any C header files to install.) If \var{predicate} is None, -that command is always applicable. - -\var{sub_commands} is usually defined at the *end* of a class, because -predicates can be unbound methods, so they must already have been -defined. The canonical example is the \command{install} command. - -% -% The ugly "%begin{latexonly}" pseudo-environments are really just to -% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're -% not really valuable. -% - -%begin{latexonly} -\renewcommand{\indexname}{Module Index} -%end{latexonly} -\input{moddist.ind} % Module Index - -%begin{latexonly} -\renewcommand{\indexname}{Index} -%end{latexonly} -\input{dist.ind} % Index - -\end{document} |