Minor tweaks to catch up with the current code in a few spots.
Wrote the "Distutils Configuration Files" section.
diff --git a/Doc/inst/inst.tex b/Doc/inst/inst.tex
index 6578496..fab4d2a 100644
--- a/Doc/inst/inst.tex
+++ b/Doc/inst/inst.tex
@@ -271,14 +271,14 @@
temp.<plat>/
\end{verbatim}
where \code{<plat>} expands to a brief description of the current
-OS/hardware platform. 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++, or Java
-for JPython), 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
+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
\file{lib.\filevar{plat}}) directory contains all Python modules (pure
Python and extensions) that will be installed.
@@ -300,7 +300,7 @@
\code{setup.py install}---then the \command{install} command installs to
the standard location for third-party Python modules. This location
varies by platform and by how you built/installed Python itself. On
-Unix and Mac OS, it also depends on whether the module distribution
+Unix and Mac~OS, it also depends on whether the module distribution
being installed is pure Python or contains extensions (``non-pure''):
\begin{tableiv}{l|l|l|c}{textrm}%
{Platform}{Standard installation location}{Default value}{Notes}
@@ -317,12 +317,12 @@
{\filenq{C:\textbackslash{}Python}}
{(2)}
\lineiv{Mac~OS (pure)}
- {\filenq{\filevar{prefix}:Lib}}
- {\filenq{Python:Lib} \XXX{???}}
+ {\filenq{\filevar{prefix}:Lib:site-packages}}
+ {\filenq{Python:Lib:site-packages}}
{}
\lineiv{Mac~OS (non-pure)}
- {\filevar{prefix}:Mac:PlugIns}
- {\filenq{Python:Mac:PlugIns}\XXX{???}}
+ {\filenq{\filevar{prefix}:Lib:site-packages}}
+ {\filenq{Python:Lib:site-packages}}
{}
\end{tableiv}
@@ -361,9 +361,11 @@
'/usr'
\end{verbatim}
-If you don't want to install to the standard location, or if you don't
-have permission to write there, then you need to read about alternate
-installations in the next section.
+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.
% This rather nasty macro is used to generate the tables that describe
@@ -711,6 +713,135 @@
\section{Distutils Configuration Files}
\label{config-files}
+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}
+[global]
+verbose=0
+\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}
+[build]
+build-base=blib
+force=1
+\end{verbatim}
+which corresponds to the command-line arguments
+\begin{verbatim}
+python setup.py build --build-base=blib --force
+\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}
+python setup.py build --help
+\end{verbatim}
+and you can find out the complete list of global options by using
+\longprogramopt{help} without a command:
+\begin{verbatim}
+python setup.py --help
+\end{verbatim}
+See also the ``Reference'' section of the ``Distributing Python
+Modules'' manual.
+
\section{Pre-Distutils Conventions}
\label{pre-distutils}