From 7ef2ba796b614ac4b63b8e264d5c787b1cebd3aa Mon Sep 17 00:00:00 2001 From: Greg Ward Date: Sun, 22 Oct 2000 01:40:08 +0000 Subject: Minor tweaks to catch up with the current code in a few spots. Wrote the "Distutils Configuration Files" section. --- Doc/inst/inst.tex | 163 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 147 insertions(+), 16 deletions(-) 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 @@ or temp./ \end{verbatim} where \code{} 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{} 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{} 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} -- cgit v0.12