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

(see section~\ref{setup-script} for an example)

Currently (Distutils 0.9.2), the are only other useful built

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}

\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}

\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}

\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}

\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}

\end{verbatim}

Note that the \option{doc\_files} option is simply a

whitespace-separated string split across multiple lines for readability.

\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)}

\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}

\command{sdist} command builds the list of files to include in the

\label{reference}