merge Anthony Baxter's distutils API reference into the package

author's documentation

Doc/dist/dist.tex

@@ -12,7 +12,8 @@
 
 \input{boilerplate}
 
-\author{Greg Ward}
+\author{Greg Ward\\
+        Anthony Baxter}
 \authoraddress{
 	\strong{Python Software Foundation}\\
 	Email: \email{distutils-sig@python.org}
@@ -1912,7 +1913,1546 @@ anything except backslash or colon; on Mac OS anything except colon.
 %\subsection{\protect\command{bdist\_wininst}}
 
 
+\chapter{API Reference \label{api-reference}}
+
+\section{\module{distutils.core} --- Core Distutils functionality}
+
+\declaremodule{standard}{distutils.core}
+\modulesynopsis{The core Distutils functionality}
+
+The \module{distutils.core} module is the only module that needs to be
+installed to use the Distutils. It provides the \function{setup()} (which
+is called from the setup script). Indirectly provides the 
+\class{distutils.dist.Distribution} and \class{distutils.cmd.Command} class.
+
+\begin{funcdesc}{setup}{arguments}
+The basic do-everything function that does most everything you could ever
+ask for from a Distutils method. See XXXXX
+
+The setup function takes a large number of arguments. These
+are laid out in the following table.
+
+\begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
+\lineiii{name}{The name of the package}{a string}
+\lineiii{version}{The version number of the package}{See \refmodule{distutils.version}}
+\lineiii{description}{A single line describing the package}{a string}
+\lineiii{long_description}{Longer description of the package}{a string}
+\lineiii{author}{The name of the package author}{a string}
+\lineiii{author_email}{The email address of the package author}{a string}
+\lineiii{maintainer}{The name of the current maintainer, if different from the author}{a string}
+\lineiii{maintainer_email}{The email address of the current maintainer, if different from the author}{}
+\lineiii{url}{A URL for the package (homepage)}{a URL}
+\lineiii{download_url}{A URL to download the package}{a URL}
+\lineiii{packages}{A list of Python packages that distutils will manipulate}{a list of strings}
+\lineiii{py_modules}{A list of Python modules that distutils will manipulate}{a list of strings}
+\lineiii{scripts}{A list of standalone script files to be built and installed}{a list of strings}
+\lineiii{ext_modules}{A list of Python extensions to be built}{A list of 
+instances of \class{distutils.core.Extension}}
+\lineiii{classifiers}{A list of Trove categories for the package}{XXX link to better definition}
+\lineiii{distclass}{the \class{Distribution} class to use}{A subclass of \class{distutils.core.Distribution}}
+% What on earth is the use case for script_name?
+\lineiii{script_name}{The name of the setup.py script - defaults to \code{sys.argv[0]}}{a string}
+\lineiii{script_args}{Arguments to supply to the setup script}{a list of strings}
+\lineiii{options}{default options for the setup script}{a string}
+\lineiii{license}{The license for the package}{}
+\lineiii{keywords}{Descriptive meta-data. See \pep{314}}{}
+\lineiii{platforms}{}{}
+\lineiii{cmdclass}{A mapping of command names to \class{Command} subclasses}{a dictionary}
+\end{tableiii}
+
+\end{funcdesc}
+
+\begin{funcdesc}{run_setup}{script_name\optional{, script_args=\code{None}, stop_after=\code{'run'}}}
+Run a setup script in a somewhat controlled environment, and return 
+the \class{distutils.dist.Distribution} instance that drives things.  
+This is useful if you need to find out the distribution meta-data 
+(passed as keyword args from \var{script} to \function{setup()}), or 
+the contents of the config files or command-line.
+
+\var{script_name} is a file that will be run with \function{execfile()}
+\var{sys.argv[0]} will be replaced with \var{script} for the duration of the
+call.  \var{script_args} is a list of strings; if supplied,
+\var{sys.argv[1:]} will be replaced by \var{script_args} for the duration 
+of the call.
+
+\var{stop_after} tells \function{setup()} when to stop processing; possible 
+values:
+
+\begin{tableii}{c|l}{value}{value}{description}
+\lineii{init}{Stop after the \class{Distribution} instance has been created 
+and populated with the keyword arguments to \function{setup()}}
+\lineii{config}{Stop after config files have been parsed (and their data
+stored in the \class{Distribution} instance)}
+\lineii{commandline}{Stop after the command-line (\code{sys.argv[1:]} or 
+\var{script_args}) have been parsed (and the data stored in the 
+\class{Distribution} instance.)}
+\lineii{run}{Stop after all commands have been run (the same as 
+if \function{setup()} had been called in the usual way). This is the default 
+value.}
+\end{tableii}
+\end{funcdesc}
+
+In addition, the \module{distutils.core} module exposed a number of 
+classes that live elsewhere.
+
+\begin{itemize}
+\item \class{Extension} from \refmodule{distutils.extension}
+\item \class{Command} from \refmodule{distutils.cmd}
+\item \class{Distribution} from \refmodule{distutils.dist}
+\end{itemize}
+
+A short description of each of these follows, but see the relevant
+module for the full reference.
+
+\begin{classdesc*}{Extension}
+
+The Extension class describes a single C or \Cpp extension module in a
+setup script. It accepts the following keyword arguments in it's
+constructor
+
+\begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
+\lineiii{name}{the full name of the extension, including any packages
+--- ie. \emph{not} a filename or pathname, but Python dotted name}{string}
+\lineiii{sources}{list of source filenames, relative to the distribution
+root (where the setup script lives), in Unix form (slash-separated) for
+portability. Source files may be C, \Cpp, SWIG (.i), platform-specific
+resource files, or whatever else is recognized by the \command{build_ext}
+command as source for a Python extension.}{string}
+\lineiii{include_dirs}{list of directories to search for C/\Cpp{} header
+files (in \UNIX{} form for portability)}{string}
+\lineiii{define_macros}{list of macros to define; each macro is defined
+using a 2-tuple, where 'value' is either the string to define it to or
+\code{None} to define it without a particular value (equivalent of
+\code{\#define FOO} in source or \programopt{-DFOO} on \UNIX{} C
+compiler command line) }{ (string,string) 
+tuple or (name,\code{None}) }
+\lineiii{undef_macros}{list of macros to undefine explicitly}{string}
+\lineiii{library_dirs}{list of directories to search for C/\Cpp{} libraries
+at link time }{string}
+\lineiii{libraries}{list of library names (not filenames or paths) to
+link against }{string}
+\lineiii{runtime_library_dirs}{list of directories to search for C/\Cpp{}
+libraries at run time (for shared extensions, this is when the extension
+is loaded)}{string}
+\lineiii{extra_objects}{list of extra files to link with (eg. object
+files not implied by 'sources', static library that must be explicitly
+specified, binary resource files, etc.)}{string}
+\lineiii{extra_compile_args}{any extra platform- and compiler-specific
+information to use when compiling the source files in 'sources'. For
+platforms and compilers where a command line makes sense, this is
+typically a list of command-line arguments, but for other platforms it
+could be anything.}{string}
+\lineiii{extra_link_args}{any extra platform- and compiler-specific
+information to use when linking object files together to create the
+extension (or to create a new static Python interpreter). Similar
+interpretation as for 'extra_compile_args'.}{string}
+\lineiii{export_symbols}{list of symbols to be exported from a shared
+extension. Not used on all platforms, and not generally necessary for
+Python extensions, which typically export exactly one symbol: \code{init} +
+extension_name. }{string}
+\lineiii{depends}{list of files that the extension depends on }{string}
+\lineiii{language}{extension language (i.e. \code{'c'}, \code{'c++'}, 
+\code{'objc'}). Will be detected from the source extensions if not provided.
+}{string}
+\end{tableiii}
+\end{classdesc*}
+
+\begin{classdesc*}{Distribution}
+A \class{Distribution} describes how to build, install and package up a
+Python software package. 
+
+See the \function{setup()} function for a list of keyword arguments accepted 
+by the Distribution constructor. \function{setup()} creates a Distribution
+instance.
+\end{classdesc*}
+
+\begin{classdesc*}{Command}
+A \class{Command} class (or rather, an instance of one of it's subclasses)
+implement a single distutils command.
+\end{classdesc*}
+
+
+\section{\module{distutils.ccompiler} --- CCompiler base class}
+\declaremodule{standard}{distutils.ccompiler}
+\modulesynopsis{Abstract CCompiler class}
+
+This module provides the abstract base class for the \class{CCompiler} 
+classes.  A \class{CCompiler} instance can be used for all the compile 
+and link steps needed to build a single project. Methods are provided to 
+set options for the compiler --- macro definitions, include directories, 
+link path, libraries and the like.
+
+This module provides the following functions.
+
+\begin{funcdesc}{gen_lib_options}{compiler, library_dirs, runtime_library_dirs, libraries}
+Generate linker options for searching library directories and
+linking with specific libraries.  \var{libraries} and \var{library_dirs} are,
+respectively, lists of library names (not filenames!) and search
+directories.  Returns a list of command-line options suitable for use
+with some compiler (depending on the two format strings passed in).
+\end{funcdesc}
+    
+\begin{funcdesc}{gen_preprocess_options}{macros, include_dirs}
+Generate C pre-processor options (-D, -U, -I) as used by at least
+two types of compilers: the typical \UNIX{} compiler and Visual \Cpp.
+\var{macros} is the usual thing, a list of 1- or 2-tuples, where \var{(name,)}
+means undefine (-U) macro \var{name}, and \var{(name,value)} means define (-D)
+macro \var{name} to \var{value}.  \var{include_dirs} is just a list of directory
+names to be added to the header file search path (-I).  Returns a list
+of command-line options suitable for either \UNIX{} compilers or Visual
+\Cpp.
+\end{funcdesc}
+
+\begin{funcdesc}{get_default_compiler}{osname, platform}
+Determine the default compiler to use for the given platform.
+    
+\var{osname} should be one of the standard Python OS names (i.e. the
+ones returned by \var{os.name}) and \var{platform} the common value
+returned by \var{sys.platform} for the platform in question.
+    
+The default values are \code{os.name} and \code{sys.platform} in case the
+parameters are not given.
+\end{funcdesc}
+
+\begin{funcdesc}{new_compiler}{plat=\code{None}, compiler=\code{None}, verbose=\code{0}, dry_run=\code{0}, force=\code{0}}
+Factory function to generate an instance of some CCompiler subclass
+for the supplied platform/compiler combination. \var{plat} defaults
+to \code{os.name} (eg. \code{'posix'}, \code{'nt'}), and \var{compiler} 
+defaults to the default compiler for that platform. Currently only
+\code{'posix'} and \code{'nt'} are supported, and the default
+compilers are ``traditional \UNIX{} interface'' (\class{UnixCCompiler}
+class) and Visual \Cpp (\class{MSVCCompiler} class).  Note that it's
+perfectly possible to ask for a \UNIX{} compiler object under Windows,
+and a Microsoft compiler object under \UNIX---if you supply a value
+for \var{compiler}, \var{plat} is ignored.
+% Is the posix/nt only thing still true? Mac OS X seems to work, and
+% returns a UnixCCompiler instance. How to document this... hmm.
+\end{funcdesc}
+
+\begin{funcdesc}{show_compilers}{}
+Print list of available compilers (used by the
+\longprogramopt{help-compiler} options to \command{build},
+\command{build_ext}, \command{build_clib}).
+\end{funcdesc}
+
+\begin{classdesc}{CCompiler}{\optional{verbose=\code{0}, dry_run=\code{0}, force=\code{0}}}
+
+The abstract base class \class{CCompiler} defines the interface that 
+must be implemented by real compiler classes.  The class also has 
+some utility methods used by several compiler classes.
+
+The basic idea behind a compiler abstraction class is that each
+instance can be used for all the compile/link steps in building a
+single project.  Thus, attributes common to all of those compile and
+link steps --- include directories, macros to define, libraries to link
+against, etc. --- are attributes of the compiler instance.  To allow for
+variability in how individual files are treated, most of those
+attributes may be varied on a per-compilation or per-link basis.
+
+The constructor for each subclass creates an instance of the Compiler
+object. Flags are \var{verbose} (show verbose output), \var{dry_run}
+(don't actually execute the steps) and \var{force} (rebuild
+everything, regardless of dependencies). All of these flags default to
+\code{0} (off). Note that you probably don't want to instantiate
+\class{CCompiler} or one of it's subclasses directly - use the
+\function{distutils.CCompiler.new_compiler()} factory function
+instead.
+
+The following methods allow you to manually alter compiler options for 
+the instance of the Compiler class.
+
+\begin{methoddesc}{add_include_dir}{dir}
+Add \var{dir} to the list of directories that will be searched for
+header files.  The compiler is instructed to search directories in
+the order in which they are supplied by successive calls to
+\method{add_include_dir()}.
+\end{methoddesc}
+
+\begin{methoddesc}{set_include_dirs}{dirs}
+Set the list of directories that will be searched to \var{dirs} (a
+list of strings).  Overrides any preceding calls to
+\method{add_include_dir()}; subsequent calls to
+\method{add_include_dir()} add to the list passed to
+\method{set_include_dirs()}.  This does not affect any list of
+standard include directories that the compiler may search by default.
+\end{methoddesc}
+
+\begin{methoddesc}{add_library}{libname}
+
+Add \var{libname} to the list of libraries that will be included in
+all links driven by this compiler object.  Note that \var{libname}
+should *not* be the name of a file containing a library, but the
+name of the library itself: the actual filename will be inferred by
+the linker, the compiler, or the compiler class (depending on the
+platform).
+    
+The linker will be instructed to link against libraries in the
+order they were supplied to \method{add_library()} and/or
+\method{set_libraries()}.  It is perfectly valid to duplicate library
+names; the linker will be instructed to link against libraries as
+many times as they are mentioned.
+\end{methoddesc}
+
+\begin{methoddesc}{set_libraries}{libnames}
+Set the list of libraries to be included in all links driven by
+this compiler object to \var{libnames} (a list of strings).  This does
+not affect any standard system libraries that the linker may
+include by default.
+\end{methoddesc}
+
+\begin{methoddesc}{add_library_dir}{dir}
+Add \var{dir} to the list of directories that will be searched for
+libraries specified to \method{add_library()} and
+\method{set_libraries()}.  The linker will be instructed to search for
+libraries in the order they are supplied to \method{add_library_dir()}
+and/or \method{set_library_dirs()}.
+\end{methoddesc}
+
+\begin{methoddesc}{set_library_dirs}{dirs}
+Set the list of library search directories to \var{dirs} (a list of
+strings).  This does not affect any standard library search path
+that the linker may search by default.
+\end{methoddesc}
+
+\begin{methoddesc}{add_runtime_library_dir}{dir}
+Add \var{dir} to the list of directories that will be searched for
+shared libraries at runtime.
+\end{methoddesc}
+
+\begin{methoddesc}{set_runtime_library_dirs}{dirs}
+Set the list of directories to search for shared libraries at
+runtime to \var{dirs} (a list of strings).  This does not affect any
+standard search path that the runtime linker may search by
+default.
+\end{methoddesc}
+
+\begin{methoddesc}{define_macro}{name\optional{, value=\code{None}}}
+Define a preprocessor macro for all compilations driven by this
+compiler object.  The optional parameter \var{value} should be a
+string; if it is not supplied, then the macro will be defined
+without an explicit value and the exact outcome depends on the
+compiler used (XXX true? does ANSI say anything about this?)
+\end{methoddesc}
+
+\begin{methoddesc}{undefine_macro}{name}
+Undefine a preprocessor macro for all compilations driven by
+this compiler object.  If the same macro is defined by
+\method{define_macro()} and undefined by \method{undefine_macro()} 
+the last call takes precedence (including multiple redefinitions or
+undefinitions).  If the macro is redefined/undefined on a
+per-compilation basis (ie. in the call to \method{compile()}), then that
+takes precedence.
+\end{methoddesc}
+
+\begin{methoddesc}{add_link_object}{object}
+Add \var{object} to the list of object files (or analogues, such as
+explicitly named library files or the output of ``resource
+compilers'') to be included in every link driven by this compiler
+object.
+\end{methoddesc}
+
+\begin{methoddesc}{set_link_objects}{objects}
+Set the list of object files (or analogues) to be included in
+every link to \var{objects}.  This does not affect any standard object
+files that the linker may include by default (such as system
+libraries).
+\end{methoddesc}
+
+The following methods implement methods for autodetection of compiler 
+options, providing some functionality similar to GNU \program{autoconf}.
+
+\begin{methoddesc}{detect_language}{sources}
+Detect the language of a given file, or list of files. Uses the 
+instance attributes \member{language_map} (a dictionary), and 
+\member{language_order} (a list) to do the job.
+\end{methoddesc}
+
+\begin{methoddesc}{find_library_file}{dirs, lib\optional{, debug=\code{0}}}
+Search the specified list of directories for a static or shared
+library file \var{lib} and return the full path to that file.  If
+\var{debug} is true, look for a debugging version (if that makes sense on
+the current platform).  Return \code{None} if \var{lib} wasn't found in any of
+the specified directories.
+\end{methoddesc}
+
+\begin{methoddesc}{has_function}{funcname \optional{, includes=\code{None}, include_dirs=\code{None}, libraries=\code{None}, library_dirs=\code{None}}}
+Return a boolean indicating whether \var{funcname} is supported on
+the current platform.  The optional arguments can be used to
+augment the compilation environment by providing additional include
+files and paths and libraries and paths.
+\end{methoddesc}
+
+\begin{methoddesc}{library_dir_option}{dir}
+Return the compiler option to add \var{dir} to the list of
+directories searched for libraries.
+\end{methoddesc}
+
+\begin{methoddesc}{library_option}{lib}
+Return the compiler option to add \var{dir} to the list of libraries
+linked into the shared library or executable.
+\end{methoddesc}
+
+\begin{methoddesc}{runtime_library_dir_option}{dir}
+Return the compiler option to add \var{dir} to the list of
+directories searched for runtime libraries.
+\end{methoddesc}
+
+\begin{methoddesc}{set_executables}{**args}
+Define the executables (and options for them) that will be run
+to perform the various stages of compilation.  The exact set of
+executables that may be specified here depends on the compiler
+class (via the 'executables' class attribute), but most will have:
+
+\begin{tableii}{l|l}{attribute}{attribute}{description}
+\lineii{compiler}{the C/\Cpp{} compiler}
+\lineii{linker_so}{linker used to create shared objects and libraries}
+\lineii{linker_exe}{linker used to create binary executables}
+\lineii{archiver}{static library creator}
+\end{tableii}
+
+On platforms with a command-line (\UNIX, DOS/Windows), each of these
+is a string that will be split into executable name and (optional)
+list of arguments.  (Splitting the string is done similarly to how
+\UNIX{} shells operate: words are delimited by spaces, but quotes and
+backslashes can override this.  See
+\function{distutils.util.split_quoted()}.)
+\end{methoddesc}
+
+The following methods invoke stages in the build process.
+
+\begin{methoddesc}{compile}{sources\optional{, output_dir=\code{None}, macros=\code{None}, include_dirs=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, depends=\code{None}}}
+Compile one or more source files. Generates object files (e.g. 
+transforms a \file{.c} file to a \file{.o} file.)
+
+\var{sources} must be a list of filenames, most likely C/\Cpp
+files, but in reality anything that can be handled by a
+particular compiler and compiler class (eg. \class{MSVCCompiler} can
+handle resource files in \var{sources}).  Return a list of object
+filenames, one per source filename in \var{sources}.  Depending on
+the implementation, not all source files will necessarily be
+compiled, but all corresponding object filenames will be
+returned.
+
+If \var{output_dir} is given, object files will be put under it, while
+retaining their original path component.  That is, \file{foo/bar.c}
+normally compiles to \file{foo/bar.o} (for a \UNIX{} implementation); if
+\var{output_dir} is \var{build}, then it would compile to
+\file{build/foo/bar.o}.
+
+\var{macros}, if given, must be a list of macro definitions.  A macro
+definition is either a \var{(name, value)} 2-tuple or a \var{(name,)} 1-tuple.
+The former defines a macro; if the value is \code{None}, the macro is
+defined without an explicit value.  The 1-tuple case undefines a
+macro.  Later definitions/redefinitions/undefinitions take
+precedence.
+
+\var{include_dirs}, if given, must be a list of strings, the
+directories to add to the default include file search path for this
+compilation only.
+
+\var{debug} is a boolean; if true, the compiler will be instructed to
+output debug symbols in (or alongside) the object file(s).
+
+\var{extra_preargs} and \var{extra_postargs} are implementation- dependent.
+On platforms that have the notion of a command-line (e.g. \UNIX,
+DOS/Windows), they are most likely lists of strings: extra
+command-line arguments to prepand/append to the compiler command
+line.  On other platforms, consult the implementation class
+documentation.  In any event, they are intended as an escape hatch
+for those occasions when the abstract compiler framework doesn't
+cut the mustard.
+
+\var{depends}, if given, is a list of filenames that all targets
+depend on.  If a source file is older than any file in
+depends, then the source file will be recompiled.  This
+supports dependency tracking, but only at a coarse
+granularity.
+
+Raises \exception{CompileError} on failure.
+\end{methoddesc}
+
+\begin{methoddesc}{create_static_lib}{objects, output_libname\optional{, output_dir=\code{None}, debug=\code{0}, target_lang=\code{None}}}
+Link a bunch of stuff together to create a static library file.
+The ``bunch of stuff'' consists of the list of object files supplied
+as \var{objects}, the extra object files supplied to
+\method{add_link_object()} and/or \method{set_link_objects()}, the libraries
+supplied to \method{add_library()} and/or \method{set_libraries()}, and the
+libraries supplied as \var{libraries} (if any).
+
+\var{output_libname} should be a library name, not a filename; the
+filename will be inferred from the library name.  \var{output_dir} is
+the directory where the library file will be put. XXX defaults to what?
+
+\var{debug} is a boolean; if true, debugging information will be
+included in the library (note that on most platforms, it is the
+compile step where this matters: the \var{debug} flag is included here
+just for consistency).
+
+\var{target_lang} is the target language for which the given objects
+are being compiled. This allows specific linkage time treatment of
+certain languages.
+
+Raises \exception{LibError} on failure.
+\end{methoddesc}
+
+\begin{methoddesc}{link}{target_desc, objects, output_filename\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}}
+Link a bunch of stuff together to create an executable or
+shared library file.
+
+The ``bunch of stuff'' consists of the list of object files supplied
+as \var{objects}.  \var{output_filename} should be a filename.  If
+\var{output_dir} is supplied, \var{output_filename} is relative to it
+(i.e. \var{output_filename} can provide directory components if
+needed).
+
+\var{libraries} is a list of libraries to link against.  These are
+library names, not filenames, since they're translated into
+filenames in a platform-specific way (eg. \var{foo} becomes \file{libfoo.a}
+on \UNIX{} and \file{foo.lib} on DOS/Windows).  However, they can include a
+directory component, which means the linker will look in that
+specific directory rather than searching all the normal locations.
+
+\var{library_dirs}, if supplied, should be a list of directories to
+search for libraries that were specified as bare library names
+(ie. no directory component).  These are on top of the system
+default and those supplied to \method{add_library_dir()} and/or
+\method{set_library_dirs()}.  \var{runtime_library_dirs} is a list of
+directories that will be embedded into the shared library and used
+to search for other shared libraries that *it* depends on at
+run-time.  (This may only be relevant on \UNIX.)
+
+\var{export_symbols} is a list of symbols that the shared library will
+export.  (This appears to be relevant only on Windows.)
+
+\var{debug} is as for \method{compile()} and \method{create_static_lib()}, 
+with the slight distinction that it actually matters on most platforms (as
+opposed to \method{create_static_lib()}, which includes a \var{debug} flag
+mostly for form's sake).
+
+\var{extra_preargs} and \var{extra_postargs} are as for \method{compile()} 
+(except of course that they supply command-line arguments for the
+particular linker being used).
+
+\var{target_lang} is the target language for which the given objects
+are being compiled. This allows specific linkage time treatment of
+certain languages.
+
+Raises \exception{LinkError} on failure.
+\end{methoddesc}
+
+\begin{methoddesc}{link_executable}{objects, output_progname\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, target_lang=\code{None}}}
+Link an executable. 
+\var{output_progname} is the name of the file executable,
+while \var{objects} are a list of object filenames to link in. Other arguments 
+are as for the \method{link} method. 
+\end{methoddesc}
+
+\begin{methoddesc}{link_shared_lib}{objects, output_libname\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}}
+Link a shared library. \var{output_libname} is the name of the output 
+library, while \var{objects} is a list of object filenames to link in. 
+Other arguments are as for the \method{link} method. 
+\end{methoddesc}
+
+\begin{methoddesc}{link_shared_object}{objects, output_filename\optional{, output_dir=\code{None}, libraries=\code{None}, library_dirs=\code{None}, runtime_library_dirs=\code{None}, export_symbols=\code{None}, debug=\code{0}, extra_preargs=\code{None}, extra_postargs=\code{None}, build_temp=\code{None}, target_lang=\code{None}}}
+Link a shared object. \var{output_filename} is the name of the shared object
+that will be created, while \var{objects} is a list of object filenames 
+to link in. Other arguments are as for the \method{link} method. 
+\end{methoddesc}
+
+\begin{methoddesc}{preprocess}{source\optional{, output_file=\code{None}, macros=\code{None}, include_dirs=\code{None}, extra_preargs=\code{None}, extra_postargs=\code{None}}}
+Preprocess a single C/\Cpp{} source file, named in \var{source}.
+Output will be written to file named \var{output_file}, or \var{stdout} if
+\var{output_file} not supplied.  \var{macros} is a list of macro
+definitions as for \method{compile()}, which will augment the macros set
+with \method{define_macro()} and \method{undefine_macro()}.  
+\var{include_dirs} is a list of directory names that will be added to the 
+default list, in the same way as \method{add_include_dir()}.
+
+Raises \exception{PreprocessError} on failure.
+\end{methoddesc}
+
+The following utility methods are defined by the \class{CCompiler} class,
+for use by the various concrete subclasses.
+
+\begin{methoddesc}{executable_filename}{basename\optional{, strip_dir=\code{0}, output_dir=\code{''}}}
+Returns the filename of the executable for the given \var{basename}. 
+Typically for non-Windows platforms this is the same as the basename, 
+while Windows will get a \file{.exe} added.
+\end{methoddesc}
+
+\begin{methoddesc}{library_filename}{libname\optional{, lib_type=\code{'static'}, strip_dir=\code{0}, output_dir=\code{''}}}
+Returns the filename for the given library name on the current platform.
+On \UNIX{} a library with \var{lib_type} of \code{'static'} will typically 
+be of the form \file{liblibname.a}, while a \var{lib_type} of \code{'dynamic'} 
+will be of the form \file{liblibname.so}.
+\end{methoddesc}
+
+\begin{methoddesc}{object_filenames}{source_filenames\optional{, strip_dir=\code{0}, output_dir=\code{''}}}
+Returns the name of the object files for the given source files. 
+\var{source_filenames} should be a list of filenames. 
+\end{methoddesc}
+
+\begin{methoddesc}{shared_object_filename}{basename\optional{, strip_dir=\code{0}, output_dir=\code{''}}}
+Returns the name of a shared object file for the given file name \var{basename}.
+\end{methoddesc}
+
+\begin{methoddesc}{execute}{func, args\optional{, msg=\code{None}, level=\code{1}}}
+Invokes \function{distutils.util.execute()} This method invokes a 
+Python function \var{func} with the given arguments \var{args}, after 
+logging and taking into account the \var{dry_run} flag. XXX see also.
+\end{methoddesc}
+
+\begin{methoddesc}{spawn}{cmd}
+Invokes \function{distutils.util.spawn()}. This invokes an external 
+process to run the given command. XXX see also.
+\end{methoddesc}
+
+\begin{methoddesc}{mkpath}{name\optional{, mode=\code{511}}}
+
+Invokes \function{distutils.dir_util.mkpath()}. This creates a directory 
+and any missing ancestor directories. XXX see also.
+\end{methoddesc}
+
+\begin{methoddesc}{move_file}{src, dst}
+Invokes \method{distutils.file_util.move_file()}. Renames \var{src} to 
+\var{dst}.  XXX see also.
+\end{methoddesc}
+
+\begin{methoddesc}{announce}{msg\optional{, level=\code{1}}}
+Write a message using \function{distutils.log.debug()}. XXX see also.
+\end{methoddesc}
+
+\begin{methoddesc}{warn}{msg}
+Write a warning message \var{msg} to standard error.
+\end{methoddesc}
+
+\begin{methoddesc}{debug_print}{msg}
+If the \var{debug} flag is set on this \class{CCompiler} instance, print 
+\var{msg} to standard output, otherwise do nothing.
+\end{methoddesc}
+
+\end{classdesc}
+
+%\subsection{Compiler-specific modules}
+%
+%The following modules implement concrete subclasses of the abstract 
+%\class{CCompiler} class. They should not be instantiated directly, but should
+%be created using \function{distutils.ccompiler.new_compiler()} factory 
+%function.
+
+\section{\module{distutils.unixccompiler} --- Unix C Compiler}
+\declaremodule{standard}{distutils.unixccompiler}
+\modulesynopsis{UNIX C Compiler}
+
+This module provides the \class{UnixCCompiler} class, a subclass of 
+\class{CCompiler} that handles the typical \UNIX-style command-line 
+C compiler:
+
+\begin{itemize}
+\item macros defined with \programopt{-D\var{name}\optional{=value}}
+\item macros undefined with \programopt{-U\var{name}}
+\item include search directories specified with
+      \programopt{-I\var{dir}}
+\item libraries specified with \programopt{-l\var{lib}}
+\item library search directories specified with \programopt{-L\var{dir}}
+\item compile handled by \program{cc} (or similar) executable with
+      \programopt{-c} option: compiles \file{.c} to \file{.o}
+\item link static library handled by \program{ar} command (possibly
+      with \program{ranlib})
+\item link shared library handled by \program{cc} \programopt{-shared}
+\end{itemize}
+
+\section{\module{distutils.msvccompiler} --- Microsoft Compiler}
+\declaremodule{standard}{distutils.msvccompiler}
+\modulesynopsis{Microsoft Compiler}
+
+This module provides \class{MSVCCompiler}, an implementation of the abstract 
+\class{CCompiler} class for Microsoft Visual Studio. It should also work using
+the freely available compiler provided as part of the .Net SDK download. XXX
+download link.
+
+\section{\module{distutils.bcppcompiler} --- Borland Compiler}
+\declaremodule{standard}{distutils.bcppcompiler}
+This module provides \class{BorlandCCompiler}, an subclass of the abstract \class{CCompiler} class for the Borland \Cpp{} compiler.
+
+\section{\module{distutils.cygwincompiler} --- Cygwin Compiler}
+\declaremodule{standard}{distutils.cygwinccompiler}
+
+This module provides the \class{CygwinCCompiler} class, a subclass of \class{UnixCCompiler} that
+handles the Cygwin port of the GNU C compiler to Windows.  It also contains
+the Mingw32CCompiler class which handles the mingw32 port of GCC (same as
+cygwin in no-cygwin mode).
+
+\section{\module{distutils.emxccompiler} --- OS/2 EMX Compiler}
+\declaremodule{standard}{distutils.emxccompiler}
+\modulesynopsis{OS/2 EMX Compiler support}
+
+This module provides the EMXCCompiler class, a subclass of \class{UnixCCompiler} that handles the EMX port of the GNU C compiler to OS/2.
+
+\section{\module{distutils.mwerkscompiler} --- Metrowerks CodeWarrior support}
+\declaremodule{standard}{distutils.mwerkscompiler}
+\modulesynopsis{Metrowerks CodeWarrior support}
+
+Contains \class{MWerksCompiler}, an implementation of the abstract 
+\class{CCompiler} class for MetroWerks CodeWarrior on the Macintosh. Needs work to support CW on Windows.
+
+
+%\subsection{Utility modules}
+%
+%The following modules all provide general utility functions. They haven't 
+%all been documented yet.
+
+\section{\module{distutils.archive_util} --- 
+			Archiving utilities}
+\declaremodule[distutils.archiveutil]{standard}{distutils.archive_util}
+\modulesynopsis{Utility functions for creating archive files (tarballs, zip files, ...)}
+
+This module provides a few functions for creating archive files, such as 
+tarballs or zipfiles.
+
+\begin{funcdesc}{make_archive}{base_name, format\optional{, root_dir=\code{None}, base_dir=\code{None}, verbose=\code{0}, dry_run=\code{0}}}
+Create an archive file (eg. \code{zip} or \code{tar}).  \var{base_name} 
+is the name of the file to create, minus any format-specific extension; 
+\var{format} is the archive format: one of \code{zip}, \code{tar}, 
+\code{ztar}, or \code{gztar}.
+\var{root_dir} is a directory that will be the root directory of the
+archive; ie. we typically \code{chdir} into \var{root_dir} before 
+creating the archive.  \var{base_dir} is the directory where we start 
+archiving from; ie. \var{base_dir} will be the common prefix of all files and
+directories in the archive.  \var{root_dir} and \var{base_dir} both default
+to the current directory.  Returns the name of the archive file.
+
+\warning{This should be changed to support bz2 files}
+\end{funcdesc}
+
+\begin{funcdesc}{make_tarball}{base_name, base_dir\optional{, compress=\code{'gzip'}, verbose=\code{0}, dry_run=\code{0}}}'Create an (optional compressed) archive as a tar file from all files in and under \var{base_dir}. \var{compress} must be \code{'gzip'} (the default), 
+\code{'compress'}, \code{'bzip2'}, or \code{None}.  Both \code{'tar'}
+and the compression utility named by \var{'compress'} must be on the 
+default program search path, so this is probably \UNIX-specific.  The 
+output tar file will be named \file{\var{base_dir}.tar}, possibly plus
+the appropriate compression extension (\file{.gz}, \file{.bz2} or
+\file{.Z}).  Return the output filename.
+
+\warning{This should be replaced with calls to the \module{tarfile} module.}
+\end{funcdesc}
+
+\begin{funcdesc}{make_zipfile}{base_name, base_dir\optional{, verbose=\code{0}, dry_run=\code{0}}}
+Create a zip file from all files in and under \var{base_dir}.  The output
+zip file will be named \var{base_dir} + \file{.zip}.  Uses either the 
+\module{zipfile} Python module (if available) or the InfoZIP \file{zip} 
+utility (if installed and found on the default search path).  If neither 
+tool is available, raises \exception{DistutilsExecError}.  
+Returns the name of the output zip file.
+\end{funcdesc}
+
+\section{\module{distutils.dep_util} --- Dependency checking}
+\declaremodule[distutils.deputil]{standard}{distutils.dep_util}
+\modulesynopsis{Utility functions for simple dependency checking}
+
+This module provides functions for performing simple, timestamp-based 
+dependency of files and groups of files; also, functions based entirely 
+on such timestamp dependency analysis.
+
+\begin{funcdesc}{newer}{source, target}
+Return true if \var{source} exists and is more recently modified than
+\var{target}, or if \var{source} exists and \var{target} doesn't.
+Return false if both exist and \var{target} is the same age or newer 
+than \var{source}.
+Raise \exception{DistutilsFileError} if \var{source} does not exist.
+\end{funcdesc}
+
+\begin{funcdesc}{newer_pairwise}{sources, targets}
+Walk two filename lists in parallel, testing if each source is newer
+than its corresponding target.  Return a pair of lists (\var{sources},
+\var{targets}) where source is newer than target, according to the semantics
+of \function{newer()}
+%% equivalent to a listcomp...
+\end{funcdesc}
+
+\begin{funcdesc}{newer_group}{sources, target\optional{, missing=\code{'error'}}}
+Return true if \var{target} is out-of-date with respect to any file
+listed in \var{sources}  In other words, if \var{target} exists and is newer
+than every file in \var{sources}, return false; otherwise return true.
+\var{missing} controls what we do when a source file is missing; the
+default (\code{'error'}) is to blow up with an \exception{OSError} from 
+inside \function{os.stat()};
+if it is \code{'ignore'}, we silently drop any missing source files; if it is
+\code{'newer'}, any missing source files make us assume that \var{target} is
+out-of-date (this is handy in ``dry-run'' mode: it'll make you pretend to
+carry out commands that wouldn't work because inputs are missing, but
+that doesn't matter because you're not actually going to run the
+commands).
+\end{funcdesc}
+
+\section{\module{distutils.dir_util} --- Directory tree operations}
+\declaremodule[distutils.dirutil]{standard}{distutils.dir_util}
+\modulesynopsis{Utility functions for operating on directories and directory trees}
+
+This module provides functions for operating on directories and trees
+of directories.
+
+\begin{funcdesc}{mkpath}{name\optional{, mode=\code{0777}, verbose=\code{0}, dry_run=\code{0}}}
+Create a directory and any missing ancestor directories.  If the
+directory already exists (or if \var{name} is the empty string, which
+means the current directory, which of course exists), then do
+nothing.  Raise \exception{DistutilsFileError} if unable to create some
+directory along the way (eg. some sub-path exists, but is a file
+rather than a directory).  If \var{verbose} is true, print a one-line
+summary of each mkdir to stdout.  Return the list of directories
+actually created.
+\end{funcdesc}
+
+\begin{funcdesc}{create_tree}{base_dir, files\optional{, mode=\code{0777}, verbose=\code{0}, dry_run=\code{0}}}
+Create all the empty directories under \var{base_dir} needed to
+put \var{files} there.  \var{base_dir} is just the a name of a directory
+which doesn't necessarily exist yet; \var{files} is a list of filenames
+to be interpreted relative to \var{base_dir}.  \var{base_dir} + the
+directory portion of every file in \var{files} will be created if it
+doesn't already exist.  \var{mode}, \var{verbose} and \var{dry_run} flags 
+are as for \function{mkpath()}.
+\end{funcdesc}
+
+\begin{funcdesc}{copy_tree}{src, dst\optional{preserve_mode=\code{1}, preserve_times=\code{1}, preserve_symlinks=\code{0}, update=\code{0}, verbose=\code{0}, dry_run=\code{0}}}
+Copy an entire directory tree \var{src} to a new location \var{dst}.  Both
+\var{src} and \var{dst} must be directory names.  If \var{src} is not a
+directory, raise \exception{DistutilsFileError}.  If \var{dst} does 
+not exist, it is created with \var{mkpath()}.  The end result of the 
+copy is that every file in \var{src} is copied to \var{dst}, and 
+directories under \var{src} are recursively copied to \var{dst}.  
+Return the list of files that were copied or might have been copied,
+using their output name. The return value is unaffected by \var{update}
+or \var{dry_run}: it is simply the list of all files under \var{src},
+with the names changed to be under \var{dst}.
+
+\var{preserve_mode} and \var{preserve_times} are the same as for
+\function{copy_file} in \refmodule[distutils.fileutil]{distutils.file_util};
+note that they only apply to regular files, not to directories.  If
+\var{preserve_symlinks} is true, symlinks will be copied as symlinks
+(on platforms that support them!); otherwise (the default), the
+destination of the symlink will be copied.  \var{update} and
+\var{verbose} are the same as for
+\function{copy_file()}.
+\end{funcdesc}
+
+\begin{funcdesc}{remove_tree}{directory\optional{verbose=\code{0}, dry_run=\code{0}}}
+Recursively remove \var{directory} and all files and directories underneath
+it. Any errors are ignored (apart from being reported to \code{stdout} if 
+\var{verbose} is true).
+\end{funcdesc}
+
+\XXX{Some of this could be replaced with the shutil module?}
+
+\section{\module{distutils.file_util} --- Single file operations}
+\declaremodule[distutils.fileutil]{standard}{distutils.file_util}
+\modulesynopsis{Utility functions for operating on single files}
+
+This module contains some utility functions for operating on individual files.
+
+\begin{funcdesc}{copy_file}{src, dst\optional{preserve_mode=\code{1}, preserve_times=\code{1}, update=\code{0}, link=\code{None}, verbose=\code{0}, dry_run=\code{0}}}
+Copy file \var{src} to \var{dst}. If \var{dst} is a directory, then
+\var{src} is copied there with the same name; otherwise, it must be a
+filename. (If the file exists, it will be ruthlessly clobbered.) If
+\var{preserve_mode} is true (the default), the file's mode (type and
+permission bits, or whatever is analogous on the current platform) is
+copied. If \var{preserve_times} is true (the default), the last-modified
+and last-access times are copied as well. If \var{update} is true,
+\var{src} will only be copied if \var{dst} does not exist, or if
+\var{dst} does exist but is older than \var{src}.
+
+\var{link} allows you to make hard links (using \function{os.link}) or
+symbolic links (using \function{os.symlink}) instead of copying: set it
+to \code{'hard'} or \code{'sym'}; if it is \code{None} (the default),
+files are copied. Don't set \var{link} on systems that don't support
+it: \function{copy_file()} doesn't check if hard or symbolic linking is
+available.
+
+Under Mac OS 9, uses the native file copy function in \module{macostools}; 
+on other systems, uses \var{_copy_file_contents()} to copy file contents.
+
+Return a tuple \samp{(dest_name, copied)}: \var{dest_name} is the actual 
+name of the output file, and \var{copied} is true if the file was copied 
+(or would have been copied, if \var{dry_run} true).
+% XXX if the destination file already exists, we clobber it if
+% copying, but blow up if linking.  Hmmm.  And I don't know what
+% macostools.copyfile() does.  Should definitely be consistent, and
+% should probably blow up if destination exists and we would be
+% changing it (ie. it's not already a hard/soft link to src OR
+% (not update) and (src newer than dst)).
+\end{funcdesc}
+
+\begin{funcdesc}{move_file}{src, dst\optional{verbose, dry_run}}
+Move file \var{src} to \var{dst}. If \var{dst} is a directory, the file will
+be moved into it with the same name; otherwise, \var{src} is just renamed
+to \var{dst}.  Returns the new full name of the file.
+\warning{Handles cross-device moves on Unix using \function{copy_file()}.  
+What about other systems???}
+\end{funcdesc}
+
+\begin{funcdesc}{write_file}{filename, contents}
+Create a file called \var{filename} and write \var{contents} (a
+sequence of strings without line terminators) to it.
+\end{funcdesc}
+
+\section{\module{distutils.utils} --- Miscellaneous other utility functions}
+\declaremodule{standard}{distutils.util}
+\modulesynopsis{Miscellaneous other utility functions}
+
+This module contains other assorted bits and pieces that don't fit into 
+any other utility module.
+
+\begin{funcdesc}{get_platform}{}
+Return a string that identifies the current platform.  This is used
+mainly to distinguish platform-specific build directories and
+platform-specific built distributions.  Typically includes the OS name
+and version and the architecture (as supplied by 'os.uname()'),
+although the exact information included depends on the OS; eg. for IRIX
+the architecture isn't particularly important (IRIX only runs on SGI
+hardware), but for Linux the kernel version isn't particularly
+important.
+
+Examples of returned values:
+\begin{itemize}
+\item \code{linux-i586}
+\item \code{linux-alpha}
+\item \code{solaris-2.6-sun4u}
+\item \code{irix-5.3}
+\item \code{irix64-6.2}
+\end{itemize}
+
+For non-\POSIX{} platforms, currently just returns \code{sys.platform}.
+% XXX isn't this also provided by some other non-distutils module?
+\end{funcdesc}
+
+\begin{funcdesc}{convert_path}{pathname}
+Return 'pathname' as a name that will work on the native filesystem,
+i.e. split it on '/' and put it back together again using the current
+directory separator.  Needed because filenames in the setup script are
+always supplied in Unix style, and have to be converted to the local
+convention before we can actually use them in the filesystem.  Raises
+\exception{ValueError} on non-\UNIX-ish systems if \var{pathname} either 
+starts or ends with a slash.
+\end{funcdesc}
+
+\begin{funcdesc}{change_root}{new_root, pathname}
+Return \var{pathname} with \var{new_root} prepended.  If \var{pathname} is
+relative, this is equivalent to \samp{os.path.join(new_root,pathname)}
+Otherwise, it requires making \var{pathname} relative and then joining the
+two, which is tricky on DOS/Windows and Mac OS.
+\end{funcdesc}
+
+\begin{funcdesc}{check_environ}{}
+Ensure that 'os.environ' has all the environment variables we
+guarantee that users can use in config files, command-line options,
+etc.  Currently this includes:
+\begin{itemize}
+\item \envvar{HOME} - user's home directory (\UNIX{} only)
+\item \envvar{PLAT} - description of the current platform, including
+      hardware and OS (see \function{get_platform()})
+\end{itemize}
+\end{funcdesc}
+
+\begin{funcdesc}{subst_vars}{s, local_vars}
+Perform shell/Perl-style variable substitution on \var{s}.  Every
+occurrence of \code{\$} followed by a name is considered a variable, and
+variable is substituted by the value found in the \var{local_vars}
+dictionary, or in \code{os.environ} if it's not in \var{local_vars}.
+\var{os.environ} is first checked/augmented to guarantee that it contains
+certain values: see \function{check_environ()}.  Raise \exception{ValueError} 
+for any variables not found in either \var{local_vars} or \code{os.environ}.
+
+Note that this is not a fully-fledged string interpolation function. A
+valid \code{\$variable} can consist only of upper and lower case letters,
+numbers and an underscore. No \{ \} or \( \) style quoting is available.
+\end{funcdesc}
+
+\begin{funcdesc}{grok_environment_error}{exc\optional{, prefix=\samp{'error: '}}}
+Generate a useful error message from an \exception{EnvironmentError} 
+(\exception{IOError} or \exception{OSError}) exception object.  
+Handles Python 1.5.1 and later styles, and does what it can to deal with 
+exception objects that don't have a filename (which happens when the error 
+is due to a two-file operation, such as \function{rename()} or 
+\function{link()}).  Returns the error message as a string prefixed 
+with \var{prefix}.
+\end{funcdesc}
+
+\begin{funcdesc}{split_quoted}{s}
+Split a string up according to Unix shell-like rules for quotes and
+backslashes.  In short: words are delimited by spaces, as long as those
+spaces are not escaped by a backslash, or inside a quoted string.
+Single and double quotes are equivalent, and the quote characters can
+be backslash-escaped.  The backslash is stripped from any two-character
+escape sequence, leaving only the escaped character.  The quote
+characters are stripped from any quoted string.  Returns a list of
+words.
+% Should probably be moved into the standard library.
+\end{funcdesc}
+
+\begin{funcdesc}{execute}{func, args\optional{, msg=\code{None}, verbose=\code{0}, dry_run=\code{0}}}
+Perform some action that affects the outside world (for instance,
+writing to the filesystem).  Such actions are special because they
+are disabled by the \var{dry_run} flag.  This method takes 
+care of all that bureaucracy for you; all you have to do is supply the
+function to call and an argument tuple for it (to embody the
+``external action'' being performed), and an optional message to
+print.
+\end{funcdesc}
+
+\begin{funcdesc}{strtobool}{val}
+Convert a string representation of truth to true (1) or false (0).
+
+True values are \code{y}, \code{yes}, \code{t}, \code{true}, \code{on} 
+and \code{1}; false values are \code{n}, \code{no}, \code{f}, \code{false}, 
+\code{off} and \code{0}.  Raises \exception{ValueError} if \var{val} 
+is anything else.
+\end{funcdesc}
+
+\begin{funcdesc}{byte_compile}{py_files\optional{,
+              optimize=\code{0}, force=\code{0},
+              prefix=\code{None}, base_dir=\code{None},
+              verbose=\code{1}, dry_run=\code{0},
+              direct=\code{None}}}
+Byte-compile a collection of Python source files to either \file{.pyc}
+or \file{.pyo} files in the same directory.  \var{py_files} is a list of files
+to compile; any files that don't end in \file{.py} are silently skipped.
+\var{optimize} must be one of the following:
+\begin{itemize}
+\item \code{0} - don't optimize (generate \file{.pyc})
+\item \code{1} - normal optimization (like \samp{python -O})
+\item \code{2} - extra optimization (like \samp{python -OO})
+\end{itemize}
+
+If \var{force} is true, all files are recompiled regardless of
+timestamps.
+
+The source filename encoded in each bytecode file defaults to the
+filenames listed in \var{py_files}; you can modify these with \var{prefix} and
+\var{basedir}.  \var{prefix} is a string that will be stripped off of each
+source filename, and \var{base_dir} is a directory name that will be
+prepended (after \var{prefix} is stripped).  You can supply either or both
+(or neither) of \var{prefix} and \var{base_dir}, as you wish.
+
+If \var{dry_run} is true, doesn't actually do anything that would
+affect the filesystem.
+
+Byte-compilation is either done directly in this interpreter process
+with the standard \module{py_compile} module, or indirectly by writing a
+temporary script and executing it.  Normally, you should let
+\function{byte_compile()} figure out to use direct compilation or not (see
+the source for details).  The \var{direct} flag is used by the script
+generated in indirect mode; unless you know what you're doing, leave
+it set to \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{rfc822_escape}{header}
+Return a version of \var{header} escaped for inclusion in an
+\rfc{822} header, by ensuring there are 8 spaces space after each newline.
+Note that it does no other modification of the string.
+% this _can_ be replaced
+\end{funcdesc}
+
+%\subsection{Distutils objects}
+
+\section{\module{distutils.dist} --- The Distribution class}
+\declaremodule{standard}{distutils.dist}
+\modulesynopsis{Provides the Distribution class, which represents the
+                module distribution being built/installed/distributed}
+
+This module provides the \class{Distribution} class, which represents
+the module distribution being built/installed/distributed.
+
+
+\section{\module{distutils.extension} --- The Extension class}
+\declaremodule{standard}{distutils.extension}
+\modulesynopsis{Provides the Extension class, used to describe
+                C/\Cpp{} extension modules in setup scripts}
+
+This module provides the \class{Extension} class, used to describe
+C/\Cpp{} extension modules in setup scripts.
+
+%\subsection{Ungrouped modules}
+%The following haven't been moved into a more appropriate section yet.
+
+\section{\module{distutils.debug} --- Distutils debug mode}
+\declaremodule{standard}{distutils.debug}
+\modulesynopsis{Provides the debug flag for distutils}
+
+This module provides the DEBUG flag.
+
+\section{\module{distutils.errors} --- Distutils exceptions}
+\declaremodule{standard}{distutils.errors}
+\modulesynopsis{Provides standard distutils exceptions}
+
+Provides exceptions used by the Distutils modules.  Note that Distutils
+modules may raise standard exceptions; in particular, SystemExit is
+usually raised for errors that are obviously the end-user's fault
+(eg. bad command-line arguments).
+
+This module is safe to use in \samp{from ... import *} mode; it only exports
+symbols whose names start with \code{Distutils} and end with \code{Error}.
+
+\section{\module{distutils.fancy_getopt}
+         --- Wrapper around the standard getopt module}
+\declaremodule[distutils.fancygetopt]{standard}{distutils.fancy_getopt}
+\modulesynopsis{Additional \module{getopt} functionality}
+
+This module provides a wrapper around the standard \module{getopt} 
+module that provides the following additional features:
+
+\begin{itemize}
+\item short and long options are tied together
+\item options have help strings, so \function{fancy_getopt} could potentially 
+create a complete usage summary
+\item options set attributes of a passed-in object
+\item boolean options can have ``negative aliases'' --- eg. if
+\longprogramopt{quiet} is the ``negative alias'' of
+\longprogramopt{verbose}, then \longprogramopt{quiet} on the command
+line sets \var{verbose} to false.
+
+\end{itemize}
+
+\XXX{Should be replaced with \module{optik} (which is also now
+known as \module{optparse} in Python 2.3 and later).}
+
+\begin{funcdesc}{fancy_getopt}{options, negative_opt, object, args}
+Wrapper function. \var{options} is a list of
+\samp{(long_option, short_option, help_string)} 3-tuples as described in the
+constructor for \class{FancyGetopt}. \var{negative_opt} should be a dictionary
+mapping option names to option names, both the key and value should be in the
+\var{options} list. \var{object} is an object which will be used to store
+values (see the \method{getopt()} method of the \class{FancyGetopt} class).
+\var{args} is the argument list. Will use \code{sys.argv[1:]} if you 
+pass \code{None} as \var{args}.
+\end{funcdesc}
+
+\begin{funcdesc}{wrap_text}{text, width}
+Wraps \var{text} to less than \var{width} wide.
+
+\warning{Should be replaced with \module{textwrap} (which is available 
+in Python 2.3 and later).}
+\end{funcdesc}
+
+\begin{classdesc}{FancyGetopt}{\optional{option_table=\code{None}}}
+The option_table is a list of 3-tuples: \samp{(long_option,
+short_option, help_string)}
+
+If an option takes an argument, it's \var{long_option} should have \code{'='}
+appended; \var{short_option} should just be a single character, no \code{':'}
+in any case. \var{short_option} should be \code{None} if a \var{long_option} 
+doesn't have a corresponding \var{short_option}. All option tuples must have
+long options.
+\end{classdesc}
+
+The \class{FancyGetopt} class provides the following methods:
+
+\begin{methoddesc}{getopt}{\optional{args=\code{None}, object=\code{None}}}
+Parse command-line options in args. Store as attributes on \var{object}.
+
+If \var{args} is \code{None} or not supplied, uses \code{sys.argv[1:]}.  If
+\var{object} is \code{None} or not supplied, creates a new \class{OptionDummy}
+instance, stores option values there, and returns a tuple \samp{(args,
+object)}.  If \var{object} is supplied, it is modified in place and
+\function{getopt()} just returns \var{args}; in both cases, the returned
+\var{args} is a modified copy of the passed-in \var{args} list, which
+is left untouched.
+% and args returned are?
+\end{methoddesc}
+
+\begin{methoddesc}{get_option_order}{}
+Returns the list of \samp{(option, value)} tuples processed by the
+previous run of \method{getopt()}  Raises \exception{RuntimeError} if
+\method{getopt()} hasn't been called yet.
+\end{methoddesc}
+
+\begin{methoddesc}{generate_help}{\optional{header=\code{None}}}
+Generate help text (a list of strings, one per suggested line of
+output) from the option table for this \class{FancyGetopt} object.
+
+If supplied, prints the supplied \var{header} at the top of the help.
+\end{methoddesc}
+
+\section{\module{distutils.filelist} --- The FileList class}
+\declaremodule{standard}{distutils.filelist}
+\modulesynopsis{The \class{FileList} class, used for poking about the
+                file system and building lists of files.}
+
+This module provides the \class{FileList} class, used for poking about
+the filesystem and building lists of files.
+
+
+\section{\module{distutils.log} --- Simple PEP 282-style logging}
+\declaremodule{standard}{distutils.log}
+\modulesynopsis{A simple logging mechanism, \pep{282}-style}
+
+\warning{Should be replaced with standard \module{logging} module.}
+
+%\subsubsection{\module{} --- }
+%\declaremodule{standard}{distutils.magic}
+%\modulesynopsis{ }
+
+
+\section{\module{distutils.spawn} --- Spawn a sub-process}
+\declaremodule{standard}{distutils.spawn}
+\modulesynopsis{Provides the spawn() function}
+
+This module provides the \function{spawn()} function, a front-end to 
+various platform-specific functions for launching another program in a 
+sub-process.
+Also provides \function{find_executable()} to search the path for a given
+executable name.
+
+
 \input{sysconfig}
 
 
+\section{\module{distutils.text_file} --- The TextFile class}
+\declaremodule[distutils.textfile]{standard}{distutils.text_file}
+\modulesynopsis{provides the TextFile class, a simple interface to text files}
+
+This module provides the \class{TextFile} class, which gives an interface 
+to text files that (optionally) takes care of stripping comments, ignoring 
+blank lines, and joining lines with backslashes.
+
+\begin{classdesc}{TextFile}{\optional{filename=\code{None}, file=\code{None}, **options}}
+This class provides a file-like object that takes care of all 
+the things you commonly want to do when processing a text file 
+that has some line-by-line syntax: strip comments (as long as \code{\#} 
+is your comment character), skip blank lines, join adjacent lines by
+escaping the newline (ie. backslash at end of line), strip
+leading and/or trailing whitespace.  All of these are optional
+and independently controllable.
+
+The class provides a \method{warn()} method so you can generate 
+warning messages that report physical line number, even if the 
+logical line in question spans multiple physical lines.  Also 
+provides \method{unreadline()} for implementing line-at-a-time lookahead.
+
+\class{TextFile} instances are create with either \var{filename}, \var{file},
+or both. \exception{RuntimeError} is raised if both are \code{None}.
+\var{filename} should be a string, and \var{file} a file object (or
+something that provides \method{readline()} and \method{close()} 
+methods).  It is recommended that you supply at least \var{filename}, 
+so that \class{TextFile} can include it in warning messages.  If 
+\var{file} is not supplied, TextFile creates its own using the 
+\var{open()} builtin.
+
+The options are all boolean, and affect the values returned by
+\var{readline()}
+
+\begin{tableiii}{c|l|l}{option name}{option name}{description}{default}
+\lineiii{strip_comments}{
+strip from \character{\#} to end-of-line, as well as any whitespace
+leading up to the \character{\#}---unless it is escaped by a backslash}
+{true}
+\lineiii{lstrip_ws}{
+strip leading whitespace from each line before returning it}
+{false}
+\lineiii{rstrip_ws}{
+strip trailing whitespace (including line terminator!) from
+each line before returning it.}
+{true}
+\lineiii{skip_blanks}{
+skip lines that are empty *after* stripping comments and
+whitespace.  (If both lstrip_ws and rstrip_ws are false,
+then some lines may consist of solely whitespace: these will
+*not* be skipped, even if \var{skip_blanks} is true.)}
+{true}
+\lineiii{join_lines}{
+if a backslash is the last non-newline character on a line
+after stripping comments and whitespace, join the following line
+to it to form one logical line; if N consecutive lines end
+with a backslash, then N+1 physical lines will be joined to
+form one logical line.}
+{false}
+\lineiii{collapse_join}{
+strip leading whitespace from lines that are joined to their
+predecessor; only matters if \samp{(join_lines and not lstrip_ws)}}
+{false}
+\end{tableiii}
+
+Note that since \var{rstrip_ws} can strip the trailing newline, the
+semantics of \method{readline()} must differ from those of the builtin file
+object's \method{readline()} method!  In particular, \method{readline()} 
+returns \code{None} for end-of-file: an empty string might just be a 
+blank line (or an all-whitespace line), if \var{rstrip_ws} is true 
+but \var{skip_blanks} is not.
+
+\begin{methoddesc}{open}{filename}
+Open a new file \var{filename}. This overrides any \var{file} or 
+\var{filename} constructor arguments.
+\end{methoddesc}
+
+\begin{methoddesc}{close}{}
+Close the current file and forget everything we know about it (including
+the filename and the current line number).
+\end{methoddesc}
+
+\begin{methoddesc}{warn}{msg\optional{,line=\code{None}}}
+Print (to stderr) a warning message tied to the current logical
+line in the current file.  If the current logical line in the
+file spans multiple physical lines, the warning refers to the
+whole range, such as \samp{"lines 3-5"}.  If \var{line} is supplied, 
+it overrides the current line number; it may be a list or tuple 
+to indicate a range of physical lines, or an integer for a 
+single physical line.
+\end{methoddesc}
+
+\begin{methoddesc}{readline}{}
+Read and return a single logical line from the current file (or
+from an internal buffer if lines have previously been ``unread''
+with \method{unreadline()}).  If the \var{join_lines} option 
+is true, this may involve reading multiple physical lines 
+concatenated into a single string.  Updates the current line number, 
+so calling \method{warn()} after \method{readline()} emits a warning 
+about the physical line(s) just read.  Returns \code{None} on end-of-file, 
+since the empty string can occur if \var{rstrip_ws} is true but 
+\var{strip_blanks} is not.
+\end{methoddesc}
+\begin{methoddesc}{readlines}{}
+Read and return the list of all logical lines remaining in the current file.
+This updates the current line number to the last line of the file.
+\end{methoddesc}
+\begin{methoddesc}{unreadline}{line}
+Push \var{line} (a string) onto an internal buffer that will be
+checked by future \method{readline()} calls.  Handy for implementing
+a parser with line-at-a-time lookahead. Note that lines that are ``unread''
+with \method{unreadline} are not subsequently re-cleansed (whitespace 
+stripped, or whatever) when read with \method{readline}. If multiple
+calls are made to \method{unreadline} before a call to \method{readline},
+the lines will be returned most in most recent first order.
+\end{methoddesc}
+
+\end{classdesc}
+
+
+\section{\module{distutils.version} --- Version number classes}
+\declaremodule{standard}{distutils.version}
+\modulesynopsis{implements classes that represent module version numbers. }
+
+% todo
+
+%\section{Distutils Commands}
+%
+%This part of Distutils implements the various Distutils commands, such
+%as \code{build}, \code{install} \&c. Each command is implemented as a
+%separate module, with the command name as the name of the module.
+
+\section{\module{distutils.cmd} --- Abstract base class for Distutils commands}
+\declaremodule{standard}{distutils.cmd}
+\modulesynopsis{This module provides the abstract base class Command. This
+class is subclassed by the modules in the \refmodule{distutils.command} 
+subpackage. }
+
+This module supplies the abstract base class \class{Command}. 
+
+\begin{classdesc}{Command}{dist}
+Abstract base class for defining command classes, the ``worker bees''
+of the Distutils.  A useful analogy for command classes is to think of
+them as subroutines with local variables called \var{options}.  The
+options are declared in \method{initialize_options()} and defined
+(given their final values) in \method{finalize_options()}, both of
+which must be defined by every command class.  The distinction between
+the two is necessary because option values might come from the outside
+world (command line, config file, ...), and any options dependent on
+other options must be computed after these outside influences have
+been processed --- hence \method{finalize_options()}.  The body of the
+subroutine, where it does all its work based on the values of its
+options, is the \method{run()} method, which must also be implemented
+by every command class.
+
+The class constructor takes a single argument \var{dist}, a 
+\class{Distribution} instance. 
+\end{classdesc}
+
+
+\section{\module{distutils.command} --- Individual Distutils commands}
+\declaremodule{standard}{distutils.command}
+\modulesynopsis{This subpackage contains one module for each standard Distutils command.}
+
+%\subsubsection{Individual Distutils commands}
+
+% todo
+
+\section{\module{distutils.command.bdist} --- Build a binary installer}
+\declaremodule{standard}{distutils.command.bdist}
+\modulesynopsis{Build a binary installer for a package}
+
+% todo
+
+\section{\module{distutils.command.bdist_packager} --- Abstract base class for packagers}
+\declaremodule[distutils.command.bdistpackager]{standard}{distutils.command.bdist_packager}
+\modulesynopsis{Abstract base class for packagers}
+
+% todo
+
+\section{\module{distutils.command.bdist_dumb} --- Build a ``dumb'' installer}
+\declaremodule[distutils.command.bdistdumb]{standard}{distutils.command.bdist_dumb}
+\modulesynopsis{Build a ``dumb'' installer - a simple archive of files}
+
+% todo
+
+
+\section{\module{distutils.command.bdist_rpm} --- Build a binary distribution as a Redhat RPM and SRPM}
+\declaremodule[distutils.command.bdistrpm]{standard}{distutils.command.bdist_rpm}
+\modulesynopsis{Build a binary distribution as a Redhat RPM and SRPM}
+
+% todo
+
+\section{\module{distutils.command.bdist_wininst} --- Build a Windows installer}
+\declaremodule[distutils.command.bdistwininst]{standard}{distutils.command.bdist_wininst}
+\modulesynopsis{Build a Windows installer}
+
+% todo
+
+\section{\module{distutils.command.sdist} --- Build a source distribution}
+\declaremodule{standard}{distutils.command.sdist}
+\modulesynopsis{Build a source distribution}
+
+% todo
+
+\section{\module{distutils.command.build} --- Build all files of a package}
+\declaremodule{standard}{distutils.command.build}
+\modulesynopsis{Build all files of a package}
+
+% todo
+
+\section{\module{distutils.command.build_clib} --- Build any C libraries in a package}
+\declaremodule[distutils.command.buildclib]{standard}{distutils.command.build_clib}
+\modulesynopsis{Build any C libraries in a package}
+
+% todo
+
+\section{\module{distutils.command.build_ext} --- Build any extensions in a package}
+\declaremodule[distutils.command.buildext]{standard}{distutils.command.build_ext}
+\modulesynopsis{Build any extensions in a package}
+
+% todo
+
+\section{\module{distutils.command.build_py} --- Build the .py/.pyc files of a package}
+\declaremodule[distutils.command.buildpy]{standard}{distutils.command.build_py}
+\modulesynopsis{Build the .py/.pyc files of a package}
+
+% todo
+
+\section{\module{distutils.command.build_scripts} --- Build the scripts of a package}
+\declaremodule[distutils.command.buildscripts]{standard}{distutils.command.build_scripts}
+\modulesynopsis{Build the scripts of a package}
+
+% todo
+
+\section{\module{distutils.command.clean} --- Clean a package build area}
+\declaremodule{standard}{distutils.command.clean}
+\modulesynopsis{Clean a package build area}
+
+% todo
+
+\section{\module{distutils.command.config} --- Perform package configuration}
+\declaremodule{standard}{distutils.command.config}
+\modulesynopsis{Perform package configuration}
+
+% todo
+
+\subsubsection{\module{distutils.command.install} --- Install a package}
+\declaremodule{standard}{distutils.command.install}
+\modulesynopsis{Install a package}
+
+% todo
+
+\subsubsection{\module{distutils.command.install_data}
+               --- Install data files from a package}
+\declaremodule[distutils.command.installdata]{standard}{distutils.command.install_data}
+\modulesynopsis{Install data files from a package}
+
+% todo
+
+\subsubsection{\module{distutils.command.install_headers}
+               --- Install C/\Cpp{} header files from a package}
+\declaremodule[distutils.command.installheaders]{standard}{distutils.command.install_headers}
+\modulesynopsis{Install C/\Cpp{} header files from a package}
+
+% todo
+
+\subsubsection{\module{distutils.command.install_lib}
+               --- Install library files from a package}
+\declaremodule[distutils.command.installlib]{standard}{distutils.command.install_lib}
+\modulesynopsis{Install library files from a package}
+
+% todo
+
+\subsubsection{\module{distutils.command.install_scripts}
+               --- Install script files from a package}
+\declaremodule[distutils.command.installscripts]{standard}{distutils.command.install_scripts}
+\modulesynopsis{Install script files from a package}
+
+% todo
+
+\subsubsection{\module{distutils.command.register}
+               --- Register a module with the Python Package Index}
+\declaremodule{standard}{distutils.command.register}
+\modulesynopsis{Register a module with the Python Package Index}
+
+The \code{register} command registers the package with the Python Package 
+Index.  This is described in more detail in \pep{301}.
+% todo
+
+\subsubsection{Creating a new Distutils command}
+
+This section outlines the steps to create a new Distutils command.
+
+A new command lives in a module in the \module{distutils.command}
+package. There is a sample template in that directory called 
+\file{command_template}. Copy this file to a new module with the
+same name as the new command you're implementing. This module should
+implement a class with the same name as the module (and the command).
+So, for instance, to create the command \code{peel_banana} (so that users
+can run \samp{setup.py peel_banana}), you'd copy \file{command_template} 
+to \file{distutils/command/peel_banana.py}, then edit it so that it's
+implementing the class \class{peel_banana}, a subclass of 
+\class{distutils.cmd.Command}.
+
+Subclasses of \class{Command} must define the following methods.
+
+\begin{methoddesc}{initialize_options()}
+Set default values for all the options that this command
+supports.  Note that these defaults may be overridden by other
+commands, by the setup script, by config files, or by the
+command-line.  Thus, this is not the place to code dependencies
+between options; generally, \method{initialize_options()} implementations
+are just a bunch of \samp{self.foo = None} assignments.
+\end{methoddesc}
+
+\begin{methoddesc}{finalize_options}{}
+Set final values for all the options that this command supports.
+This is always called as late as possible, ie.  after any option
+assignments from the command-line or from other commands have been
+done.  Thus, this is the place to to code option dependencies: if
+\var{foo} depends on \var{bar}, then it is safe to set \var{foo} from 
+\var{bar} as long as \var{foo} still has the same value it was assigned in
+\method{initialize_options()}.
+\end{methoddesc}
+\begin{methoddesc}{run}{}
+A command's raison d'etre: carry out the action it exists to
+perform, controlled by the options initialized in
+\method{initialize_options()}, customized by other commands, the setup
+script, the command-line, and config files, and finalized in
+\method{finalize_options()}.  All terminal output and filesystem
+interaction should be done by \method{run()}.
+\end{methoddesc}
+
+\var{sub_commands} formalizes the notion of a ``family'' of commands,
+eg. \code{install} as the parent with sub-commands \code{install_lib},
+\code{install_headers}, etc.  The parent of a family of commands
+defines \var{sub_commands} as a class attribute; it's a list of
+2-tuples \samp{(command_name, predicate)}, with \var{command_name} a string
+and \var{predicate} an unbound method, a string or None.
+\var{predicate} is a method of the parent command that
+determines whether the corresponding command is applicable in the
+current situation.  (Eg. we \code{install_headers} is only applicable if
+we have any C header files to install.)  If \var{predicate} is None,
+that command is always applicable.
+
+\var{sub_commands} is usually defined at the *end* of a class, because
+predicates can be unbound methods, so they must already have been
+defined.  The canonical example is the \command{install} command.
+
+
 \end{document}