[Python-checkins] CVS: distutils/doc/dist dist.tex,1.22,1.23

[Greg Ward]

Update of /cvsroot/python/distutils/doc/dist
In directory slayer.i.sourceforge.net:/tmp/cvs-serv17015/dist

Modified Files:
	dist.tex 
Log Message:
Fleshed out the section on the setup config file, setup.cfg.
Added a few clarifying footnotes and cross-references.
Various minor tweaks.


Index: dist.tex
===================================================================
RCS file: /cvsroot/python/distutils/doc/dist/dist.tex,v
retrieving revision 1.22
retrieving revision 1.23
diff -C2 -r1.22 -r1.23
*** dist.tex	2000/08/31 16:36:30	1.22
--- dist.tex	2000/09/04 20:07:15	1.23
***************
*** 79,83 ****
  
  The setup script is usually quite simple, although since it's written in
! Python, there are no arbitrary limits to what you can do with it.  If
  all you want to do is distribute a module called \module{foo}, contained
  in a file \file{foo.py}, then your setup script can be as little as
--- 79,89 ----
  
  The setup script is usually quite simple, although since it's written in
! 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
  all you want to do is distribute a module called \module{foo}, contained
  in a file \file{foo.py}, then your setup script can be as little as
***************
*** 101,104 ****
--- 107,111 ----
  \item it's recommended that you supply a little more meta-data, in
    particular your name, email address and a URL for the project
+   (see section~\ref{setup-script} for an example)
  \end{itemize}
  
***************
*** 154,158 ****
  work; it's available from \url{http://foo/bar/baz}.)
  
! Currently (Distutils 0.9.1), the are only other useful built
  distribution format is RPM, implemented by the \command{bdist\_rpm}
  command.  For example, the following command will create an RPM file
--- 161,165 ----
  work; it's available from \url{http://foo/bar/baz}.)
  
! Currently (Distutils 0.9.2), the are only other useful built
  distribution format is RPM, implemented by the \command{bdist\_rpm}
  command.  For example, the following command will create an RPM file
***************
*** 553,574 ****
  
  Often, it's not possible to write down everything needed to build a
! distribution \emph{a priori}.  You need to get some information from the
! user, or from the user's system, in order to proceed.  For example, you
! might include an optional extension module that provides an interface to
! a particular C library.  If that library is installed on the user's
! system, then you can build your optional extension---but you need to
! know where to find the header and library file.  If it's not installed,
! you need to know this so you can omit your optional extension.
! 
! The preferred way to do this, of course, would be for you to tell the
! Distutils which optional features (C libraries, system calls, external
! utilities, etc.) you're looking for, and it would inspect the user's
! system and try to find them.  This functionality may appear in a future
! version of the Distutils, but it isn't there now.  So, for the time
! being, we rely on the user building and installing your software to
! provide the necessary information.  The vehicle for doing so is the
! setup configuration file, \file{setup.cfg}.
  
! \XXX{need more here!}
  
  
--- 560,682 ----
  
  Often, it's not possible to write down everything needed to build a
! 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}
! [command]
! option=value
! ...
! \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}
! > python setup.py --help build_ext
! [...]
! Options for 'build_ext' command:
!   --build-lib (-b)     directory for compiled extension modules
!   --build-temp (-t)    directory for temporary files (build by-products)
!   --inplace (-i)       ignore build-lib and put compiled extensions into the
!                        source directory alongside your pure Python modules
!   --include-dirs (-I)  list of directories to search for header files
!   --define (-D)        C preprocessor macros to define
!   --undef (-U)         C preprocessor macros to undefine
! [...]
! \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}
! python setup.py build_ext --inplace
! \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}
! [build_ext]
! inplace=1
! \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}
! [bdist_rpm]
! release = 1
! packager = Greg Ward <gward@python.net>
! doc_files = CHANGES.txt
!             README.txt
!             USAGE.txt
!             doc/
!             examples/
! \end{verbatim}
! Note that the \option{doc\_files} option is simply a
! whitespace-separated string split across multiple lines for readability.
  
  
***************
*** 598,604 ****
  \begin{tableiii}{l|l|c}{code}%
    {Format}{Description}{Notes}
!   \lineiii{zip}{zip file (\file{.zip})}{(1)}
!   \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(2)}
!   \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{}
    \lineiii{tar}{tar file (\file{.tar})}{}
  \end{tableiii}
--- 706,713 ----
  \begin{tableiii}{l|l|c}{code}%
    {Format}{Description}{Notes}
!   \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)}
    \lineiii{tar}{tar file (\file{.tar})}{}
  \end{tableiii}
***************
*** 607,611 ****
  \begin{description}
  \item[(1)] default on Windows
! \item[(2)] default on Unix
  \end{description}
  
--- 716,724 ----
  \begin{description}
  \item[(1)] default on Windows
! \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}
  \end{description}
  
***************
*** 660,664 ****
  
  Following the Distutils' own manifest template, let's trace how the
! \command{sdist} command will build the list of files to include in the
  Distutils source distribution:
  \begin{enumerate}
--- 773,777 ----
  
  Following the Distutils' own manifest template, let's trace how the
! \command{sdist} command builds the list of files to include in the
  Distutils source distribution:
  \begin{enumerate}
***************
*** 870,874 ****
  
  \section{Reference}
! \label{ref}
  
  
--- 983,987 ----
  
  \section{Reference}
! \label{reference}