OS/hardware platform and Python version. The first form, with just a

\file{lib} directory, is used for ``pure module distributions''---that

is, module distributions that include only pure Python modules. If a

module distribution contains any extensions (modules written in C/C++),

then the second form, with two \code{<plat>} directories, is used. In

that case, the \file{temp.\filevar{plat}} directory holds temporary

files generated by the compile/link process that don't actually get

installed. In either case, the \file{lib} (or

Unix and Mac~OS, it also depends on whether the module distribution

{\filenq{\filevar{prefix}:Lib:site-packages}}

{\filenq{Python:Lib:site-packages}}

{\filenq{\filevar{prefix}:Lib:site-packages}}

{\filenq{Python:Lib:site-packages}}

If you don't want to install modules to the standard location, or if you

don't have permission to write there, then you need to read about

alternate installations in section~\ref{alt-install}. If you want to

customize your installation directories more heavily, see

section~\ref{custom-install} on custom installations.

As mentioned above, you can use Distutils configuration files to record

personal or site preferences for any Distutils options. That is, any

option to any command can be stored in one of two or three (depending on

your platform) configuration files, which will be consulted before the

command-line is parsed. This means that configuration files will

override default values, and the command-line will in turn override

configuration files. Furthermore, if multiple configuration files

apply, values from ``earlier'' files are overridden by ``later'' files.

\subsection{Location and names of config files}

\label{sec:config-filenames}

The names and locations of the configuration files vary slightly across

platforms. On Unix, the three configuration files (in the order they

are processed) are:

\begin{tableiii}{l|l|c}{textrm}

{Type of file}{Location and filename}{Notes}

\lineiii{system}{\filenq{\filevar{prefix}/lib/python\filevar{ver}/distutils/pydistutils.cfg}}{(1)}

\lineiii{personal}{\filenq{\$HOME/.pydistutils.cfg}}{(2)}

\lineiii{local}{\filenq{setup.cfg}}{(3)}

\end{tableiii}

On Windows, the configuration files are:

\begin{tableiii}{l|l|c}{textrm}

{Type of file}{Location and filename}{Notes}

\lineiii{system}{\filenq{\filevar{prefix}\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}pydistutils.cfg}}{(4)}

\lineiii{personal}{\filenq{\%HOME\textbackslash{}pydistutils.cfg}}{(5)}

\lineiii{local}{\filenq{setup.cfg}}{(3)}

\end{tableiii}

And on Mac~OS, they are:

\begin{tableiii}{l|l|c}{textrm}

{Type of file}{Location and filename}{Notes}

\lineiii{system}{\filenq{\filevar{prefix}:Lib:distutils:pydistutils.cfg}}{(6)}

\lineiii{personal}{N/A}{}

\lineiii{local}{\filenq{setup.cfg}}{(3)}

\end{tableiii}

\noindent Notes:

\begin{description}

\item[(1)] Strictly speaking, the system-wide configuration file lives

in the directory where the Distutils are installed; under Python 1.6

and later on Unix, this is as shown. For Python 1.5.2, the Distutils

will normally be installed to

\file{\filevar{prefix}/lib/site-packages/python1.5/distutils},

so the system configuration file should be put there under Python

1.5.2.

\item[(2)] On Unix, if the \envvar{HOME} environment variable is not

defined, the user's home directory will be determined with the

\function{getpwuid()} function from the standard \module{pwd} module.

\item[(3)] I.e., in the current directory (usually the location of the

setup script).

\item[(4)] (See also note (1).) Under Python 1.6 and later, Python's

default ``installation prefix'' is \file{C:\textbackslash{}Python}, so

the system configuration file is normally

\file{C:\textbackslash{}Python\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}pydistutils.cfg}.

Under Python 1.5.2, the default prefix was

\file{C:\textbackslash{}Program~Files\textbackslash{}Python}, and the

Distutils were not part of the standard library---so the system

configuration file would be

\file{C:\textbackslash{}Program~Files\textbackslash{}Python\textbackslash{}distutils\textbackslash{}pydistutils.cfg}

in a standard Python 1.5.2 installation under Windows.

\item[(5)] On Windows, if the \envvar{HOME} environment variable is not

defined, no personal configuration file will be found or used. (In

other words, the Distutils make no attempt to guess your home

directory on Windows.)

\item[(6)] (See also notes (1) and (4).) The default installation

prefix is just \file{Python:}, so under Python 1.6 and later this is

normally\file{Python:Lib:distutils:pydistutils.cfg}. (The Distutils

don't work very well with Python 1.5.2 under Mac~OS. \XXX{true?})

\end{description}

\subsection{Syntax of config files}

\label{sec:config-syntax}

The Distutils configuration files all have the same syntax. The config

files are grouped into sections; there is one section for each Distutils

command, plus a \code{global} section for global options that affect

every command. Each section consists of one option per line, specified

like \code{option=value}.

For example, the following is a complete config file that just forces

all commands to run quietly by default:

\begin{verbatim}

\end{verbatim}

If this is installed as the system config file, it will affect all

processing of any Python module distribution by any user on the current

system. If it is installed as your personal config file (on systems

that support them), it will affect only module distributions processed

by you. And if it is used as the \file{setup.cfg} for a particular

module distribution, it affects only that distribution.

You could override the default ``build base'' directory and make the

\command{build*} commands always forcibly rebuild all files with the

following:

\begin{verbatim}

\end{verbatim}

which corresponds to the command-line arguments

\begin{verbatim}

\end{verbatim}

except that including the \command{build} command on the command-line

means that command will be run. Including a particular command in

config files has no such implication; it only means that if the command

is run, the options in the config file will apply. (Or if other

commands that derive values from it are run, they will use the values in

the config file.)

You can find out the complete list of options for any command using the

\longprogramopt{help} option, e.g.:

\begin{verbatim}

\end{verbatim}

and you can find out the complete list of global options by using

\longprogramopt{help} without a command:

\begin{verbatim}

\end{verbatim}

See also the ``Reference'' section of the ``Distributing Python

Modules'' manual.