[Python-checkins] python/nondist/sandbox/distutilsref distref.tex,1.6,1.7
anthonybaxter@users.sourceforge.net
anthonybaxter@users.sourceforge.net
Tue, 20 May 2003 01:42:06 -0700
Update of /cvsroot/python/python/nondist/sandbox/distutilsref
In directory sc8-pr-cvs1:/tmp/cvs-serv1702
Modified Files:
distref.tex
Log Message:
big slab of markup.
Index: distref.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/distutilsref/distref.tex,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** distref.tex 20 May 2003 02:54:20 -0000 1.6
--- distref.tex 20 May 2003 08:42:03 -0000 1.7
***************
*** 107,111 ****
\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.
--- 107,111 ----
\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.
***************
*** 120,133 ****
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
--- 120,134 ----
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
***************
*** 262,266 ****
\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
--- 263,267 ----
\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
***************
*** 281,285 ****
\end{funcdesc}
! \begin{classdesc}{CCompiler}{verbose=0, dry_run=0, force=0}
The abstract base class \class{CCompiler} defines the interface that
--- 282,286 ----
\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
***************
*** 298,303 ****
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.
--- 299,304 ----
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.
***************
*** 370,374 ****
\end{methoddesc}
! \begin{methoddesc}{define_macro}{name\optional{, value=None}}
Define a preprocessor macro for all compilations driven by this
compiler object. The optional parameter \var{value} should be a
--- 371,375 ----
\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
***************
*** 411,415 ****
\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
--- 412,416 ----
\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
***************
*** 419,423 ****
\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
--- 420,424 ----
\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
***************
*** 464,468 ****
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.)
--- 465,469 ----
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 .c file to a .o file.)
***************
*** 515,519 ****
\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
--- 516,520 ----
\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
***************
*** 539,543 ****
\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.
--- 540,544 ----
\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.
***************
*** 584,588 ****
\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,
--- 585,589 ----
\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,
***************
*** 591,595 ****
\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.
--- 592,596 ----
\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.
***************
*** 597,601 ****
\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
--- 598,602 ----
\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
***************
*** 603,607 ****
\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
--- 604,608 ----
\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/C++ source file, named in \var{source}.
Output will be written to file named \var{output_file}, or \var{stdout} if
***************
*** 618,622 ****
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,
--- 619,623 ----
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,
***************
*** 624,644 ****
\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 \file{liblibname.a}, while a \var{lib_type} of 'dynamic' will be of
! the form \file{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
--- 625,645 ----
\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
***************
*** 651,655 ****
\end{methoddesc}
! \begin{methoddesc}{mkpath}{name\optional{, mode=511}}
Invokes \function{distutils.dir_util.mkpath()}. This creates a directory
--- 652,656 ----
\end{methoddesc}
! \begin{methoddesc}{mkpath}{name\optional{, mode=\code{511}}}
Invokes \function{distutils.dir_util.mkpath()}. This creates a directory
***************
*** 662,666 ****
\end{methoddesc}
! \begin{methoddesc}{announce}{msg\optional{, level=1}}
Write a message using \function{distutils.log.debug()}. XXX see also.
\end{methoddesc}
--- 663,667 ----
\end{methoddesc}
! \begin{methoddesc}{announce}{msg\optional{, level=\code{1}}}
Write a message using \function{distutils.log.debug()}. XXX see also.
\end{methoddesc}
***************
*** 755,759 ****
tarballs or zipfiles.
! \begin{funcdesc}{make_archive}{base_name, format\optional{, root_dir=None, base_dir=None, verbose=0, dry_run=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;
--- 756,760 ----
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;
***************
*** 770,774 ****
\end{funcdesc}
! \begin{funcdesc}{make_tarball}{base_name, base_dir\optional{, compress="gzip", verbose=0, dry_run=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"}
--- 771,775 ----
\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"}
***************
*** 782,786 ****
\end{funcdesc}
! \begin{funcdesc}{make_zipfile}{base_name, base_dir\optional{, verbose=0, dry_run=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
--- 783,787 ----
\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
***************
*** 837,841 ****
of directories.
! \begin{funcdesc}{mkpath}{name\optional{, mode=0777, verbose=0, dry_run=0}}
Create a directory and any missing ancestor directories. If the
directory already exists (or if \var{name} is the empty string, which
--- 838,842 ----
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
***************
*** 848,852 ****
\end{funcdesc}
! \begin{funcdesc}{create_tree}{base_dir, files\optional{, mode=0777, verbose=0, dry_run=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
--- 849,853 ----
\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
***************
*** 858,862 ****
\end{funcdesc}
! \begin{funcdesc}{copy_tree}{src, dst\optional{preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=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
--- 859,863 ----
\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
***************
*** 879,885 ****
\end{funcdesc}
! \begin{funcdesc}{remove_tree}{directory\optional{verbose, dry_run}}
Recursively remove \var{directory} and all files and directories underneath
! it. Any errors are ignored (apart from being reported to stdout if
\var{verbose} is true).
\end{funcdesc}
--- 880,886 ----
\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}