\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. If
+Python, there are no arbitrary limits to what you can do with
+it.\footnote{But 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 you need to
+ insert potentially expensive processing steps into the Distutils
+ chain, see section~\ref{extending} on extending the Distutils.} 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 little as
this:
hold true for packages and extensions)
\item it's recommended that you supply a little more meta-data, 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
Wise installed on your system for the \command{bdist\_wise} command to
work; it's available from \url{http://foo/bar/baz}.)
-Currently (Distutils 0.9.1), the are only other useful built
+Currently (Distutils 0.9.2), the are only other useful built
distribution format is RPM, implemented by the \command{bdist\_rpm}
command. For example, the following command will create an RPM file
called \file{Foo-1.0.noarch.rpm}:
\label{setup-config}
Often, it's not possible to write down everything needed to build a
-distribution \emph{a priori}. You need to get some information from the
-user, or from the user's system, in order to proceed. For example, you
-might include an optional extension module that provides an interface to
-a particular C library. If that library is installed on the user's
-system, then you can build your optional extension---but you need to
-know where to find the header and library file. If it's not installed,
-you need to know this so you can omit your optional extension.
-
-The preferred way to do this, of course, would be for you to tell the
-Distutils which optional features (C libraries, system calls, external
-utilities, etc.) you're looking for, and it would inspect the user's
-system and try to find them. This functionality may appear in a future
-version of the Distutils, but it isn't there now. So, for the time
-being, we rely on the user building and installing your software to
-provide the necessary information. The vehicle for doing so is the
-setup configuration file, \file{setup.cfg}.
-
-\XXX{need more here!}
+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.)
+
+\XXX{should reference description of distutils config files in
+ ``Installing'' manual here}
+
+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 (from a \verb+#+
+character to end-of-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
+[...]
+\end{verbatim}
+Or consult section \ref{reference} of this document (the command
+reference).
+
+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 explcitly 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.
\section{Creating a Source Distribution}
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)}
- \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(2)}
- \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{}
+ \lineiii{zip}{zip file (\file{.zip})}{(1),(2)}
+ \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(3),(4)}
+ \lineiii{bztar}{bzip2'ed tar file (\file{.tar.gz})}{(4)}
+ \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)}
\lineiii{tar}{tar file (\file{.tar})}{}
\end{tableiii}
\noindent Notes:
\begin{description}
\item[(1)] default on Windows
-\item[(2)] default on Unix
+\item[(2)] under both Unix and Windows, requires either external
+ Info-ZIP utility \emph{or} the \module{zipfile} module
+\item[(3)] default on Unix
+\item[(4)] requires external utilities: \program{tar} and possibly one
+ of \program{gzip}, \program{bzip2}, or \program{compress}
\end{description}
reference, and then used to build the source distribution archive(s).
Following the Distutils' own manifest template, let's trace how the
-\command{sdist} command will build the list of files to include in 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
\section{Reference}
-\label{ref}
+\label{reference}
\subsection{Building modules: the \protect\command{build} command family}
projects / python / commitdiff