diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index 91c92914d98..b5f973302aa 100644 --- a/Doc/dist/dist.tex +++ b/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}