PageRenderTime 99ms CodeModel.GetById 13ms app.highlight 70ms RepoModel.GetById 1ms app.codeStats 0ms

/Doc/distutils/apiref.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 2004 lines | 1352 code | 652 blank | 0 comment | 0 complexity | a6bfe97b71144243c2f2905f8d1f6e0d MD5 | raw file
   1.. _api-reference:
   2
   3*************
   4API Reference
   5*************
   6
   7
   8:mod:`distutils.core` --- Core Distutils functionality
   9======================================================
  10
  11.. module:: distutils.core
  12   :synopsis: The core Distutils functionality
  13
  14
  15The :mod:`distutils.core` module is the only module that needs to be installed
  16to use the Distutils. It provides the :func:`setup` (which is called from the
  17setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
  18:class:`distutils.cmd.Command` class.
  19
  20
  21.. function:: setup(arguments)
  22
  23   The basic do-everything function that does most everything you could ever ask
  24   for from a Distutils method. See XXXXX
  25
  26   The setup function takes a large number of arguments. These are laid out in the
  27   following table.
  28
  29   +--------------------+--------------------------------+-------------------------------------------------------------+
  30   | argument name      | value                          | type                                                        |
  31   +====================+================================+=============================================================+
  32   | *name*             | The name of the package        | a string                                                    |
  33   +--------------------+--------------------------------+-------------------------------------------------------------+
  34   | *version*          | The version number of the      | See :mod:`distutils.version`                                |
  35   |                    | package                        |                                                             |
  36   +--------------------+--------------------------------+-------------------------------------------------------------+
  37   | *description*      | A single line describing the   | a string                                                    |
  38   |                    | package                        |                                                             |
  39   +--------------------+--------------------------------+-------------------------------------------------------------+
  40   | *long_description* | Longer description of the      | a string                                                    |
  41   |                    | package                        |                                                             |
  42   +--------------------+--------------------------------+-------------------------------------------------------------+
  43   | *author*           | The name of the package author | a string                                                    |
  44   +--------------------+--------------------------------+-------------------------------------------------------------+
  45   | *author_email*     | The email address of the       | a string                                                    |
  46   |                    | package author                 |                                                             |
  47   +--------------------+--------------------------------+-------------------------------------------------------------+
  48   | *maintainer*       | The name of the current        | a string                                                    |
  49   |                    | maintainer, if different from  |                                                             |
  50   |                    | the author                     |                                                             |
  51   +--------------------+--------------------------------+-------------------------------------------------------------+
  52   | *maintainer_email* | The email address of the       |                                                             |
  53   |                    | current maintainer, if         |                                                             |
  54   |                    | different from the author      |                                                             |
  55   +--------------------+--------------------------------+-------------------------------------------------------------+
  56   | *url*              | A URL for the package          | a URL                                                       |
  57   |                    | (homepage)                     |                                                             |
  58   +--------------------+--------------------------------+-------------------------------------------------------------+
  59   | *download_url*     | A URL to download the package  | a URL                                                       |
  60   +--------------------+--------------------------------+-------------------------------------------------------------+
  61   | *packages*         | A list of Python packages that | a list of strings                                           |
  62   |                    | distutils will manipulate      |                                                             |
  63   +--------------------+--------------------------------+-------------------------------------------------------------+
  64   | *py_modules*       | A list of Python modules that  | a list of strings                                           |
  65   |                    | distutils will manipulate      |                                                             |
  66   +--------------------+--------------------------------+-------------------------------------------------------------+
  67   | *scripts*          | A list of standalone script    | a list of strings                                           |
  68   |                    | files to be built and          |                                                             |
  69   |                    | installed                      |                                                             |
  70   +--------------------+--------------------------------+-------------------------------------------------------------+
  71   | *ext_modules*      | A list of Python extensions to | A list of  instances of                                     |
  72   |                    | be built                       | :class:`distutils.core.Extension`                           |
  73   +--------------------+--------------------------------+-------------------------------------------------------------+
  74   | *classifiers*      | A list of categories for the   | The list of available                                       |
  75   |                    | package                        | categorizations is at                                       |
  76   |                    |                                | http://pypi.python.org/pypi?:action=list_classifiers.       |
  77   +--------------------+--------------------------------+-------------------------------------------------------------+
  78   | *distclass*        | the :class:`Distribution`      | A subclass of                                               |
  79   |                    | class to use                   | :class:`distutils.core.Distribution`                        |
  80   +--------------------+--------------------------------+-------------------------------------------------------------+
  81   | *script_name*      | The name of the setup.py       | a string                                                    |
  82   |                    | script - defaults to           |                                                             |
  83   |                    | ``sys.argv[0]``                |                                                             |
  84   +--------------------+--------------------------------+-------------------------------------------------------------+
  85   | *script_args*      | Arguments to supply to the     | a list of strings                                           |
  86   |                    | setup script                   |                                                             |
  87   +--------------------+--------------------------------+-------------------------------------------------------------+
  88   | *options*          | default options for the setup  | a string                                                    |
  89   |                    | script                         |                                                             |
  90   +--------------------+--------------------------------+-------------------------------------------------------------+
  91   | *license*          | The license for the package    | a string                                                    |
  92   +--------------------+--------------------------------+-------------------------------------------------------------+
  93   | *keywords*         | Descriptive meta-data, see     |                                                             |
  94   |                    | :pep:`314`                     |                                                             |
  95   +--------------------+--------------------------------+-------------------------------------------------------------+
  96   | *platforms*        |                                |                                                             |
  97   +--------------------+--------------------------------+-------------------------------------------------------------+
  98   | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
  99   |                    | :class:`Command` subclasses    |                                                             |
 100   +--------------------+--------------------------------+-------------------------------------------------------------+
 101   | *data_files*       | A list of data files to        | a list                                                      |
 102   |                    | install                        |                                                             |
 103   +--------------------+--------------------------------+-------------------------------------------------------------+
 104   | *package_dir*      | A mapping of package to        | a dictionary                                                |
 105   |                    | directory names                |                                                             |
 106   +--------------------+--------------------------------+-------------------------------------------------------------+
 107
 108
 109
 110.. function:: run_setup(script_name[, script_args=None, stop_after='run'])
 111
 112   Run a setup script in a somewhat controlled environment, and return  the
 113   :class:`distutils.dist.Distribution` instance that drives things.   This is
 114   useful if you need to find out the distribution meta-data  (passed as keyword
 115   args from *script* to :func:`setup`), or  the contents of the config files or
 116   command-line.
 117
 118   *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``
 119   will be replaced with *script* for the duration of the call.  *script_args* is a
 120   list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
 121   for the duration  of the call.
 122
 123   *stop_after* tells :func:`setup` when to stop processing; possible  values:
 124
 125   +---------------+---------------------------------------------+
 126   | value         | description                                 |
 127   +===============+=============================================+
 128   | *init*        | Stop after the :class:`Distribution`        |
 129   |               | instance has been created  and populated    |
 130   |               | with the keyword arguments to :func:`setup` |
 131   +---------------+---------------------------------------------+
 132   | *config*      | Stop after config files have been parsed    |
 133   |               | (and their data stored in the               |
 134   |               | :class:`Distribution` instance)             |
 135   +---------------+---------------------------------------------+
 136   | *commandline* | Stop after the command-line                 |
 137   |               | (``sys.argv[1:]`` or  *script_args*) have   |
 138   |               | been parsed (and the data stored in the     |
 139   |               | :class:`Distribution` instance.)            |
 140   +---------------+---------------------------------------------+
 141   | *run*         | Stop after all commands have been run (the  |
 142   |               | same as  if :func:`setup` had been called   |
 143   |               | in the usual way). This is the default      |
 144   |               | value.                                      |
 145   +---------------+---------------------------------------------+
 146
 147In addition, the :mod:`distutils.core` module exposed a number of  classes that
 148live elsewhere.
 149
 150* :class:`Extension` from :mod:`distutils.extension`
 151
 152* :class:`Command` from :mod:`distutils.cmd`
 153
 154* :class:`Distribution` from :mod:`distutils.dist`
 155
 156A short description of each of these follows, but see the relevant module for
 157the full reference.
 158
 159
 160.. class:: Extension
 161
 162   The Extension class describes a single C or C++extension module in a setup
 163   script. It accepts the following keyword arguments in its constructor
 164
 165   +------------------------+--------------------------------+---------------------------+
 166   | argument name          | value                          | type                      |
 167   +========================+================================+===========================+
 168   | *name*                 | the full name of the           | string                    |
 169   |                        | extension, including any       |                           |
 170   |                        | packages --- ie. *not* a       |                           |
 171   |                        | filename or pathname, but      |                           |
 172   |                        | Python dotted name             |                           |
 173   +------------------------+--------------------------------+---------------------------+
 174   | *sources*              | list of source filenames,      | string                    |
 175   |                        | relative to the distribution   |                           |
 176   |                        | root (where the setup script   |                           |
 177   |                        | lives), in Unix form (slash-   |                           |
 178   |                        | separated) for portability.    |                           |
 179   |                        | Source files may be C, C++,    |                           |
 180   |                        | SWIG (.i), platform-specific   |                           |
 181   |                        | resource files, or whatever    |                           |
 182   |                        | else is recognized by the      |                           |
 183   |                        | :command:`build_ext` command   |                           |
 184   |                        | as source for a Python         |                           |
 185   |                        | extension.                     |                           |
 186   +------------------------+--------------------------------+---------------------------+
 187   | *include_dirs*         | list of directories to search  | string                    |
 188   |                        | for C/C++ header files (in     |                           |
 189   |                        | Unix form for portability)     |                           |
 190   +------------------------+--------------------------------+---------------------------+
 191   | *define_macros*        | list of macros to define; each | (string, string) tuple or |
 192   |                        | macro is defined using a       | (name, ``None``)          |
 193   |                        | 2-tuple ``(name, value)``,     |                           |
 194   |                        | where *value* is               |                           |
 195   |                        | either the string to define it |                           |
 196   |                        | to or ``None`` to define it    |                           |
 197   |                        | without a particular value     |                           |
 198   |                        | (equivalent of ``#define FOO`` |                           |
 199   |                        | in source or :option:`-DFOO`   |                           |
 200   |                        | on Unix C compiler command     |                           |
 201   |                        | line)                          |                           |
 202   +------------------------+--------------------------------+---------------------------+
 203   | *undef_macros*         | list of macros to undefine     | string                    |
 204   |                        | explicitly                     |                           |
 205   +------------------------+--------------------------------+---------------------------+
 206   | *library_dirs*         | list of directories to search  | string                    |
 207   |                        | for C/C++ libraries at link    |                           |
 208   |                        | time                           |                           |
 209   +------------------------+--------------------------------+---------------------------+
 210   | *libraries*            | list of library names (not     | string                    |
 211   |                        | filenames or paths) to link    |                           |
 212   |                        | against                        |                           |
 213   +------------------------+--------------------------------+---------------------------+
 214   | *runtime_library_dirs* | list of directories to search  | string                    |
 215   |                        | for C/C++ libraries at run     |                           |
 216   |                        | time (for shared extensions,   |                           |
 217   |                        | this is when the extension is  |                           |
 218   |                        | loaded)                        |                           |
 219   +------------------------+--------------------------------+---------------------------+
 220   | *extra_objects*        | list of extra files to link    | string                    |
 221   |                        | with (eg. object files not     |                           |
 222   |                        | implied by 'sources', static   |                           |
 223   |                        | library that must be           |                           |
 224   |                        | explicitly specified, binary   |                           |
 225   |                        | resource files, etc.)          |                           |
 226   +------------------------+--------------------------------+---------------------------+
 227   | *extra_compile_args*   | any extra platform- and        | string                    |
 228   |                        | compiler-specific information  |                           |
 229   |                        | to use when compiling the      |                           |
 230   |                        | source files in 'sources'. For |                           |
 231   |                        | platforms and compilers where  |                           |
 232   |                        | a command line makes sense,    |                           |
 233   |                        | this is typically a list of    |                           |
 234   |                        | command-line arguments, but    |                           |
 235   |                        | for other platforms it could   |                           |
 236   |                        | be anything.                   |                           |
 237   +------------------------+--------------------------------+---------------------------+
 238   | *extra_link_args*      | any extra platform- and        | string                    |
 239   |                        | compiler-specific information  |                           |
 240   |                        | to use when linking object     |                           |
 241   |                        | files together to create the   |                           |
 242   |                        | extension (or to create a new  |                           |
 243   |                        | static Python interpreter).    |                           |
 244   |                        | Similar interpretation as for  |                           |
 245   |                        | 'extra_compile_args'.          |                           |
 246   +------------------------+--------------------------------+---------------------------+
 247   | *export_symbols*       | list of symbols to be exported | string                    |
 248   |                        | from a shared extension. Not   |                           |
 249   |                        | used on all platforms, and not |                           |
 250   |                        | generally necessary for Python |                           |
 251   |                        | extensions, which typically    |                           |
 252   |                        | export exactly one symbol:     |                           |
 253   |                        | ``init`` + extension_name.     |                           |
 254   +------------------------+--------------------------------+---------------------------+
 255   | *depends*              | list of files that the         | string                    |
 256   |                        | extension depends on           |                           |
 257   +------------------------+--------------------------------+---------------------------+
 258   | *language*             | extension language (i.e.       | string                    |
 259   |                        | ``'c'``, ``'c++'``,            |                           |
 260   |                        | ``'objc'``). Will be detected  |                           |
 261   |                        | from the source extensions if  |                           |
 262   |                        | not provided.                  |                           |
 263   +------------------------+--------------------------------+---------------------------+
 264
 265
 266.. class:: Distribution
 267
 268   A :class:`Distribution` describes how to build, install and package up a Python
 269   software package.
 270
 271   See the :func:`setup` function for a list of keyword arguments accepted  by the
 272   Distribution constructor. :func:`setup` creates a Distribution instance.
 273
 274
 275.. class:: Command
 276
 277   A :class:`Command` class (or rather, an instance of one of its subclasses)
 278   implement a single distutils command.
 279
 280
 281:mod:`distutils.ccompiler` --- CCompiler base class
 282===================================================
 283
 284.. module:: distutils.ccompiler
 285   :synopsis: Abstract CCompiler class
 286
 287
 288This module provides the abstract base class for the :class:`CCompiler`
 289classes.  A :class:`CCompiler` instance can be used for all the compile  and
 290link steps needed to build a single project. Methods are provided to  set
 291options for the compiler --- macro definitions, include directories,  link path,
 292libraries and the like.
 293
 294This module provides the following functions.
 295
 296
 297.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
 298
 299   Generate linker options for searching library directories and linking with
 300   specific libraries.  *libraries* and *library_dirs* are, respectively, lists of
 301   library names (not filenames!) and search directories.  Returns a list of
 302   command-line options suitable for use with some compiler (depending on the two
 303   format strings passed in).
 304
 305
 306.. function:: gen_preprocess_options(macros, include_dirs)
 307
 308   Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as
 309   used by at least two types of compilers: the typical Unix compiler and Visual
 310   C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
 311   means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define
 312   (:option:`-D`) macro *name* to *value*.  *include_dirs* is just a list of
 313   directory names to be added to the header file search path (:option:`-I`).
 314   Returns a list of command-line options suitable for either Unix compilers or
 315   Visual C++.
 316
 317
 318.. function:: get_default_compiler(osname, platform)
 319
 320   Determine the default compiler to use for the given platform.
 321
 322   *osname* should be one of the standard Python OS names (i.e. the ones returned
 323   by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
 324   the platform in question.
 325
 326   The default values are ``os.name`` and ``sys.platform`` in case the parameters
 327   are not given.
 328
 329
 330.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
 331
 332   Factory function to generate an instance of some CCompiler subclass for the
 333   supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
 334   ``'posix'``, ``'nt'``), and *compiler*  defaults to the default compiler for
 335   that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
 336   default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
 337   class) and Visual C++ (:class:`MSVCCompiler` class).  Note that it's perfectly
 338   possible to ask for a Unix compiler object under Windows, and a Microsoft
 339   compiler object under Unix---if you supply a value for *compiler*, *plat* is
 340   ignored.
 341
 342   .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
 343   .. % returns a UnixCCompiler instance. How to document this... hmm.
 344
 345
 346.. function:: show_compilers()
 347
 348   Print list of available compilers (used by the :option:`--help-compiler` options
 349   to :command:`build`, :command:`build_ext`, :command:`build_clib`).
 350
 351
 352.. class:: CCompiler([verbose=0, dry_run=0, force=0])
 353
 354   The abstract base class :class:`CCompiler` defines the interface that  must be
 355   implemented by real compiler classes.  The class also has  some utility methods
 356   used by several compiler classes.
 357
 358   The basic idea behind a compiler abstraction class is that each instance can be
 359   used for all the compile/link steps in building a single project.  Thus,
 360   attributes common to all of those compile and link steps --- include
 361   directories, macros to define, libraries to link against, etc. --- are
 362   attributes of the compiler instance.  To allow for variability in how individual
 363   files are treated, most of those attributes may be varied on a per-compilation
 364   or per-link basis.
 365
 366   The constructor for each subclass creates an instance of the Compiler object.
 367   Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
 368   steps) and *force* (rebuild everything, regardless of dependencies). All of
 369   these flags default to ``0`` (off). Note that you probably don't want to
 370   instantiate :class:`CCompiler` or one of its subclasses directly - use the
 371   :func:`distutils.CCompiler.new_compiler` factory function instead.
 372
 373   The following methods allow you to manually alter compiler options for  the
 374   instance of the Compiler class.
 375
 376
 377   .. method:: CCompiler.add_include_dir(dir)
 378
 379      Add *dir* to the list of directories that will be searched for header files.
 380      The compiler is instructed to search directories in the order in which they are
 381      supplied by successive calls to :meth:`add_include_dir`.
 382
 383
 384   .. method:: CCompiler.set_include_dirs(dirs)
 385
 386      Set the list of directories that will be searched to *dirs* (a list of strings).
 387      Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
 388      :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
 389      This does not affect any list of standard include directories that the compiler
 390      may search by default.
 391
 392
 393   .. method:: CCompiler.add_library(libname)
 394
 395      Add *libname* to the list of libraries that will be included in all links driven
 396      by this compiler object.  Note that *libname* should \*not\* be the name of a
 397      file containing a library, but the name of the library itself: the actual
 398      filename will be inferred by the linker, the compiler, or the compiler class
 399      (depending on the platform).
 400
 401      The linker will be instructed to link against libraries in the order they were
 402      supplied to :meth:`add_library` and/or :meth:`set_libraries`.  It is perfectly
 403      valid to duplicate library names; the linker will be instructed to link against
 404      libraries as many times as they are mentioned.
 405
 406
 407   .. method:: CCompiler.set_libraries(libnames)
 408
 409      Set the list of libraries to be included in all links driven by this compiler
 410      object to *libnames* (a list of strings).  This does not affect any standard
 411      system libraries that the linker may include by default.
 412
 413
 414   .. method:: CCompiler.add_library_dir(dir)
 415
 416      Add *dir* to the list of directories that will be searched for libraries
 417      specified to :meth:`add_library` and :meth:`set_libraries`.  The linker will be
 418      instructed to search for libraries in the order they are supplied to
 419      :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
 420
 421
 422   .. method:: CCompiler.set_library_dirs(dirs)
 423
 424      Set the list of library search directories to *dirs* (a list of strings).  This
 425      does not affect any standard library search path that the linker may search by
 426      default.
 427
 428
 429   .. method:: CCompiler.add_runtime_library_dir(dir)
 430
 431      Add *dir* to the list of directories that will be searched for shared libraries
 432      at runtime.
 433
 434
 435   .. method:: CCompiler.set_runtime_library_dirs(dirs)
 436
 437      Set the list of directories to search for shared libraries at runtime to *dirs*
 438      (a list of strings).  This does not affect any standard search path that the
 439      runtime linker may search by default.
 440
 441
 442   .. method:: CCompiler.define_macro(name[, value=None])
 443
 444      Define a preprocessor macro for all compilations driven by this compiler object.
 445      The optional parameter *value* should be a string; if it is not supplied, then
 446      the macro will be defined without an explicit value and the exact outcome
 447      depends on the compiler used (XXX true? does ANSI say anything about this?)
 448
 449
 450   .. method:: CCompiler.undefine_macro(name)
 451
 452      Undefine a preprocessor macro for all compilations driven by this compiler
 453      object.  If the same macro is defined by :meth:`define_macro` and
 454      undefined by :meth:`undefine_macro` the last call takes precedence
 455      (including multiple redefinitions or undefinitions).  If the macro is
 456      redefined/undefined on a per-compilation basis (ie. in the call to
 457      :meth:`compile`), then that takes precedence.
 458
 459
 460   .. method:: CCompiler.add_link_object(object)
 461
 462      Add *object* to the list of object files (or analogues, such as explicitly named
 463      library files or the output of "resource compilers") to be included in every
 464      link driven by this compiler object.
 465
 466
 467   .. method:: CCompiler.set_link_objects(objects)
 468
 469      Set the list of object files (or analogues) to be included in every link to
 470      *objects*.  This does not affect any standard object files that the linker may
 471      include by default (such as system libraries).
 472
 473   The following methods implement methods for autodetection of compiler  options,
 474   providing some functionality similar to GNU :program:`autoconf`.
 475
 476
 477   .. method:: CCompiler.detect_language(sources)
 478
 479      Detect the language of a given file, or list of files. Uses the  instance
 480      attributes :attr:`language_map` (a dictionary), and  :attr:`language_order` (a
 481      list) to do the job.
 482
 483
 484   .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
 485
 486      Search the specified list of directories for a static or shared library file
 487      *lib* and return the full path to that file.  If *debug* is true, look for a
 488      debugging version (if that makes sense on the current platform).  Return
 489      ``None`` if *lib* wasn't found in any of the specified directories.
 490
 491
 492   .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
 493
 494      Return a boolean indicating whether *funcname* is supported on the current
 495      platform.  The optional arguments can be used to augment the compilation
 496      environment by providing additional include files and paths and libraries and
 497      paths.
 498
 499
 500   .. method:: CCompiler.library_dir_option(dir)
 501
 502      Return the compiler option to add *dir* to the list of directories searched for
 503      libraries.
 504
 505
 506   .. method:: CCompiler.library_option(lib)
 507
 508      Return the compiler option to add *dir* to the list of libraries linked into the
 509      shared library or executable.
 510
 511
 512   .. method:: CCompiler.runtime_library_dir_option(dir)
 513
 514      Return the compiler option to add *dir* to the list of directories searched for
 515      runtime libraries.
 516
 517
 518   .. method:: CCompiler.set_executables(**args)
 519
 520      Define the executables (and options for them) that will be run to perform the
 521      various stages of compilation.  The exact set of executables that may be
 522      specified here depends on the compiler class (via the 'executables' class
 523      attribute), but most will have:
 524
 525      +--------------+------------------------------------------+
 526      | attribute    | description                              |
 527      +==============+==========================================+
 528      | *compiler*   | the C/C++ compiler                       |
 529      +--------------+------------------------------------------+
 530      | *linker_so*  | linker used to create shared objects and |
 531      |              | libraries                                |
 532      +--------------+------------------------------------------+
 533      | *linker_exe* | linker used to create binary executables |
 534      +--------------+------------------------------------------+
 535      | *archiver*   | static library creator                   |
 536      +--------------+------------------------------------------+
 537
 538      On platforms with a command-line (Unix, DOS/Windows), each of these is a string
 539      that will be split into executable name and (optional) list of arguments.
 540      (Splitting the string is done similarly to how Unix shells operate: words are
 541      delimited by spaces, but quotes and backslashes can override this.  See
 542      :func:`distutils.util.split_quoted`.)
 543
 544   The following methods invoke stages in the build process.
 545
 546
 547   .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
 548
 549      Compile one or more source files. Generates object files (e.g.  transforms a
 550      :file:`.c` file to a :file:`.o` file.)
 551
 552      *sources* must be a list of filenames, most likely C/C++ files, but in reality
 553      anything that can be handled by a particular compiler and compiler class (eg.
 554      :class:`MSVCCompiler` can handle resource files in *sources*).  Return a list of
 555      object filenames, one per source filename in *sources*.  Depending on the
 556      implementation, not all source files will necessarily be compiled, but all
 557      corresponding object filenames will be returned.
 558
 559      If *output_dir* is given, object files will be put under it, while retaining
 560      their original path component.  That is, :file:`foo/bar.c` normally compiles to
 561      :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
 562      it would compile to :file:`build/foo/bar.o`.
 563
 564      *macros*, if given, must be a list of macro definitions.  A macro definition is
 565      either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
 566      a macro; if the value is ``None``, the macro is defined without an explicit
 567      value.  The 1-tuple case undefines a macro.  Later
 568      definitions/redefinitions/undefinitions take precedence.
 569
 570      *include_dirs*, if given, must be a list of strings, the directories to add to
 571      the default include file search path for this compilation only.
 572
 573      *debug* is a boolean; if true, the compiler will be instructed to output debug
 574      symbols in (or alongside) the object file(s).
 575
 576      *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
 577      that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
 578      likely lists of strings: extra command-line arguments to prepend/append to the
 579      compiler command line.  On other platforms, consult the implementation class
 580      documentation.  In any event, they are intended as an escape hatch for those
 581      occasions when the abstract compiler framework doesn't cut the mustard.
 582
 583      *depends*, if given, is a list of filenames that all targets depend on.  If a
 584      source file is older than any file in depends, then the source file will be
 585      recompiled.  This supports dependency tracking, but only at a coarse
 586      granularity.
 587
 588      Raises :exc:`CompileError` on failure.
 589
 590
 591   .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
 592
 593      Link a bunch of stuff together to create a static library file. The "bunch of
 594      stuff" consists of the list of object files supplied as *objects*, the extra
 595      object files supplied to :meth:`add_link_object` and/or
 596      :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
 597      :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
 598
 599      *output_libname* should be a library name, not a filename; the filename will be
 600      inferred from the library name.  *output_dir* is the directory where the library
 601      file will be put. XXX defaults to what?
 602
 603      *debug* is a boolean; if true, debugging information will be included in the
 604      library (note that on most platforms, it is the compile step where this matters:
 605      the *debug* flag is included here just for consistency).
 606
 607      *target_lang* is the target language for which the given objects are being
 608      compiled. This allows specific linkage time treatment of certain languages.
 609
 610      Raises :exc:`LibError` on failure.
 611
 612
 613   .. method:: CCompiler.link(target_desc, objects, output_filename[, 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])
 614
 615      Link a bunch of stuff together to create an executable or shared library file.
 616
 617      The "bunch of stuff" consists of the list of object files supplied as *objects*.
 618      *output_filename* should be a filename.  If *output_dir* is supplied,
 619      *output_filename* is relative to it (i.e. *output_filename* can provide
 620      directory components if needed).
 621
 622      *libraries* is a list of libraries to link against.  These are library names,
 623      not filenames, since they're translated into filenames in a platform-specific
 624      way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
 625      DOS/Windows).  However, they can include a directory component, which means the
 626      linker will look in that specific directory rather than searching all the normal
 627      locations.
 628
 629      *library_dirs*, if supplied, should be a list of directories to search for
 630      libraries that were specified as bare library names (ie. no directory
 631      component).  These are on top of the system default and those supplied to
 632      :meth:`add_library_dir` and/or :meth:`set_library_dirs`.  *runtime_library_dirs*
 633      is a list of directories that will be embedded into the shared library and used
 634      to search for other shared libraries that \*it\* depends on at run-time.  (This
 635      may only be relevant on Unix.)
 636
 637      *export_symbols* is a list of symbols that the shared library will export.
 638      (This appears to be relevant only on Windows.)
 639
 640      *debug* is as for :meth:`compile` and :meth:`create_static_lib`,  with the
 641      slight distinction that it actually matters on most platforms (as opposed to
 642      :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
 643      sake).
 644
 645      *extra_preargs* and *extra_postargs* are as for :meth:`compile`  (except of
 646      course that they supply command-line arguments for the particular linker being
 647      used).
 648
 649      *target_lang* is the target language for which the given objects are being
 650      compiled. This allows specific linkage time treatment of certain languages.
 651
 652      Raises :exc:`LinkError` on failure.
 653
 654
 655   .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
 656
 657      Link an executable.  *output_progname* is the name of the file executable, while
 658      *objects* are a list of object filenames to link in. Other arguments  are as for
 659      the :meth:`link` method.
 660
 661
 662   .. method:: CCompiler.link_shared_lib(objects, output_libname[, 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])
 663
 664      Link a shared library. *output_libname* is the name of the output  library,
 665      while *objects* is a list of object filenames to link in.  Other arguments are
 666      as for the :meth:`link` method.
 667
 668
 669   .. method:: CCompiler.link_shared_object(objects, output_filename[, 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])
 670
 671      Link a shared object. *output_filename* is the name of the shared object that
 672      will be created, while *objects* is a list of object filenames  to link in.
 673      Other arguments are as for the :meth:`link` method.
 674
 675
 676   .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
 677
 678      Preprocess a single C/C++ source file, named in *source*. Output will be written
 679      to file named *output_file*, or *stdout* if *output_file* not supplied.
 680      *macros* is a list of macro definitions as for :meth:`compile`, which will
 681      augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
 682      *include_dirs* is a list of directory names that will be added to the  default
 683      list, in the same way as :meth:`add_include_dir`.
 684
 685      Raises :exc:`PreprocessError` on failure.
 686
 687   The following utility methods are defined by the :class:`CCompiler` class, for
 688   use by the various concrete subclasses.
 689
 690
 691   .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
 692
 693      Returns the filename of the executable for the given *basename*.  Typically for
 694      non-Windows platforms this is the same as the basename,  while Windows will get
 695      a :file:`.exe` added.
 696
 697
 698   .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
 699
 700      Returns the filename for the given library name on the current platform. On Unix
 701      a library with *lib_type* of ``'static'`` will typically  be of the form
 702      :file:`liblibname.a`, while a *lib_type* of ``'dynamic'``  will be of the form
 703      :file:`liblibname.so`.
 704
 705
 706   .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
 707
 708      Returns the name of the object files for the given source files.
 709      *source_filenames* should be a list of filenames.
 710
 711
 712   .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
 713
 714      Returns the name of a shared object file for the given file name *basename*.
 715
 716
 717   .. method:: CCompiler.execute(func, args[, msg=None, level=1])
 718
 719      Invokes :func:`distutils.util.execute` This method invokes a  Python function
 720      *func* with the given arguments *args*, after  logging and taking into account
 721      the *dry_run* flag. XXX see also.
 722
 723
 724   .. method:: CCompiler.spawn(cmd)
 725
 726      Invokes :func:`distutils.util.spawn`. This invokes an external  process to run
 727      the given command. XXX see also.
 728
 729
 730   .. method:: CCompiler.mkpath(name[, mode=511])
 731
 732      Invokes :func:`distutils.dir_util.mkpath`. This creates a directory  and any
 733      missing ancestor directories. XXX see also.
 734
 735
 736   .. method:: CCompiler.move_file(src, dst)
 737
 738      Invokes :meth:`distutils.file_util.move_file`. Renames *src* to  *dst*.  XXX see
 739      also.
 740
 741
 742   .. method:: CCompiler.announce(msg[, level=1])
 743
 744      Write a message using :func:`distutils.log.debug`. XXX see also.
 745
 746
 747   .. method:: CCompiler.warn(msg)
 748
 749      Write a warning message *msg* to standard error.
 750
 751
 752   .. method:: CCompiler.debug_print(msg)
 753
 754      If the *debug* flag is set on this :class:`CCompiler` instance, print  *msg* to
 755      standard output, otherwise do nothing.
 756
 757.. % \subsection{Compiler-specific modules}
 758.. %
 759.. % The following modules implement concrete subclasses of the abstract
 760.. % \class{CCompiler} class. They should not be instantiated directly, but should
 761.. % be created using \function{distutils.ccompiler.new_compiler()} factory
 762.. % function.
 763
 764
 765:mod:`distutils.unixccompiler` --- Unix C Compiler
 766==================================================
 767
 768.. module:: distutils.unixccompiler
 769   :synopsis: UNIX C Compiler
 770
 771
 772This module provides the :class:`UnixCCompiler` class, a subclass of
 773:class:`CCompiler` that handles the typical Unix-style command-line  C compiler:
 774
 775* macros defined with :option:`-Dname[=value]`
 776
 777* macros undefined with :option:`-Uname`
 778
 779* include search directories specified with :option:`-Idir`
 780
 781* libraries specified with :option:`-llib`
 782
 783* library search directories specified with :option:`-Ldir`
 784
 785* compile handled by :program:`cc` (or similar) executable with :option:`-c`
 786  option: compiles :file:`.c` to :file:`.o`
 787
 788* link static library handled by :program:`ar` command (possibly with
 789  :program:`ranlib`)
 790
 791* link shared library handled by :program:`cc` :option:`-shared`
 792
 793
 794:mod:`distutils.msvccompiler` --- Microsoft Compiler
 795====================================================
 796
 797.. module:: distutils.msvccompiler
 798   :synopsis: Microsoft Compiler
 799
 800
 801This module provides :class:`MSVCCompiler`, an implementation of the abstract
 802:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
 803modules need to be compiled with the same compiler that was used to compile
 804Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
 8052.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
 806binaries are created using the Platform SDK.
 807
 808:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
 809its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
 810and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
 811been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
 812had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
 813that the distutils user has made an explicit choice to override the compiler
 814selection by :class:`MSVCCompiler`.
 815
 816
 817:mod:`distutils.bcppcompiler` --- Borland Compiler
 818==================================================
 819
 820.. module:: distutils.bcppcompiler
 821
 822
 823This module provides :class:`BorlandCCompiler`, an subclass of the abstract
 824:class:`CCompiler` class for the Borland C++ compiler.
 825
 826
 827:mod:`distutils.cygwincompiler` --- Cygwin Compiler
 828===================================================
 829
 830.. module:: distutils.cygwinccompiler
 831
 832
 833This module provides the :class:`CygwinCCompiler` class, a subclass of
 834:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
 835Windows.  It also contains the Mingw32CCompiler class which handles the mingw32
 836port of GCC (same as cygwin in no-cygwin mode).
 837
 838
 839:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler
 840===================================================
 841
 842.. module:: distutils.emxccompiler
 843   :synopsis: OS/2 EMX Compiler support
 844
 845
 846This module provides the EMXCCompiler class, a subclass of
 847:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
 848
 849
 850:mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support
 851==================================================================
 852
 853.. module:: distutils.mwerkscompiler
 854   :synopsis: Metrowerks CodeWarrior support
 855
 856
 857Contains :class:`MWerksCompiler`, an implementation of the abstract
 858:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X
 859Macintosh. Needs work to support CW on Windows or Mac OS X.
 860
 861.. % \subsection{Utility modules}
 862.. %
 863.. % The following modules all provide general utility functions. They haven't
 864.. % all been documented yet.
 865
 866
 867:mod:`distutils.archive_util` ---  Archiving utilities
 868======================================================
 869
 870.. module:: distutils.archive_util
 871   :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
 872
 873
 874This module provides a few functions for creating archive files, such as
 875tarballs or zipfiles.
 876
 877
 878.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
 879
 880   Create an archive file (eg. ``zip`` or ``tar``).  *base_name*  is the name of
 881   the file to create, minus any format-specific extension;  *format* is the
 882   archive format: one of ``zip``, ``tar``,  ``ztar``, or ``gztar``. *root_dir* is
 883   a directory that will be the root directory of the archive; ie. we typically
 884   ``chdir`` into *root_dir* before  creating the archive.  *base_dir* is the
 885   directory where we start  archiving from; ie. *base_dir* will be the common
 886   prefix of all files and directories in the archive.  *root_dir* and *base_dir*
 887   both default to the current directory.  Returns the name of the archive file.
 888
 889   .. XXX This should be changed to support bz2 files.
 890
 891
 892.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
 893
 894   'Create an (optional compressed) archive as a tar file from all files in and
 895   under *base_dir*. *compress* must be ``'gzip'`` (the default),  ``'compress'``,
 896   ``'bzip2'``, or ``None``.  Both :program:`tar` and the compression utility named
 897   by *compress* must be on the  default program search path, so this is probably
 898   Unix-specific.  The  output tar file will be named :file:`base_dir.tar`,
 899   possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
 900   or :file:`.Z`).  Return the output filename.
 901
 902   .. XXX This should be replaced with calls to the :mod:`tarfile` module.
 903
 904
 905.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
 906
 907   Create a zip file from all files in and under *base_dir*.  The output zip file
 908   will be named *base_dir* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python
 909   module (if available) or the InfoZIP :file:`zip`  utility (if installed and
 910   found on the default search path).  If neither  tool is available, raises
 911   :exc:`DistutilsExecError`.   Returns the name of the output zip file.
 912
 913
 914:mod:`distutils.dep_util` --- Dependency checking
 915=================================================
 916
 917.. module:: distutils.dep_util
 918   :synopsis: Utility functions for simple dependency checking
 919
 920
 921This module provides functions for performing simple, timestamp-based
 922dependency of files and groups of files; also, functions based entirely  on such
 923timestamp dependency analysis.
 924
 925
 926.. function:: newer(source, target)
 927
 928   Return true if *source* exists and is more recently modified than *target*, or
 929   if *source* exists and *target* doesn't. Return false if both exist and *target*
 930   is the same age or newer  than *source*. Raise :exc:`DistutilsFileError` if
 931   *source* does not exist.
 932
 933
 934.. function:: newer_pairwise(sources, targets)
 935
 936   Walk two filename lists in parallel, testing if each source is newer than its
 937   corresponding target.  Return a pair of lists (*sources*, *targets*) where
 938   source is newer than target, according to the semantics of :func:`newer`
 939
 940   .. % % equivalent to a listcomp...
 941
 942
 943.. function:: newer_group(sources, target[, missing='error'])
 944
 945   Return true if *target* is out-of-date with respect to any file listed in
 946   *sources*  In other words, if *target* exists and is newer than every file in
 947   *sources*, return false; otherwise return true. *missing* controls what we do
 948   when a source file is missing; the default (``'error'``) is to blow up with an
 949   :exc:`OSError` from  inside :func:`os.stat`; if it is ``'ignore'``, we silently
 950   drop any missing source files; if it is ``'newer'``, any missing source files
 951   make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
 952   it'll make you pretend to carry out commands that wouldn't work because inputs
 953   are missing, but that doesn't matter because you're not actually going to run
 954   the commands).
 955
 956
 957:mod:`distutils.dir_util` --- Directory tree operations
 958=======================================================
 959
 960.. module:: distutils.dir_util
 961   :synopsis: Utility functions for operating on directories and directory trees
 962
 963
 964This module provides functions for operating on directories and trees of
 965directories.
 966
 967
 968.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0])
 969
 970   Create a directory and any missing ancestor directories.  If the directory
 971   already exists (or if *name* is the empty string, which means the current
 972   directory, which of course exists), then do nothing.  Raise
 973   :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
 974   some sub-path exists, but is a file rather than a directory).  If *verbose* is
 975   true, print a one-line summary of each mkdir to stdout.  Return the list of
 976   directories actually created.
 977
 978
 979.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0])
 980
 981   Create all the empty directories under *base_dir* needed to put *files* there.
 982   *base_dir* is just the a name of a directory which doesn't necessarily exist
 983   yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
 984   *base_dir* + the directory portion of every file in *files* will be created if
 985   it doesn't already exist.  *mode*, *verbose* and *dry_run* flags  are as for
 986   :func:`mkpath`.
 987
 988
 989.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
 990
 991   Copy an entire directory tree *src* to a new location *dst*.  Both *src* and
 992   *dst* must be directory names.  If *src* is not a directory, raise
 993   :exc:`DistutilsFileError`.  If *dst* does  not exist, it is created with
 994   :func:`mkpath`.  The end result of the  copy is that every file in *src* is
 995   copied to *dst*, and  directories under *src* are recursively copied to *dst*.
 996   Return the list of files that were copied or might have been copied, using their
 997   output name. The return value is unaffected by *update* or *dry_run*: it is
 998   simply the list of all files under *src*, with the names changed to be under
 999   *dst*.
1000
1001   *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
1002   :mod:`distutils.file_util`; note that they only apply to regular files, not to
1003   directories.  If *preserve_symlinks* is true, symlinks will be copied as
1004   symlinks (on platforms that support them!); otherwise (the default), the
1005   destination of the symlink will be copied.  *update* and *verbose* are the same
1006   as for :func:`copy_file`.
1007
1008
1009.. function:: remove_tree(directory[, verbose=0, dry_run=0])
1010
1011   Recursively remove *directory* and all files and directories underneath it. Any
1012   errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
1013   true).
1014
1015**\*\*** Some of this could be replaced with the shutil module? **\*\***
1016
1017
1018:mod:`distutils.file_util` --- Single file operations
1019=====================================================
1020
1021.. module:: distutils.file_util
1022   :synopsis: Utility functions for operating on single files
1023
1024
1025This module contains some utility functions for operating on individual files.
1026
1027
1028.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
1029
1030   Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
1031   with the same name; otherwise, it must be a filename. (If the file exists, it
1032   will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
1033   file's mode (type and permission bits, or whatever is analogous on the
1034   current platform) is copied. If *preserve_times* is true (the default), the
1035   last-modified and last-access times are copied as well. If *update* is true,
1036   *src* will only be copied if *dst* does not exist, or if *dst* does exist but
1037   is older than *src*.
1038
1039   *link* allows you to make hard links (using :func:`os.link`) or symbolic links
1040   (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
1041   ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
1042   on systems that don't support it: :func:`copy_file` doesn't check if hard or
1043   symbolic linking is available.  It uses :func:`_copy_file_contents` to copy file
1044   contents.
1045
1046   Return a tuple ``(dest_name, copied)``: *dest_name* is the actual  name of the
1047   output file, and *copied* is true if the file was copied  (or would have been
1048   copied, if *dry_run* true).
1049
1050   .. % XXX if the destination file already exists, we clobber it if
1051   .. % copying, but blow up if linking.  Hmmm.  And I don't know what
1052   .. % macostools.copyfile() does.  Should definitely be consistent, and
1053   .. % should probably blow up if destination exists and we would be
1054   .. % changing it (ie. it's not already a hard/soft link to src OR
1055   .. % (not update) and (src newer than dst)).
1056
1057
1058.. function:: move_file(src, dst[, verbose, dry_run])
1059
1060   Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
1061   it with the same name; otherwise, *src* is just renamed to *dst*.  Returns the
1062   new full name of the file.
1063
1064   .. warning::
1065
1066      Handles cross-device moves on Unix using :func:`copy_file`.  What about
1067      other systems?
1068
1069
1070.. function:: write_file(filename, contents)
1071
1072   Create a file called *filename* and write *contents* (a sequence of strings
1073   without line terminators) to it.
1074
1075
1076:mod:`distutils.util` --- Miscellaneous other utility functions
1077===============================================================
1078
1079.. module:: distutils.util
1080   :synopsis: Miscellaneous other utility functions
1081
1082
1083This module contains other assorted bits and pieces that don't fit into  any
1084other utility module.
1085
1086
1087.. function:: get_platform()
1088
1089   Return a string that identifies the current platform.  This is used mainly to
1090   distinguish platform-specific build directories and platform-specific built
1091   distributions.  Typically includes the OS name and version and the architecture
1092   (as supplied by 'os.uname()'), although the exact information included depends
1093   on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
1094   runs on SGI hardware), but for Linux the kernel version isn't particularly
1095   important.
1096
1097   Examples of returned values:
1098
1099   * ``linux-i586``
1100   * ``linux-alpha``
1101   * ``solaris-2.6-sun4u``
1102   * ``irix-5.3``
1103   * ``irix64-6.2``
1104
1105   For non-POSIX platforms, currently just returns ``sys.platform``.
1106
1107   For Mac OS X systems the OS version reflects the minimal version on which
1108   binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
1109   during the build of Python), not the OS version of the current system.
1110
1111   For universal binary builds on Mac OS X the architecture value reflects
1112   the univeral binary status instead of the architecture of the current
1113   processor. For 32-bit universal binaries the architecture is ``fat``,
1114   for 64-bit universal binaries the architecture is ``fat64``, and
1115   for 4-way universal binaries the architecture is ``universal``. Starting
1116   from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
1117   a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
1118   a univeral build with the i386 and x86_64 architectures
1119
1120   Examples of returned values on Mac OS X:
1121
1122   * ``macosx-10.3-ppc``
1123
1124   * ``macosx-10.3-fat``
1125
1126   * ``macosx-10.5-universal``
1127
1128   * ``macosx-10.6-intel``
1129
1130   .. % XXX isn't this also provided by some other non-distutils module?
1131
1132
1133.. function:: convert_path(pathname)
1134
1135   Return 'pathname' as a name that will work on the native filesystem, i.e. split
1136   it on '/' and put it back together again using the current directory separator.
1137   Needed because filenames in the setup script are always supplied in Unix style,
1138   and have to be converted to the local convention before we can actually use them
1139   in the filesystem.  Raises :exc:`ValueError` on non-Unix-ish systems if
1140   *pathname* either  starts or ends with a slash.
1141
1142
1143.. function:: change_root(new_root, pathname)
1144
1145   Return *pathname* with *new_root* prepended.  If *pathname* is relative, this is
1146   equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
1147   *pathname* relative and then joining the two, which is tricky on DOS/Windows.
1148
1149
1150.. function:: check_environ()
1151
1152   Ensure that 'os.environ' has all the environment variables we guarantee that
1153   users can use in config files, command-line options, etc.  Currently this
1154   includes:
1155
1156   * :envvar:`HOME` - user's home directory (Unix only)
1157   * :envvar:`PLAT` - description of the current platform, including hardware and
1158     OS (see :func:`get_platform`)
1159
1160
1161.. function:: subst_vars(s, local_vars)
1162
1163   Perform shell/Perl-style variable substitution on *s*.  Every occurrence of
1164   ``$`` followed by a name is considered a variable, and variable is substituted
1165   by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
1166   not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
1167   it contains certain values: see :func:`check_environ`.  Raise :exc:`ValueError`
1168   for any variables not found in either *local_vars* or ``os.environ``.
1169
1170   Note that this is not a fully-fledged string interpolation function. A valid
1171   ``$variable`` can consist only of upper and lower case letters, numbers and an
1172   underscore. No { } or ( ) style quoting is available.
1173
1174
1175.. function:: grok_environment_error(exc[, prefix='error: '])
1176
1177   Generate a useful error message from an :exc:`EnvironmentError`  (:exc:`IOError`
1178   or :exc:`OSError`) exception object.   Handles Python 1.5.1 and later styles,
1179   and does what it can to deal with  exception objects that don't have a filename
1180   (which happens when the error  is due to a two-file operation, such as
1181   :func:`rename` or  :func:`link`).  Returns the error message as a string
1182   prefixed  with *prefix*.
1183
1184
1185.. function:: split_quoted(s)
1186
1187   Split a string up according to Unix shell-like rules for quotes and backslashes.
1188   In short: words are delimited by spaces, as long as those spaces are not escaped
1189   by a backslash, or inside a quoted string. Single and double quotes are
1190   equivalent, and the quote characters can be backslash-escaped.  The backslash is
1191   stripped from any two-character escape sequence, leaving only the escaped
1192   character.  The quote characters are stripped from any quoted string.  Returns a
1193   list of words.
1194
1195   .. % Should probably be moved into the standard library.
1196
1197
1198.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
1199
1200   Perform some action that affects the outside world (for instance, writing to the
1201   filesystem).  Such actions are special because they are disabled by the
1202   *dry_run* flag.  This method takes  care of all that bureaucracy for you; all
1203   you have to do is supply the function to call and an argument tuple for it (to
1204   embody the "external action" being performed), and an optional message to print.
1205
1206
1207.. function:: strtobool(val)
1208
1209   Convert a string representation of truth to true (1) or false (0).
1210
1211   True values are ``y``, ``yes``, ``t``, ``true``, ``on``  and ``1``; false values
1212   are ``n``, ``no``, ``f``, ``false``,  ``off`` and ``0``.  Raises
1213   :exc:`ValueError` if *val*  is anything else.
1214
1215
1216.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
1217
1218   Byte-compile a collection of Python source files to either :file:`.pyc` or
1219   :file:`.pyo` files in the same directory.  *py_files* is a list of files to
1220   compile; any files that don't end in :file:`.py` are silently skipped.
1221   *optimize* must be one of the following:
1222
1223   * ``0`` - don't optimize (generate :file:`.pyc`)
1224   * ``1`` - normal optimization (like ``python -O``)
1225   * ``2`` - extra optimization (like ``python -OO``)
1226
1227   If *force* is true, all files are recompiled regardless of timestamps.
1228
1229   The source filename encoded in each :term:`bytecode` file defaults to the filenames
1230   listed in *py_files*; you can modify these with *prefix* and *basedir*.
1231   *prefix* is a string that will be stripped off of each source filename, and
1232   *base_dir* is a directory name that will be prepended (after *prefix* is
1233   stripped).  You can supply either or both (or neither) of *prefix* and
1234   *base_dir*, as you wish.
1235
1236   If *dry_run* is true, doesn't actually do anything that would affect the
1237   filesystem.
1238
1239   Byte-compilation is either done directly in this interpreter process with the
1240   standard :mod:`py_compile` module, or indirectly by writing a temporary script
1241   and executing it.  Normally, you should let :func:`byte_compile` figure out to
1242   use direct compilation or not (see the source for details).  The *direct* flag
1243   is used by the script generated in indirect mode; unless you know what you're
1244   doing, leave it set to ``None``.
1245
1246
1247.. function:: rfc822_escape(header)
1248
1249   Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
1250   ensuring there are 8 spaces space after each newline. Note that it does no other
1251   modification of the string.
1252
1253   .. % this _can_ be replaced
1254
1255.. % \subsection{Distutils objects}
1256
1257
1258:mod:`distutils.dist` --- The Distribution class
1259================================================
1260
1261.. module:: distutils.dist
1262   :synopsis: Provides the Distribution class, which represents the module distribution being
1263              built/installed/distributed
1264
1265
1266This module provides the :class:`Distribution` class, which represents the
1267module distribution being built/installed/distributed.
1268
1269
1270:mod:`distutils.extension` --- The Extension class
1271==================================================
1272
1273.. module:: distutils.extension
1274   :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
1275              scripts
1276
1277
1278This module provides the :class:`Extension` class, used to describe C/C++
1279extension modules in setup scripts.
1280
1281.. % \subsection{Ungrouped modules}
1282.. % The following haven't been moved into a more appropriate section yet.
1283
1284
1285:mod:`distutils.debug` --- Distutils debug mode
1286===============================================
1287
1288.. module:: distutils.debug
1289   :synopsis: Provides the debug flag for distutils
1290
1291
1292This module provides the DEBUG flag.
1293
1294
1295:mod:`distutils.errors` --- Distutils exceptions
1296================================================
1297
1298.. module:: distutils.errors
1299   :synopsis: Provides standard distutils exceptions
1300
1301
1302Provides exceptions used by the Distutils modules.  Note that Distutils modules
1303may raise standard exceptions; in particular, SystemExit is usually raised for
1304errors that are obviously the end-user's fault (eg. bad command-line arguments).
1305
1306This module is safe to use in ``from ... import *`` mode; it only exports
1307symbols whose names start with ``Distutils`` and end with ``Error``.
1308
1309
1310:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
1311===========================================================================
1312
1313.. module:: distutils.fancy_getopt
1314   :synopsis: Additional getopt functionality
1315
1316
1317This module provides a wrapper around the standard :mod:`getopt`  module that
1318provides the following additional features:
1319
1320* short and long options are tied together
1321
1322* options have help strings, so :func:`fancy_getopt` could potentially  create a
1323  complete usage summary
1324
1325* options set attributes of a passed-in object
1326
1327* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is
1328  the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
1329  command line sets *verbose* to false.
1330
1331**\*\*** Should be replaced with :mod:`optik` (which is also now known as
1332:mod:`optparse` in Python 2.3 and later). **\*\***
1333
1334
1335.. function:: fancy_getopt(options, negative_opt, object, args)
1336
1337   Wrapper function. *options* is a list of ``(long_option, short_option,
1338   help_string)`` 3-tuples as described in the constructor for
1339   :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
1340   to option names, both the key and value should be in the *options* list.
1341   *object* is an object which will be used to store values (see the :meth:`getopt`
1342   method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
1343   ``sys.argv[1:]`` if you  pass ``None`` as *args*.
1344
1345
1346.. function:: wrap_text(text, width)
1347
1348   Wraps *text* to less than *width* wide.
1349
1350   .. XXX Should be replaced with :mod:`textwrap` (which is available in Python
1351      2.3 and later).
1352
1353
1354.. class:: FancyGetopt([option_table=None])
1355
1356   The option_table is a list of 3-tuples: ``(long_option, short_option,
1357   help_string)``
1358
1359   If an option takes an argument, its *long_option* should have ``'='`` appended;
1360   *short_option* should just be a single character, no ``':'`` in any case.
1361   *short_option* should be ``None`` if a *long_option*  doesn't have a
1362   corresponding *short_option*. All option tuples must have long options.
1363
1364The :class:`FancyGetopt` class provides the following methods:
1365
1366
1367.. method:: FancyGetopt.getopt([args=None, object=None])
1368
1369   Parse command-line options in args. Store as attributes on *object*.
1370
1371   If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``.  If *object* is
1372   ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
1373   option values there, and returns a tuple ``(args, object)``.  If *object* is
1374   supplied, it is modified in place and :func:`getopt` just returns *args*; in
1375   both cases, the returned *args* is a modified copy of the passed-in *args* list,
1376   which is left untouched.
1377
1378   .. % and args returned are?
1379
1380
1381.. method:: FancyGetopt.get_option_order()
1382
1383   Returns the list of ``(option, value)`` tuples processed by the previous run of
1384   :meth:`getopt`  Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
1385   yet.
1386
1387
1388.. method:: FancyGetopt.generate_help([header=None])
1389
1390   Generate help text (a list of strings, one per suggested line of output) from
1391   the option table for this :class:`FancyGetopt` object.
1392
1393   If supplied, prints the supplied *header* at the top of the help.
1394
1395
1396:mod:`distutils.filelist` --- The FileList class
1397================================================
1398
1399.. module:: distutils.filelist
1400   :synopsis: The FileList class, used for poking about the file system and
1401              building lists of files.
1402
1403
1404This module provides the :class:`FileList` class, used for poking about the
1405filesystem and building lists of files.
1406
1407
1408:mod:`distutils.log` --- Simple PEP 282-style logging
1409=====================================================
1410
1411.. module:: distutils.log
1412   :synopsis: A simple logging mechanism, 282-style
1413
1414
1415.. XXX Should be replaced with standard :mod:`logging` module.
1416
1417
1418
1419:mod:`distutils.spawn` --- Spawn a sub-process
1420==============================================
1421
1422.. module:: distutils.spawn
1423   :synopsis: Provides the spawn() function
1424
1425
1426This module provides the :func:`spawn` function, a front-end to  various
1427platform-specific functions for launching another program in a  sub-process.
1428Also provides :func:`find_executable` to search the path for a given executable
1429name.
1430
1431
1432:mod:`distutils.sysconfig` --- System configuration information
1433===============================================================
1434
1435.. module:: distutils.sysconfig
1436   :synopsis: Low-level access to configuration information of the Python interpreter.
1437.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1438.. moduleauthor:: Greg Ward <gward@python.net>
1439.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1440
1441
1442The :mod:`distutils.sysconfig` module provides access to Python's low-level
1443configuration information.  The specific configuration variables available
1444depend heavily on the platform and configuration. The specific variables depend
1445on the build process for the specific version of Python being run; the variables
1446are those found in the :file:`Makefile` and configuration header that are
1447installed with Python on Unix systems.  The configuration header is called
1448:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
1449for earlier versions of Python.
1450
1451Some additional functions are provided which perform some useful manipulations
1452for other parts of the :mod:`distutils` package.
1453
1454
1455.. data:: PREFIX
1456
1457   The result of ``os.path.normpath(sys.prefix)``.
1458
1459
1460.. data:: EXEC_PREFIX
1461
1462   The result of ``os.path.normpath(sys.exec_prefix)``.
1463
1464
1465.. function:: get_config_var(name)
1466
1467   Return the value of a single variable.  This is equivalent to
1468   ``get_config_vars().get(name)``.
1469
1470
1471.. function:: get_config_vars(...)
1472
1473   Return a set of variable definitions.  If there are no arguments, this returns a
1474   dictionary mapping names of configuration variables to values.  If arguments are
1475   provided, they should be strings, and the return value will be a sequence giving
1476   the associated values. If a given name does not have a corresponding value,
1477   ``None`` will be included for that variable.
1478
1479
1480.. function:: get_config_h_filename()
1481
1482   Return the full path name of the configuration header.  For Unix, this will be
1483   the header generated by the :program:`configure` script; for other platforms the
1484   header will have been supplied directly by the Python source distribution.  The
1485   file is a platform-specific text file.
1486
1487
1488.. function:: get_makefile_filename()
1489
1490   Return the full path name of the :file:`Makefile` used to build Python.  For
1491   Unix, this will be a file generated by the :program:`configure` script; the
1492   meaning for other platforms will vary.  The file is a platform-specific text
1493   file, if it exists. This function is only useful on POSIX platforms.
1494
1495
1496.. function:: get_python_inc([plat_specific[, prefix]])
1497
1498   Return the directory for either the general or platform-dependent C include
1499   files.  If *plat_specific* is true, the platform-dependent include directory is
1500   returned; if false or omitted, the platform-independent directory is returned.
1501   If *prefix* is given, it is used as either the prefix instead of
1502   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1503   *plat_specific* is true.
1504
1505
1506.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
1507
1508   Return the directory for either the general or platform-dependent library
1509   installation.  If *plat_specific* is true, the platform-dependent include
1510   directory is returned; if false or omitted, the platform-independent directory
1511   is returned.  If *prefix* is given, it is used as either the prefix instead of
1512   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1513   *plat_specific* is true.  If *standard_lib* is true, the directory for the
1514   standard library is returned rather than the directory for the installation of
1515   third-party extensions.
1516
1517The following function is only intended for use within the :mod:`distutils`
1518package.
1519
1520
1521.. function:: customize_compiler(compiler)
1522
1523   Do any platform-specific customization of a
1524   :class:`distutils.ccompiler.CCompiler` instance.
1525
1526   This function is only needed on Unix at this time, but should be called
1527   consistently to support forward-compatibility.  It inserts the information that
1528   varies across Unix flavors and is stored in Python's :file:`Makefile`.  This
1529   information includes the selected compiler, compiler and linker options, and the
1530   extension used by the linker for shared objects.
1531
1532This function is even more special-purpose, and should only be used from
1533Python's own build procedures.
1534
1535
1536.. function:: set_python_build()
1537
1538   Inform the :mod:`distutils.sysconfig` module that it is being used as part of
1539   the build process for Python.  This changes a lot of relative locations for
1540   files, allowing them to be located in the build area rather than in an installed
1541   Python.
1542
1543
1544:mod:`distutils.text_file` --- The TextFile class
1545=================================================
1546
1547.. module:: distutils.text_file
1548   :synopsis: provides the TextFile class, a simple interface to text files
1549
1550
1551This module provides the :class:`TextFile` class, which gives an interface  to
1552text files that (optionally) takes care of stripping comments, ignoring  blank
1553lines, and joining lines with backslashes.
1554
1555
1556.. class:: TextFile([filename=None, file=None, **options])
1557
1558   This class provides a file-like object that takes care of all  the things you
1559   commonly want to do when processing a text file  that has some line-by-line
1560   syntax: strip comments (as long as ``#``  is your comment character), skip blank
1561   lines, join adjacent lines by escaping the newline (ie. backslash at end of
1562   line), strip leading and/or trailing whitespace.  All of these are optional and
1563   independently controllable.
1564
1565   The class provides a :meth:`warn` method so you can generate  warning messages
1566   that report physical line number, even if the  logical line in question spans
1567   multiple physical lines.  Also  provides :meth:`unreadline` for implementing
1568   line-at-a-time lookahead.
1569
1570   :class:`TextFile` instances are create with either *filename*, *file*, or both.
1571   :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
1572   string, and *file* a file object (or something that provides :meth:`readline`
1573   and :meth:`close`  methods).  It is recommended that you supply at least
1574   *filename*,  so that :class:`TextFile` can include it in warning messages.  If
1575   *file* is not supplied, :class:`TextFile` creates its own using the
1576   :func:`open` built-in function.
1577
1578   The options are all boolean, and affect the values returned by :meth:`readline`
1579
1580   +------------------+--------------------------------+---------+
1581   | option name      | description                    | default |
1582   +==================+================================+=========+
1583   | *strip_comments* | strip from ``'#'`` to end-of-  | true    |
1584   |                  | line, as well as any           |         |
1585   |                  | whitespace leading up to the   |         |
1586   |                  | ``'#'``\ ---unless it is       |         |
1587   |                  | escaped by a backslash         |         |
1588   +------------------+--------------------------------+---------+
1589   | *lstrip_ws*      | strip leading whitespace from  | false   |
1590   |                  | each line before returning it  |         |
1591   +------------------+--------------------------------+---------+
1592   | *rstrip_ws*      | strip trailing whitespace      | true    |
1593   |                  | (including line terminator!)   |         |
1594   |                  | from each line before          |         |
1595   |                  | returning it.                  |         |
1596   +------------------+--------------------------------+---------+
1597   | *skip_blanks*    | skip lines that are empty      | true    |
1598   |                  | \*after\* stripping comments   |         |
1599   |                  | and whitespace.  (If both      |         |
1600   |                  | lstrip_ws and rstrip_ws are    |         |
1601   |                  | false, then some lines may     |         |
1602   |                  | consist of solely whitespace:  |         |
1603   |                  | these will \*not\* be skipped, |         |
1604   |                  | even if *skip_blanks* is       |         |
1605   |                  | true.)                         |         |
1606   +------------------+--------------------------------+---------+
1607   | *join_lines*     | if a backslash is the last     | false   |
1608   |                  | non-newline character on a     |         |
1609   |                  | line after stripping comments  |         |
1610   |                  | and whitespace, join the       |         |
1611   |                  | following line to it to form   |         |
1612   |                  | one logical line; if N         |         |
1613   |                  | consecutive lines end with a   |         |
1614   |                  | backslash, then N+1 physical   |         |
1615   |                  | lines will be joined to form   |         |
1616   |                  | one logical line.              |         |
1617   +------------------+--------------------------------+---------+
1618   | *collapse_join*  | strip leading whitespace from  | false   |
1619   |                  | lines that are joined to their |         |
1620   |                  | predecessor; only matters if   |         |
1621   |                  | ``(join_lines and not          |         |
1622   |                  | lstrip_ws)``                   |         |
1623   +------------------+--------------------------------+---------+
1624
1625   Note that since *rstrip_ws* can strip the trailing newline, the semantics of
1626   :meth:`readline` must differ from those of the builtin file object's
1627   :meth:`readline` method!  In particular, :meth:`readline`  returns ``None`` for
1628   end-of-file: an empty string might just be a  blank line (or an all-whitespace
1629   line), if *rstrip_ws* is true  but *skip_blanks* is not.
1630
1631
1632   .. method:: TextFile.open(filename)
1633
1634      Open a new file *filename*. This overrides any *file* or  *filename* constructor
1635      arguments.
1636
1637
1638   .. method:: TextFile.close()
1639
1640      Close the current file and forget everything we know about it (including the
1641      filename and the current line number).
1642
1643
1644   .. method:: TextFile.warn(msg[,line=None])
1645
1646      Print (to stderr) a warning message tied to the current logical line in the
1647      current file.  If the current logical line in the file spans multiple physical
1648      lines, the warning refers to the whole range, such as ``"lines 3-5"``.  If
1649      *line* is supplied,  it overrides the current line number; it may be a list or
1650      tuple  to indicate a range of physical lines, or an integer for a  single
1651      physical line.
1652
1653
1654   .. method:: TextFile.readline()
1655
1656      Read and return a single logical line from the current file (or from an internal
1657      buffer if lines have previously been "unread" with :meth:`unreadline`).  If the
1658      *join_lines* option  is true, this may involve reading multiple physical lines
1659      concatenated into a single string.  Updates the current line number,  so calling
1660      :meth:`warn` after :meth:`readline` emits a warning  about the physical line(s)
1661      just read.  Returns ``None`` on end-of-file,  since the empty string can occur
1662      if *rstrip_ws* is true but  *strip_blanks* is not.
1663
1664
1665   .. method:: TextFile.readlines()
1666
1667      Read and return the list of all logical lines remaining in the current file.
1668      This updates the current line number to the last line of the file.
1669
1670
1671   .. method:: TextFile.unreadline(line)
1672
1673      Push *line* (a string) onto an internal buffer that will be checked by future
1674      :meth:`readline` calls.  Handy for implementing a parser with line-at-a-time
1675      lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
1676      subsequently re-cleansed (whitespace  stripped, or whatever) when read with
1677      :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
1678      to :meth:`readline`, the lines will be returned most in most recent first order.
1679
1680
1681:mod:`distutils.version` --- Version number classes
1682===================================================
1683
1684.. module:: distutils.version
1685   :synopsis: implements classes that represent module version numbers.
1686
1687
1688.. % todo
1689.. % \section{Distutils Commands}
1690.. %
1691.. % This part of Distutils implements the various Distutils commands, such
1692.. % as \code{build}, \code{install} \&c. Each command is implemented as a
1693.. % separate module, with the command name as the name of the module.
1694
1695
1696:mod:`distutils.cmd` --- Abstract base class for Distutils commands
1697===================================================================
1698
1699.. module:: distutils.cmd
1700   :synopsis: This module provides the abstract base class Command. This class is subclassed
1701              by the modules in the distutils.command  subpackage.
1702
1703
1704This module supplies the abstract base class :class:`Command`.
1705
1706
1707.. class:: Command(dist)
1708
1709   Abstract base class for defining command classes, the "worker bees" of the
1710   Distutils.  A useful analogy for command classes is to think of them as
1711   subroutines with local variables called *options*.  The options are declared in
1712   :meth:`initialize_options` and defined (given their final values) in
1713   :meth:`finalize_options`, both of which must be defined by every command class.
1714   The distinction between the two is necessary because option values might come
1715   from the outside world (command line, config file, ...), and any options
1716   dependent on other options must be computed after these outside influences have
1717   been processed --- hence :meth:`finalize_options`.  The body of the subroutine,
1718   where it does all its work based on the values of its options, is the
1719   :meth:`run` method, which must also be implemented by every command class.
1720
1721   The class constructor takes a single argument *dist*, a  :class:`Distribution`
1722   instance.
1723
1724
1725:mod:`distutils.command` --- Individual Distutils commands
1726==========================================================
1727
1728.. module:: distutils.command
1729   :synopsis: This subpackage contains one module for each standard Distutils command.
1730
1731
1732.. % \subsubsection{Individual Distutils commands}
1733.. % todo
1734
1735
1736:mod:`distutils.command.bdist` --- Build a binary installer
1737===========================================================
1738
1739.. module:: distutils.command.bdist
1740   :synopsis: Build a binary installer for a package
1741
1742
1743.. % todo
1744
1745
1746:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
1747=============================================================================
1748
1749.. module:: distutils.command.bdist_packager
1750   :synopsis: Abstract base class for packagers
1751
1752
1753.. % todo
1754
1755
1756:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
1757================================================================
1758
1759.. module:: distutils.command.bdist_dumb
1760   :synopsis: Build a "dumb" installer - a simple archive of files
1761
1762
1763.. % todo
1764
1765
1766:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
1767=================================================================================
1768
1769.. module:: distutils.command.bdist_msi
1770   :synopsis: Build a binary distribution as a Windows MSI file
1771
1772.. class:: bdist_msi(Command)
1773
1774   Builds a `Windows Installer`_ (.msi) binary package.
1775
1776   .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
1777
1778   In most cases, the ``bdist_msi`` installer is a better choice than the
1779   ``bdist_wininst`` installer, because it provides better support for
1780   Win64 platforms, allows administrators to perform non-interactive
1781   installations, and allows installation through group policies.
1782
1783
1784:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
1785===========================================================================================
1786
1787.. module:: distutils.command.bdist_rpm
1788   :synopsis: Build a binary distribution as a Redhat RPM and SRPM
1789
1790
1791.. % todo
1792
1793
1794:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
1795====================================================================
1796
1797.. module:: distutils.command.bdist_wininst
1798   :synopsis: Build a Windows installer
1799
1800
1801.. % todo
1802
1803
1804:mod:`distutils.command.sdist` --- Build a source distribution
1805==============================================================
1806
1807.. module:: distutils.command.sdist
1808   :synopsis: Build a source distribution
1809
1810
1811.. % todo
1812
1813
1814:mod:`distutils.command.build` --- Build all files of a package
1815===============================================================
1816
1817.. module:: distutils.command.build
1818   :synopsis: Build all files of a package
1819
1820
1821.. % todo
1822
1823
1824:mod:`distutils.command.build_clib` --- Build any C libraries in a package
1825==========================================================================
1826
1827.. module:: distutils.command.build_clib
1828   :synopsis: Build any C libraries in a package
1829
1830
1831.. % todo
1832
1833
1834:mod:`distutils.command.build_ext` --- Build any extensions in a package
1835========================================================================
1836
1837.. module:: distutils.command.build_ext
1838   :synopsis: Build any extensions in a package
1839
1840
1841.. % todo
1842
1843
1844:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
1845===========================================================================
1846
1847.. module:: distutils.command.build_py
1848   :synopsis: Build the .py/.pyc files of a package
1849
1850
1851.. % todo
1852
1853
1854:mod:`distutils.command.build_scripts` --- Build the scripts of a package
1855=========================================================================
1856
1857.. module:: distutils.command.build_scripts
1858   :synopsis: Build the scripts of a package
1859
1860
1861.. % todo
1862
1863
1864:mod:`distutils.command.clean` --- Clean a package build area
1865=============================================================
1866
1867.. module:: distutils.command.clean
1868   :synopsis: Clean a package build area
1869
1870
1871.. % todo
1872
1873
1874:mod:`distutils.command.config` --- Perform package configuration
1875=================================================================
1876
1877.. module:: distutils.command.config
1878   :synopsis: Perform package configuration
1879
1880
1881.. % todo
1882
1883
1884:mod:`distutils.command.install` --- Install a package
1885======================================================
1886
1887.. module:: distutils.command.install
1888   :synopsis: Install a package
1889
1890
1891.. % todo
1892
1893
1894:mod:`distutils.command.install_data` --- Install data files from a package
1895===========================================================================
1896
1897.. module:: distutils.command.install_data
1898   :synopsis: Install data files from a package
1899
1900
1901.. % todo
1902
1903
1904:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
1905======================================================================================
1906
1907.. module:: distutils.command.install_headers
1908   :synopsis: Install C/C++ header files from a package
1909
1910
1911.. % todo
1912
1913
1914:mod:`distutils.command.install_lib` --- Install library files from a package
1915=============================================================================
1916
1917.. module:: distutils.command.install_lib
1918   :synopsis: Install library files from a package
1919
1920
1921.. % todo
1922
1923
1924:mod:`distutils.command.install_scripts` --- Install script files from a package
1925================================================================================
1926
1927.. module:: distutils.command.install_scripts
1928   :synopsis: Install script files from a package
1929
1930
1931.. % todo
1932
1933
1934:mod:`distutils.command.register` --- Register a module with the Python Package Index
1935=====================================================================================
1936
1937.. module:: distutils.command.register
1938   :synopsis: Register a module with the Python Package Index
1939
1940
1941The ``register`` command registers the package with the Python Package  Index.
1942This is described in more detail in :pep:`301`.
1943
1944.. % todo
1945
1946
1947Creating a new Distutils command
1948================================
1949
1950This section outlines the steps to create a new Distutils command.
1951
1952A new command lives in a module in the :mod:`distutils.command` package. There
1953is a sample template in that directory called  :file:`command_template`. Copy
1954this file to a new module with the same name as the new command you're
1955implementing. This module should implement a class with the same name as the
1956module (and the command). So, for instance, to create the command
1957``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
1958:file:`command_template`  to :file:`distutils/command/peel_banana.py`, then edit
1959it so that it's implementing the class :class:`peel_banana`, a subclass of
1960:class:`distutils.cmd.Command`.
1961
1962Subclasses of :class:`Command` must define the following methods.
1963
1964
1965.. method:: Command.initialize_options()(S)
1966
1967   et default values for all the options that this command supports.  Note that
1968   these defaults may be overridden by other commands, by the setup script, by
1969   config files, or by the command-line.  Thus, this is not the place to code
1970   dependencies between options; generally, :meth:`initialize_options`
1971   implementations are just a bunch of ``self.foo = None`` assignments.
1972
1973
1974.. method:: Command.finalize_options()
1975
1976   Set final values for all the options that this command supports. This is
1977   always called as late as possible, ie.  after any option assignments from the
1978   command-line or from other commands have been done.  Thus, this is the place
1979   to to code option dependencies: if *foo* depends on *bar*, then it is safe to
1980   set *foo* from *bar* as long as *foo* still has the same value it was
1981   assigned in :meth:`initialize_options`.
1982
1983
1984.. method:: Command.run()
1985
1986   A command's raison d'etre: carry out the action it exists to perform, controlled
1987   by the options initialized in :meth:`initialize_options`, customized by other
1988   commands, the setup script, the command-line, and config files, and finalized in
1989   :meth:`finalize_options`.  All terminal output and filesystem interaction should
1990   be done by :meth:`run`.
1991
1992*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
1993as the parent with sub-commands ``install_lib``, ``install_headers``, etc.  The
1994parent of a family of commands defines *sub_commands* as a class attribute; it's
1995a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
1996and *predicate* an unbound method, a string or None. *predicate* is a method of
1997the parent command that determines whether the corresponding command is
1998applicable in the current situation.  (Eg. we ``install_headers`` is only
1999applicable if we have any C header files to install.)  If *predicate* is None,
2000that command is always applicable.
2001
2002*sub_commands* is usually defined at the \*end\* of a class, because predicates
2003can be unbound methods, so they must already have been defined.  The canonical
2004example is the :command:`install` command.