Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Minor tweaks to catch up with the current code in a few spots. 

Wrote the "Distutils Configuration Files" section.
This commit is contained in:
Greg Ward 2000-10-22 01:40:08 +00:00
parent d097d48200
commit 7ef2ba796b
1 changed files with 147 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
Doc/inst/inst.tex
View File

@ -271,14 +271,14 @@ or
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 @@ If you don't choose an installation directory---i.e., if you just run
\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 @@ being installed is pure Python or contains extensions (``non-pure''):
{\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 @@ Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
'/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~\ref{config-files} for details.
\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}