Delete the LaTeX doc tree.

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}