[Python-checkins] python/nondist/sandbox/distutilsref distref.tex,NONE,1.1

[anthonybaxter@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/sandbox/distutilsref
In directory sc8-pr-cvs1:/tmp/cvs-serv14570

Added Files:
	distref.tex 
Log Message:
distutils reference -- work in progress.


--- NEW FILE: distref.tex ---
\section{\module{distutils} ---
         Building and installing Python modules, reference.}

\sectionauthor {Anthony Baxter}{anthony@interlink.com.au}
\sectionauthor {Greg Ward}{gward@python.net}

The \module{distutils} package provides support for building and
installing additional modules into a Python installation.  The new
modules may be either 100\%{}-pure Python, or may be extension modules
written in C, or may be collections of Python packages which include
modules coded in both Python and C.

\localmoduletable

\section{The simple interface}

\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}{notes}
\lineiii{name}{The name of the package}{a string}
\lineiii{version}{The version number of the package}{See \module{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}{}{}
\lineiii{script_name}{}{}
\lineiii{script_args}{}{}
\lineiii{options}{}{}
\lineiii{license}{The license for the package}{}
\lineiii{keywords}{}{}
\lineiii{platforms}{}{}
\end{tableiii}

In addition, the \module{distutils.core} module exposed a number of 
other classes that live elsewhere.

\begin{itemize}
\item The \class{Distribution} from \module{distutils.dist}
\item The \class{Command} from \module{distutils.cmd}
\item The \class{Extension} from \module{distutils.extension}
\end{itemize}

A short description of each of these follows, but see the relevant
module for the full reference.



\end{funcdesc}


\begin{funcdesc}{run_setup}{script_name, script_args=None, stop_after='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 '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 (\var{sys.argv[1:]} or 
\var{script_args}) have been parsed (and the data stored in the 
\class{Distribution})}
\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}

\section{The more complex interface}

Most people will never need anything other than the \function{setup()} 
function from \module{distutils.core}. For people looking to extend 
Distutils functionality, or do something a little more complex, there's
a whole host of additional modules and functionality provided.

\declaremodule{standard}{distutils.ccompiler}
\modulesynopsis{Abstract CCompiler class}

This module provides the abstract base class for the CCompiler classes.
A 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 C++.
\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
C++.
\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 \var{os.name} and \var{sys.platform} in case the
parameters are not given.
\end{funcdesc}

\begin{funcdesc}{new_compiler}{plat=None, compiler=None, verbose=0, dry_run=0, force=0}
Factory function to generate an instance of some CCompiler subclass
for the supplied platform/compiler combination. \var{plat} defaults
to \var{os.name' (eg. \var{posix}, \var{nt}), and \var{compiler} 
defaults to the default compiler for that platform. Currently only \var{posix} 
and \var{nt} are supported, and the default compilers are "traditional
Unix interface" (\class{UnixCCompiler} class) and Visual C++ 
(\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.
\end{funcdesc}

\begin{funcdesc}{show_compilers}{}
Print list of available compilers (used by the "--help-compiler" options 
to "build", "build_ext", "build_clib").
\end{funcdesc}

\begin{classdesc}{CCompiler}{verbose=0, dry_run=0, force=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 0 (off). Note that you 
probably don't want to instantiate 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 \var{add_include_dir()} 
add to the list passed to \var{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\option{, value=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 autoconf.

\begin{methoddesc}{detect_language}{sources}
Detect the language of a given file, or list of files. Uses the 
instance attributes \var{language_map} (a dictionary), and \var{language_order}
(a list) to do the job.
\end{methoddesc}

\begin{methoddesc}{find_library_file}{dirs, lib\optional{, debug=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 None if \var{lib} wasn't found in any of
the specified directories.
\end{methoddesc}

\begin{methoddesc}{has_function}{funcname \optional{, includes=None, include_dirs=None, libraries=None, library_dirs=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/C++ 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=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None}}
Compile one or more source files. Generates object files (e.g. 
transforms a .c file to a .o file.

\var{sources} must be a list of filenames, most likely C/C++
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, \var{foo/bar.c}
normally compiles to \var{foo/bar.o} (for a Unix implementation); if
\var{output_dir} is \var{build}, then it would compile to
\var{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 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=None, debug=0, target_lang=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=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=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. "foo" becomes "libfoo.a"
on Unix and "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=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=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=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=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=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=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=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None}}
Preprocess a single C/C++ 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=0, output_dir=''}}
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 '.exe' added.
\end{methoddesc}

\begin{methoddesc}{library_filename}{libname\optional{, lib_type='static', strip_dir=0, output_dir=''}}
Returns the filename for the given library name on the current platform.
On unix a library with \var{lib_type} of 'static' will typically be of the 
form "liblibname.a", while a \var{lib_type} of 'dynamic' will be of 
the form "liblibname.so".
\end{methoddesc}

\begin{methoddesc}{object_filenames}{source_filenames\optional{, strip_dir=0, output_dir=''}}
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=0, output_dir=''}}
Returns the name of a shared object file for the given file name \var{basename}.
\end{methoddesc}

\begin{methoddesc}{execute}{func, args\optional{, msg=None, level=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=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=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 
CCompiler class. They should not be instantiated directly, but should
be created using \function{distutils.ccompiler.new_compiler()} factory 
function.

\declaremodule{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 -Dname[=value]
\item macros undefined with -Uname
\item include search directories specified with -Idir
\item libraries specified with -lllib
\item library search directories specified with -Ldir
\item compile handled by 'cc' (or similar) executable with -c option: 
compiles .c to .o
\item link static library handled by 'ar' command (possibly with 'ranlib')
\item link shared library handled by 'cc -shared'
\end{itemize}

\declaremodule{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.

\declaremodule{distutils.bcppcompiler}

This module provides \class{BorlandCCompiler}, an subclass of the abstract \class{CCompiler} class for the Borland C++ compiler.

\declaremodule{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).

\declaremodule{distutils.emxccompiler}
This module provides the EMXCCompiler class, a subclass of \class{UnixCCompiler} that handles the EMX port of the GNU C compiler to OS/2.

\declaremodule{distutils.mwerkscompiler}
Contains \class{MWerksCompiler}, an implementation of the abstract 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. Haven't 
been documented yet.

\declaremodule{standard}{distutils.util}
\modulesynopsis{ }

\declaremodule{standard}{distutils.archive_util}
\modulesynopsis{ }

\declaremodule{standard}{distutils.dep_util}
\modulesynopsis{ }

\declaremodule{standard}{distutils.dir_util}
\modulesynopsis{ }

\declaremodule{standard}{distutils.file_util}
\modulesynopsis{ }

\subsection{Ungrouped modules}

The following haven't been moved into a more appropriate section yet.

\declaremodule{standard}{distutils.debug}
\modulesynopsis{ }

\declaremodule{standard}{distutils.dist}
\modulesynopsis{ }

\declaremodule{standard}{distutils.errors}
\modulesynopsis{ }

\declaremodule{standard}{distutils.extension}
\modulesynopsis{ }

\declaremodule{standard}{distutils.fancy_getopt}
\modulesynopsis{ }

\declaremodule{standard}{distutils.filelist}
\modulesynopsis{ }

\declaremodule{standard}{distutils.log}
\modulesynopsis{ }

\declaremodule{standard}{distutils.magic}
\modulesynopsis{ }

\declaremodule{standard}{distutils.spawn}
\modulesynopsis{ }

\declaremodule{standard}{distutils.sysconfig}
\modulesynopsis{ }

\declaremodule{standard}{distutils.text_file}
\modulesynopsis{ }

\declaremodule{standard}{distutils.version}
\modulesynopsis{implements classes that represent module version numbers. }

\subsection{Distutils Commands}

This part of Distutils implements the various Distutils commands, such
as 'build', 'install' &c. 

\declaremodule{standard}{distutils.cmd}
\modulesynopsis{This module provides the abstract base class Command. This
class is subclassed by the modules in the distutils.command subpackage. }

\declaremodule{standard}{distutils.command}
\modulesynopsis{This subpackage contains one module for each standard Distutils command.}

\subsubsection{Individual Distutils commands}

\declaremodule{standard}{distutils.command.bdist}
\modulesynopsis{Build a binary installer for a package}

\declaremodule{standard}{distutils.command.bdist_packager}
\modulesynopsis{Abstract base class for packagers}

\declaremodule{standard}{distutils.command.bdist_dumb}
\modulesynopsis{Build a "dumb" installer - a simple archive of files}

%\declaremodule{standard}{distutils.command.bdist_pkgtool}
%\modulesynopsis{ }

%\declaremodule{standard}{distutils.command.bdist_sdux}
%\modulesynopsis{ }

\declaremodule{standard}{distutils.command.bdist_rpm}
\modulesynopsis{Build a binary distribution as a Redhat RPM and SRPM}

\declaremodule{standard}{distutils.command.bdist_wininst}
\modulesynopsis{Build a Windows installer}

\declaremodule{standard}{distutils.command.sdist}
\modulesynopsis{Build a source distribution}

\declaremodule{standard}{distutils.command.build}
\modulesynopsis{Build all files of a package}

\declaremodule{standard}{distutils.command.build_clib}
\modulesynopsis{Build any C libraries in a package}

\declaremodule{standard}{distutils.command.build_ext}
\modulesynopsis{Build any extensions in a package}

\declaremodule{standard}{distutils.command.build_py}
\modulesynopsis{Build the .py/.pyc files of a package}

\declaremodule{standard}{distutils.command.build_scripts}
\modulesynopsis{Build the scripts of a package}

\declaremodule{standard}{distutils.command.clean}
\modulesynopsis{Clean a package build area}

\declaremodule{standard}{distutils.command.config}
\modulesynopsis{Perform package configuration}

\declaremodule{standard}{distutils.command.install}
\modulesynopsis{Install a package}

\declaremodule{standard}{distutils.command.install_data}
\modulesynopsis{Install data files from a package}

\declaremodule{standard}{distutils.command.install_headers}
\modulesynopsis{Install C/C++ header files from a package}

\declaremodule{standard}{distutils.command.install_lib}
\modulesynopsis{Install library files from a package}

\declaremodule{standard}{distutils.command.install_scripts}
\modulesynopsis{Install script files from a package}

\declaremodule{standard}{distutils.command.register}
\modulesynopsis{Register a module with the Python Package Index}

\subsubsection{Creating a new Distutils command}

This section will go through the steps to create a new Distutils command.