1 .. _api-reference:

     2 

     3 *************

     4 API 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 

    15 The :mod:`distutils.core` module is the only module that needs to be installed

    16 to use the Distutils. It provides the :func:`setup` (which is called from the

    17 setup 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    |                                                             |

    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 

   102 

   103 .. function:: run_setup(script_name[, script_args=None, stop_after='run'])

   104 

   105    Run a setup script in a somewhat controlled environment, and return  the

   106    :class:`distutils.dist.Distribution` instance that drives things.   This is

   107    useful if you need to find out the distribution meta-data  (passed as keyword

   108    args from *script* to :func:`setup`), or  the contents of the config files or

   109    command-line.

   110 

   111    *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``

   112    will be replaced with *script* for the duration of the call.  *script_args* is a

   113    list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*

   114    for the duration  of the call.

   115 

   116    *stop_after* tells :func:`setup` when to stop processing; possible  values:

   117 

   118    +---------------+---------------------------------------------+

   119    | value         | description                                 |

   120    +===============+=============================================+

   121    | *init*        | Stop after the :class:`Distribution`        |

   122    |               | instance has been created  and populated    |

   123    |               | with the keyword arguments to :func:`setup` |

   124    +---------------+---------------------------------------------+

   125    | *config*      | Stop after config files have been parsed    |

   126    |               | (and their data stored in the               |

   127    |               | :class:`Distribution` instance)             |

   128    +---------------+---------------------------------------------+

   129    | *commandline* | Stop after the command-line                 |

   130    |               | (``sys.argv[1:]`` or  *script_args*) have   |

   131    |               | been parsed (and the data stored in the     |

   132    |               | :class:`Distribution` instance.)            |

   133    +---------------+---------------------------------------------+

   134    | *run*         | Stop after all commands have been run (the  |

   135    |               | same as  if :func:`setup` had been called   |

   136    |               | in the usual way). This is the default      |

   137    |               | value.                                      |

   138    +---------------+---------------------------------------------+

   139 

   140 In addition, the :mod:`distutils.core` module exposed a number of  classes that

   141 live elsewhere.

   142 

   143 * :class:`Extension` from :mod:`distutils.extension`

   144 

   145 * :class:`Command` from :mod:`distutils.cmd`

   146 

   147 * :class:`Distribution` from :mod:`distutils.dist`

   148 

   149 A short description of each of these follows, but see the relevant module for

   150 the full reference.

   151 

   152 

   153 .. class:: Extension

   154 

   155    The Extension class describes a single C or C++extension module in a setup

   156    script. It accepts the following keyword arguments in its constructor

   157 

   158    +------------------------+--------------------------------+---------------------------+

   159    | argument name          | value                          | type                      |

   160    +========================+================================+===========================+

   161    | *name*                 | the full name of the           | string                    |

   162    |                        | extension, including any       |                           |

   163    |                        | packages --- ie. *not* a       |                           |

   164    |                        | filename or pathname, but      |                           |

   165    |                        | Python dotted name             |                           |

   166    +------------------------+--------------------------------+---------------------------+

   167    | *sources*              | list of source filenames,      | string                    |

   168    |                        | relative to the distribution   |                           |

   169    |                        | root (where the setup script   |                           |

   170    |                        | lives), in Unix form (slash-   |                           |

   171    |                        | separated) for portability.    |                           |

   172    |                        | Source files may be C, C++,    |                           |

   173    |                        | SWIG (.i), platform-specific   |                           |

   174    |                        | resource files, or whatever    |                           |

   175    |                        | else is recognized by the      |                           |

   176    |                        | :command:`build_ext` command   |                           |

   177    |                        | as source for a Python         |                           |

   178    |                        | extension.                     |                           |

   179    +------------------------+--------------------------------+---------------------------+

   180    | *include_dirs*         | list of directories to search  | string                    |

   181    |                        | for C/C++ header files (in     |                           |

   182    |                        | Unix form for portability)     |                           |

   183    +------------------------+--------------------------------+---------------------------+

   184    | *define_macros*        | list of macros to define; each | (string,string)  tuple or |

   185    |                        | macro is defined using a       | (name,``None``)           |

   186    |                        | 2-tuple, where 'value' is      |                           |

   187    |                        | either the string to define it |                           |

   188    |                        | to or ``None`` to define it    |                           |

   189    |                        | without a particular value     |                           |

   190    |                        | (equivalent of ``#define FOO`` |                           |

   191    |                        | in source or :option:`-DFOO`   |                           |

   192    |                        | on Unix C compiler command     |                           |

   193    |                        | line)                          |                           |

   194    +------------------------+--------------------------------+---------------------------+

   195    | *undef_macros*         | list of macros to undefine     | string                    |

   196    |                        | explicitly                     |                           |

   197    +------------------------+--------------------------------+---------------------------+

   198    | *library_dirs*         | list of directories to search  | string                    |

   199    |                        | for C/C++ libraries at link    |                           |

   200    |                        | time                           |                           |

   201    +------------------------+--------------------------------+---------------------------+

   202    | *libraries*            | list of library names (not     | string                    |

   203    |                        | filenames or paths) to link    |                           |

   204    |                        | against                        |                           |

   205    +------------------------+--------------------------------+---------------------------+

   206    | *runtime_library_dirs* | list of directories to search  | string                    |

   207    |                        | for C/C++ libraries at run     |                           |

   208    |                        | time (for shared extensions,   |                           |

   209    |                        | this is when the extension is  |                           |

   210    |                        | loaded)                        |                           |

   211    +------------------------+--------------------------------+---------------------------+

   212    | *extra_objects*        | list of extra files to link    | string                    |

   213    |                        | with (eg. object files not     |                           |

   214    |                        | implied by 'sources', static   |                           |

   215    |                        | library that must be           |                           |

   216    |                        | explicitly specified, binary   |                           |

   217    |                        | resource files, etc.)          |                           |

   218    +------------------------+--------------------------------+---------------------------+

   219    | *extra_compile_args*   | any extra platform- and        | string                    |

   220    |                        | compiler-specific information  |                           |

   221    |                        | to use when compiling the      |                           |

   222    |                        | source files in 'sources'. For |                           |

   223    |                        | platforms and compilers where  |                           |

   224    |                        | a command line makes sense,    |                           |

   225    |                        | this is typically a list of    |                           |

   226    |                        | command-line arguments, but    |                           |

   227    |                        | for other platforms it could   |                           |

   228    |                        | be anything.                   |                           |

   229    +------------------------+--------------------------------+---------------------------+

   230    | *extra_link_args*      | any extra platform- and        | string                    |

   231    |                        | compiler-specific information  |                           |

   232    |                        | to use when linking object     |                           |

   233    |                        | files together to create the   |                           |

   234    |                        | extension (or to create a new  |                           |

   235    |                        | static Python interpreter).    |                           |

   236    |                        | Similar interpretation as for  |                           |

   237    |                        | 'extra_compile_args'.          |                           |

   238    +------------------------+--------------------------------+---------------------------+

   239    | *export_symbols*       | list of symbols to be exported | string                    |

   240    |                        | from a shared extension. Not   |                           |

   241    |                        | used on all platforms, and not |                           |

   242    |                        | generally necessary for Python |                           |

   243    |                        | extensions, which typically    |                           |

   244    |                        | export exactly one symbol:     |                           |

   245    |                        | ``init`` + extension_name.     |                           |

   246    +------------------------+--------------------------------+---------------------------+

   247    | *depends*              | list of files that the         | string                    |

   248    |                        | extension depends on           |                           |

   249    +------------------------+--------------------------------+---------------------------+

   250    | *language*             | extension language (i.e.       | string                    |

   251    |                        | ``'c'``, ``'c++'``,            |                           |

   252    |                        | ``'objc'``). Will be detected  |                           |

   253    |                        | from the source extensions if  |                           |

   254    |                        | not provided.                  |                           |

   255    +------------------------+--------------------------------+---------------------------+

   256 

   257 

   258 .. class:: Distribution

   259 

   260    A :class:`Distribution` describes how to build, install and package up a Python

   261    software package.

   262 

   263    See the :func:`setup` function for a list of keyword arguments accepted  by the

   264    Distribution constructor. :func:`setup` creates a Distribution instance.

   265 

   266 

   267 .. class:: Command

   268 

   269    A :class:`Command` class (or rather, an instance of one of its subclasses)

   270    implement a single distutils command.

   271 

   272 

   273 :mod:`distutils.ccompiler` --- CCompiler base class

   274 ===================================================

   275 

   276 .. module:: distutils.ccompiler

   277    :synopsis: Abstract CCompiler class

   278 

   279 

   280 This module provides the abstract base class for the :class:`CCompiler`

   281 classes.  A :class:`CCompiler` instance can be used for all the compile  and

   282 link steps needed to build a single project. Methods are provided to  set

   283 options for the compiler --- macro definitions, include directories,  link path,

   284 libraries and the like.

   285 

   286 This module provides the following functions.

   287 

   288 

   289 .. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

   290 

   291    Generate linker options for searching library directories and linking with

   292    specific libraries.  *libraries* and *library_dirs* are, respectively, lists of

   293    library names (not filenames!) and search directories.  Returns a list of

   294    command-line options suitable for use with some compiler (depending on the two

   295    format strings passed in).

   296 

   297 

   298 .. function:: gen_preprocess_options(macros, include_dirs)

   299 

   300    Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as

   301    used by at least two types of compilers: the typical Unix compiler and Visual

   302    C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``

   303    means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define

   304    (:option:`-D`) macro *name* to *value*.  *include_dirs* is just a list of

   305    directory names to be added to the header file search path (:option:`-I`).

   306    Returns a list of command-line options suitable for either Unix compilers or

   307    Visual C++.

   308 

   309 

   310 .. function:: get_default_compiler(osname, platform)

   311 

   312    Determine the default compiler to use for the given platform.

   313 

   314    *osname* should be one of the standard Python OS names (i.e. the ones returned

   315    by ``os.name``) and *platform* the common value returned by ``sys.platform`` for

   316    the platform in question.

   317 

   318    The default values are ``os.name`` and ``sys.platform`` in case the parameters

   319    are not given.

   320 

   321 

   322 .. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)

   323 

   324    Factory function to generate an instance of some CCompiler subclass for the

   325    supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.

   326    ``'posix'``, ``'nt'``), and *compiler*  defaults to the default compiler for

   327    that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the

   328    default compilers are "traditional Unix interface" (:class:`UnixCCompiler`

   329    class) and Visual C++ (:class:`MSVCCompiler` class).  Note that it's perfectly

   330    possible to ask for a Unix compiler object under Windows, and a Microsoft

   331    compiler object under Unix---if you supply a value for *compiler*, *plat* is

   332    ignored.

   333 

   334    .. % Is the posix/nt only thing still true? Mac OS X seems to work, and

   335    .. % returns a UnixCCompiler instance. How to document this... hmm.

   336 

   337 

   338 .. function:: show_compilers()

   339 

   340    Print list of available compilers (used by the :option:`--help-compiler` options

   341    to :command:`build`, :command:`build_ext`, :command:`build_clib`).

   342 

   343 

   344 .. class:: CCompiler([verbose=0, dry_run=0, force=0])

   345 

   346    The abstract base class :class:`CCompiler` defines the interface that  must be

   347    implemented by real compiler classes.  The class also has  some utility methods

   348    used by several compiler classes.

   349 

   350    The basic idea behind a compiler abstraction class is that each instance can be

   351    used for all the compile/link steps in building a single project.  Thus,

   352    attributes common to all of those compile and link steps --- include

   353    directories, macros to define, libraries to link against, etc. --- are

   354    attributes of the compiler instance.  To allow for variability in how individual

   355    files are treated, most of those attributes may be varied on a per-compilation

   356    or per-link basis.

   357 

   358    The constructor for each subclass creates an instance of the Compiler object.

   359    Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the

   360    steps) and *force* (rebuild everything, regardless of dependencies). All of

   361    these flags default to ``0`` (off). Note that you probably don't want to

   362    instantiate :class:`CCompiler` or one of its subclasses directly - use the

   363    :func:`distutils.CCompiler.new_compiler` factory function instead.

   364 

   365    The following methods allow you to manually alter compiler options for  the

   366    instance of the Compiler class.

   367 

   368 

   369    .. method:: CCompiler.add_include_dir(dir)

   370 

   371       Add *dir* to the list of directories that will be searched for header files.

   372       The compiler is instructed to search directories in the order in which they are

   373       supplied by successive calls to :meth:`add_include_dir`.

   374 

   375 

   376    .. method:: CCompiler.set_include_dirs(dirs)

   377 

   378       Set the list of directories that will be searched to *dirs* (a list of strings).

   379       Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to

   380       :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.

   381       This does not affect any list of standard include directories that the compiler

   382       may search by default.

   383 

   384 

   385    .. method:: CCompiler.add_library(libname)

   386 

   387       Add *libname* to the list of libraries that will be included in all links driven

   388       by this compiler object.  Note that *libname* should \*not\* be the name of a

   389       file containing a library, but the name of the library itself: the actual

   390       filename will be inferred by the linker, the compiler, or the compiler class

   391       (depending on the platform).

   392 

   393       The linker will be instructed to link against libraries in the order they were

   394       supplied to :meth:`add_library` and/or :meth:`set_libraries`.  It is perfectly

   395       valid to duplicate library names; the linker will be instructed to link against

   396       libraries as many times as they are mentioned.

   397 

   398 

   399    .. method:: CCompiler.set_libraries(libnames)

   400 

   401       Set the list of libraries to be included in all links driven by this compiler

   402       object to *libnames* (a list of strings).  This does not affect any standard

   403       system libraries that the linker may include by default.

   404 

   405 

   406    .. method:: CCompiler.add_library_dir(dir)

   407 

   408       Add *dir* to the list of directories that will be searched for libraries

   409       specified to :meth:`add_library` and :meth:`set_libraries`.  The linker will be

   410       instructed to search for libraries in the order they are supplied to

   411       :meth:`add_library_dir` and/or :meth:`set_library_dirs`.

   412 

   413 

   414    .. method:: CCompiler.set_library_dirs(dirs)

   415 

   416       Set the list of library search directories to *dirs* (a list of strings).  This

   417       does not affect any standard library search path that the linker may search by

   418       default.

   419 

   420 

   421    .. method:: CCompiler.add_runtime_library_dir(dir)

   422 

   423       Add *dir* to the list of directories that will be searched for shared libraries

   424       at runtime.

   425 

   426 

   427    .. method:: CCompiler.set_runtime_library_dirs(dirs)

   428 

   429       Set the list of directories to search for shared libraries at runtime to *dirs*

   430       (a list of strings).  This does not affect any standard search path that the

   431       runtime linker may search by default.

   432 

   433 

   434    .. method:: CCompiler.define_macro(name[, value=None])

   435 

   436       Define a preprocessor macro for all compilations driven by this compiler object.

   437       The optional parameter *value* should be a string; if it is not supplied, then

   438       the macro will be defined without an explicit value and the exact outcome

   439       depends on the compiler used (XXX true? does ANSI say anything about this?)

   440 

   441 

   442    .. method:: CCompiler.undefine_macro(name)

   443 

   444       Undefine a preprocessor macro for all compilations driven by this compiler

   445       object.  If the same macro is defined by :meth:`define_macro` and

   446       undefined by :meth:`undefine_macro` the last call takes precedence

   447       (including multiple redefinitions or undefinitions).  If the macro is

   448       redefined/undefined on a per-compilation basis (ie. in the call to

   449       :meth:`compile`), then that takes precedence.

   450 

   451 

   452    .. method:: CCompiler.add_link_object(object)

   453 

   454       Add *object* to the list of object files (or analogues, such as explicitly named

   455       library files or the output of "resource compilers") to be included in every

   456       link driven by this compiler object.

   457 

   458 

   459    .. method:: CCompiler.set_link_objects(objects)

   460 

   461       Set the list of object files (or analogues) to be included in every link to

   462       *objects*.  This does not affect any standard object files that the linker may

   463       include by default (such as system libraries).

   464 

   465    The following methods implement methods for autodetection of compiler  options,

   466    providing some functionality similar to GNU :program:`autoconf`.

   467 

   468 

   469    .. method:: CCompiler.detect_language(sources)

   470 

   471       Detect the language of a given file, or list of files. Uses the  instance

   472       attributes :attr:`language_map` (a dictionary), and  :attr:`language_order` (a

   473       list) to do the job.

   474 

   475 

   476    .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])

   477 

   478       Search the specified list of directories for a static or shared library file

   479       *lib* and return the full path to that file.  If *debug* is true, look for a

   480       debugging version (if that makes sense on the current platform).  Return

   481       ``None`` if *lib* wasn't found in any of the specified directories.

   482 

   483 

   484    .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])

   485 

   486       Return a boolean indicating whether *funcname* is supported on the current

   487       platform.  The optional arguments can be used to augment the compilation

   488       environment by providing additional include files and paths and libraries and

   489       paths.

   490 

   491 

   492    .. method:: CCompiler.library_dir_option(dir)

   493 

   494       Return the compiler option to add *dir* to the list of directories searched for

   495       libraries.

   496 

   497 

   498    .. method:: CCompiler.library_option(lib)

   499 

   500       Return the compiler option to add *dir* to the list of libraries linked into the

   501       shared library or executable.

   502 

   503 

   504    .. method:: CCompiler.runtime_library_dir_option(dir)

   505 

   506       Return the compiler option to add *dir* to the list of directories searched for

   507       runtime libraries.

   508 

   509 

   510    .. method:: CCompiler.set_executables(**args)

   511 

   512       Define the executables (and options for them) that will be run to perform the

   513       various stages of compilation.  The exact set of executables that may be

   514       specified here depends on the compiler class (via the 'executables' class

   515       attribute), but most will have:

   516 

   517       +--------------+------------------------------------------+

   518       | attribute    | description                              |

   519       +==============+==========================================+

   520       | *compiler*   | the C/C++ compiler                       |

   521       +--------------+------------------------------------------+

   522       | *linker_so*  | linker used to create shared objects and |

   523       |              | libraries                                |

   524       +--------------+------------------------------------------+

   525       | *linker_exe* | linker used to create binary executables |

   526       +--------------+------------------------------------------+

   527       | *archiver*   | static library creator                   |

   528       +--------------+------------------------------------------+

   529 

   530       On platforms with a command-line (Unix, DOS/Windows), each of these is a string

   531       that will be split into executable name and (optional) list of arguments.

   532       (Splitting the string is done similarly to how Unix shells operate: words are

   533       delimited by spaces, but quotes and backslashes can override this.  See

   534       :func:`distutils.util.split_quoted`.)

   535 

   536    The following methods invoke stages in the build process.

   537 

   538 

   539    .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

   540 

   541       Compile one or more source files. Generates object files (e.g.  transforms a

   542       :file:`.c` file to a :file:`.o` file.)

   543 

   544       *sources* must be a list of filenames, most likely C/C++ files, but in reality

   545       anything that can be handled by a particular compiler and compiler class (eg.

   546       :class:`MSVCCompiler` can handle resource files in *sources*).  Return a list of

   547       object filenames, one per source filename in *sources*.  Depending on the

   548       implementation, not all source files will necessarily be compiled, but all

   549       corresponding object filenames will be returned.

   550 

   551       If *output_dir* is given, object files will be put under it, while retaining

   552       their original path component.  That is, :file:`foo/bar.c` normally compiles to

   553       :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then

   554       it would compile to :file:`build/foo/bar.o`.

   555 

   556       *macros*, if given, must be a list of macro definitions.  A macro definition is

   557       either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines

   558       a macro; if the value is ``None``, the macro is defined without an explicit

   559       value.  The 1-tuple case undefines a macro.  Later

   560       definitions/redefinitions/undefinitions take precedence.

   561 

   562       *include_dirs*, if given, must be a list of strings, the directories to add to

   563       the default include file search path for this compilation only.

   564 

   565       *debug* is a boolean; if true, the compiler will be instructed to output debug

   566       symbols in (or alongside) the object file(s).

   567 

   568       *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms

   569       that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most

   570       likely lists of strings: extra command-line arguments to prepend/append to the

   571       compiler command line.  On other platforms, consult the implementation class

   572       documentation.  In any event, they are intended as an escape hatch for those

   573       occasions when the abstract compiler framework doesn't cut the mustard.

   574 

   575       *depends*, if given, is a list of filenames that all targets depend on.  If a

   576       source file is older than any file in depends, then the source file will be

   577       recompiled.  This supports dependency tracking, but only at a coarse

   578       granularity.

   579 

   580       Raises :exc:`CompileError` on failure.

   581 

   582 

   583    .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])

   584 

   585       Link a bunch of stuff together to create a static library file. The "bunch of

   586       stuff" consists of the list of object files supplied as *objects*, the extra

   587       object files supplied to :meth:`add_link_object` and/or

   588       :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or

   589       :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).

   590 

   591       *output_libname* should be a library name, not a filename; the filename will be

   592       inferred from the library name.  *output_dir* is the directory where the library

   593       file will be put. XXX defaults to what?

   594 

   595       *debug* is a boolean; if true, debugging information will be included in the

   596       library (note that on most platforms, it is the compile step where this matters:

   597       the *debug* flag is included here just for consistency).

   598 

   599       *target_lang* is the target language for which the given objects are being

   600       compiled. This allows specific linkage time treatment of certain languages.

   601 

   602       Raises :exc:`LibError` on failure.

   603 

   604 

   605    .. 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])

   606 

   607       Link a bunch of stuff together to create an executable or shared library file.

   608 

   609       The "bunch of stuff" consists of the list of object files supplied as *objects*.

   610       *output_filename* should be a filename.  If *output_dir* is supplied,

   611       *output_filename* is relative to it (i.e. *output_filename* can provide

   612       directory components if needed).

   613 

   614       *libraries* is a list of libraries to link against.  These are library names,

   615       not filenames, since they're translated into filenames in a platform-specific

   616       way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on

   617       DOS/Windows).  However, they can include a directory component, which means the

   618       linker will look in that specific directory rather than searching all the normal

   619       locations.

   620 

   621       *library_dirs*, if supplied, should be a list of directories to search for

   622       libraries that were specified as bare library names (ie. no directory

   623       component).  These are on top of the system default and those supplied to

   624       :meth:`add_library_dir` and/or :meth:`set_library_dirs`.  *runtime_library_dirs*

   625       is a list of directories that will be embedded into the shared library and used

   626       to search for other shared libraries that \*it\* depends on at run-time.  (This

   627       may only be relevant on Unix.)

   628 

   629       *export_symbols* is a list of symbols that the shared library will export.

   630       (This appears to be relevant only on Windows.)

   631 

   632       *debug* is as for :meth:`compile` and :meth:`create_static_lib`,  with the

   633       slight distinction that it actually matters on most platforms (as opposed to

   634       :meth:`create_static_lib`, which includes a *debug* flag mostly for form's

   635       sake).

   636 

   637       *extra_preargs* and *extra_postargs* are as for :meth:`compile`  (except of

   638       course that they supply command-line arguments for the particular linker being

   639       used).

   640 

   641       *target_lang* is the target language for which the given objects are being

   642       compiled. This allows specific linkage time treatment of certain languages.

   643 

   644       Raises :exc:`LinkError` on failure.

   645 

   646 

   647    .. 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])

   648 

   649       Link an executable.  *output_progname* is the name of the file executable, while

   650       *objects* are a list of object filenames to link in. Other arguments  are as for

   651       the :meth:`link` method.

   652 

   653 

   654    .. 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])

   655 

   656       Link a shared library. *output_libname* is the name of the output  library,

   657       while *objects* is a list of object filenames to link in.  Other arguments are

   658       as for the :meth:`link` method.

   659 

   660 

   661    .. 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])

   662 

   663       Link a shared object. *output_filename* is the name of the shared object that

   664       will be created, while *objects* is a list of object filenames  to link in.

   665       Other arguments are as for the :meth:`link` method.

   666 

   667 

   668    .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])

   669 

   670       Preprocess a single C/C++ source file, named in *source*. Output will be written

   671       to file named *output_file*, or *stdout* if *output_file* not supplied.

   672       *macros* is a list of macro definitions as for :meth:`compile`, which will

   673       augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.

   674       *include_dirs* is a list of directory names that will be added to the  default

   675       list, in the same way as :meth:`add_include_dir`.

   676 

   677       Raises :exc:`PreprocessError` on failure.

   678 

   679    The following utility methods are defined by the :class:`CCompiler` class, for

   680    use by the various concrete subclasses.

   681 

   682 

   683    .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])

   684 

   685       Returns the filename of the executable for the given *basename*.  Typically for

   686       non-Windows platforms this is the same as the basename,  while Windows will get

   687       a :file:`.exe` added.

   688 

   689 

   690    .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])

   691 

   692       Returns the filename for the given library name on the current platform. On Unix

   693       a library with *lib_type* of ``'static'`` will typically  be of the form

   694       :file:`liblibname.a`, while a *lib_type* of ``'dynamic'``  will be of the form

   695       :file:`liblibname.so`.

   696 

   697 

   698    .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])

   699 

   700       Returns the name of the object files for the given source files.

   701       *source_filenames* should be a list of filenames.

   702 

   703 

   704    .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])

   705 

   706       Returns the name of a shared object file for the given file name *basename*.

   707 

   708 

   709    .. method:: CCompiler.execute(func, args[, msg=None, level=1])

   710 

   711       Invokes :func:`distutils.util.execute` This method invokes a  Python function

   712       *func* with the given arguments *args*, after  logging and taking into account

   713       the *dry_run* flag. XXX see also.

   714 

   715 

   716    .. method:: CCompiler.spawn(cmd)

   717 

   718       Invokes :func:`distutils.util.spawn`. This invokes an external  process to run

   719       the given command. XXX see also.

   720 

   721 

   722    .. method:: CCompiler.mkpath(name[, mode=511])

   723 

   724       Invokes :func:`distutils.dir_util.mkpath`. This creates a directory  and any

   725       missing ancestor directories. XXX see also.

   726 

   727 

   728    .. method:: CCompiler.move_file(src, dst)

   729 

   730       Invokes :meth:`distutils.file_util.move_file`. Renames *src* to  *dst*.  XXX see

   731       also.

   732 

   733 

   734    .. method:: CCompiler.announce(msg[, level=1])

   735 

   736       Write a message using :func:`distutils.log.debug`. XXX see also.

   737 

   738 

   739    .. method:: CCompiler.warn(msg)

   740 

   741       Write a warning message *msg* to standard error.

   742 

   743 

   744    .. method:: CCompiler.debug_print(msg)

   745 

   746       If the *debug* flag is set on this :class:`CCompiler` instance, print  *msg* to

   747       standard output, otherwise do nothing.

   748 

   749 .. % \subsection{Compiler-specific modules}

   750 .. % 

   751 .. % The following modules implement concrete subclasses of the abstract

   752 .. % \class{CCompiler} class. They should not be instantiated directly, but should

   753 .. % be created using \function{distutils.ccompiler.new_compiler()} factory

   754 .. % function.

   755 

   756 

   757 :mod:`distutils.unixccompiler` --- Unix C Compiler

   758 ==================================================

   759 

   760 .. module:: distutils.unixccompiler

   761    :synopsis: UNIX C Compiler

   762 

   763 

   764 This module provides the :class:`UnixCCompiler` class, a subclass of

   765 :class:`CCompiler` that handles the typical Unix-style command-line  C compiler:

   766 

   767 * macros defined with :option:`-Dname[=value]`

   768 

   769 * macros undefined with :option:`-Uname`

   770 

   771 * include search directories specified with :option:`-Idir`

   772 

   773 * libraries specified with :option:`-llib`

   774 

   775 * library search directories specified with :option:`-Ldir`

   776 

   777 * compile handled by :program:`cc` (or similar) executable with :option:`-c`

   778   option: compiles :file:`.c` to :file:`.o`

   779 

   780 * link static library handled by :program:`ar` command (possibly with

   781   :program:`ranlib`)

   782 

   783 * link shared library handled by :program:`cc` :option:`-shared`

   784 

   785 

   786 :mod:`distutils.msvccompiler` --- Microsoft Compiler

   787 ====================================================

   788 

   789 .. module:: distutils.msvccompiler

   790    :synopsis: Microsoft Compiler

   791 

   792 

   793 This module provides :class:`MSVCCompiler`, an implementation of the abstract

   794 :class:`CCompiler` class for Microsoft Visual Studio. Typically, extension

   795 modules need to be compiled with the same compiler that was used to compile

   796 Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python

   797 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium

   798 binaries are created using the Platform SDK.

   799 

   800 :class:`MSVCCompiler` will normally choose the right compiler, linker etc. on

   801 its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*

   802 and *MSSdk* must be both set. *MSSdk* indicates that the current environment has

   803 been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables

   804 had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates

   805 that the distutils user has made an explicit choice to override the compiler

   806 selection by :class:`MSVCCompiler`.

   807 

   808 

   809 :mod:`distutils.bcppcompiler` --- Borland Compiler

   810 ==================================================

   811 

   812 .. module:: distutils.bcppcompiler

   813 

   814 

   815 This module provides :class:`BorlandCCompiler`, an subclass of the abstract

   816 :class:`CCompiler` class for the Borland C++ compiler.

   817 

   818 

   819 :mod:`distutils.cygwincompiler` --- Cygwin Compiler

   820 ===================================================

   821 

   822 .. module:: distutils.cygwinccompiler

   823 

   824 

   825 This module provides the :class:`CygwinCCompiler` class, a subclass of

   826 :class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to

   827 Windows.  It also contains the Mingw32CCompiler class which handles the mingw32

   828 port of GCC (same as cygwin in no-cygwin mode).

   829 

   830 

   831 :mod:`distutils.emxccompiler` --- OS/2 EMX Compiler

   832 ===================================================

   833 

   834 .. module:: distutils.emxccompiler

   835    :synopsis: OS/2 EMX Compiler support

   836 

   837 

   838 This module provides the EMXCCompiler class, a subclass of

   839 :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.

   840 

   841 

   842 :mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support

   843 ==================================================================

   844 

   845 .. module:: distutils.mwerkscompiler

   846    :synopsis: Metrowerks CodeWarrior support

   847 

   848 

   849 Contains :class:`MWerksCompiler`, an implementation of the abstract

   850 :class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X

   851 Macintosh. Needs work to support CW on Windows or Mac OS X.

   852 

   853 .. % \subsection{Utility modules}

   854 .. % 

   855 .. % The following modules all provide general utility functions. They haven't

   856 .. % all been documented yet.

   857 

   858 

   859 :mod:`distutils.archive_util` ---  Archiving utilities

   860 ======================================================

   861 

   862 .. module:: distutils.archive_util

   863    :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)

   864 

   865 

   866 This module provides a few functions for creating archive files, such as

   867 tarballs or zipfiles.

   868 

   869 

   870 .. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

   871 

   872    Create an archive file (eg. ``zip`` or ``tar``).  *base_name*  is the name of

   873    the file to create, minus any format-specific extension;  *format* is the

   874    archive format: one of ``zip``, ``tar``,  ``ztar``, or ``gztar``. *root_dir* is

   875    a directory that will be the root directory of the archive; ie. we typically

   876    ``chdir`` into *root_dir* before  creating the archive.  *base_dir* is the

   877    directory where we start  archiving from; ie. *base_dir* will be the common

   878    prefix of all files and directories in the archive.  *root_dir* and *base_dir*

   879    both default to the current directory.  Returns the name of the archive file.

   880 

   881    .. warning::

   882 

   883       This should be changed to support bz2 files

   884 

   885 

   886 .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

   887 

   888    'Create an (optional compressed) archive as a tar file from all files in and

   889    under *base_dir*. *compress* must be ``'gzip'`` (the default),  ``'compress'``,

   890    ``'bzip2'``, or ``None``.  Both :program:`tar` and the compression utility named

   891    by *compress* must be on the  default program search path, so this is probably

   892    Unix-specific.  The  output tar file will be named :file:`base_dir.tar`,

   893    possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`

   894    or :file:`.Z`).  Return the output filename.

   895 

   896    .. warning::

   897 

   898       This should be replaced with calls to the :mod:`tarfile` module.

   899 

   900 

   901 .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

   902 

   903    Create a zip file from all files in and under *base_dir*.  The output zip file

   904    will be named *base_dir* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python

   905    module (if available) or the InfoZIP :file:`zip`  utility (if installed and

   906    found on the default search path).  If neither  tool is available, raises

   907    :exc:`DistutilsExecError`.   Returns the name of the output zip file.

   908 

   909 

   910 :mod:`distutils.dep_util` --- Dependency checking

   911 =================================================

   912 

   913 .. module:: distutils.dep_util

   914    :synopsis: Utility functions for simple dependency checking

   915 

   916 

   917 This module provides functions for performing simple, timestamp-based

   918 dependency of files and groups of files; also, functions based entirely  on such

   919 timestamp dependency analysis.

   920 

   921 

   922 .. function:: newer(source, target)

   923 

   924    Return true if *source* exists and is more recently modified than *target*, or

   925    if *source* exists and *target* doesn't. Return false if both exist and *target*

   926    is the same age or newer  than *source*. Raise :exc:`DistutilsFileError` if

   927    *source* does not exist.

   928 

   929 

   930 .. function:: newer_pairwise(sources, targets)

   931 

   932    Walk two filename lists in parallel, testing if each source is newer than its

   933    corresponding target.  Return a pair of lists (*sources*, *targets*) where

   934    source is newer than target, according to the semantics of :func:`newer`

   935 

   936    .. % % equivalent to a listcomp...

   937 

   938 

   939 .. function:: newer_group(sources, target[, missing='error'])

   940 

   941    Return true if *target* is out-of-date with respect to any file listed in

   942    *sources*  In other words, if *target* exists and is newer than every file in

   943    *sources*, return false; otherwise return true. *missing* controls what we do

   944    when a source file is missing; the default (``'error'``) is to blow up with an

   945    :exc:`OSError` from  inside :func:`os.stat`; if it is ``'ignore'``, we silently

   946    drop any missing source files; if it is ``'newer'``, any missing source files

   947    make us assume that *target* is out-of-date (this is handy in "dry-run" mode:

   948    it'll make you pretend to carry out commands that wouldn't work because inputs

   949    are missing, but that doesn't matter because you're not actually going to run

   950    the commands).

   951 

   952 

   953 :mod:`distutils.dir_util` --- Directory tree operations

   954 =======================================================

   955 

   956 .. module:: distutils.dir_util

   957    :synopsis: Utility functions for operating on directories and directory trees

   958 

   959 

   960 This module provides functions for operating on directories and trees of

   961 directories.

   962 

   963 

   964 .. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0])

   965 

   966    Create a directory and any missing ancestor directories.  If the directory

   967    already exists (or if *name* is the empty string, which means the current

   968    directory, which of course exists), then do nothing.  Raise

   969    :exc:`DistutilsFileError` if unable to create some directory along the way (eg.

   970    some sub-path exists, but is a file rather than a directory).  If *verbose* is

   971    true, print a one-line summary of each mkdir to stdout.  Return the list of

   972    directories actually created.

   973 

   974 

   975 .. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0])

   976 

   977    Create all the empty directories under *base_dir* needed to put *files* there.

   978    *base_dir* is just the a name of a directory which doesn't necessarily exist

   979    yet; *files* is a list of filenames to be interpreted relative to *base_dir*.

   980    *base_dir* + the directory portion of every file in *files* will be created if

   981    it doesn't already exist.  *mode*, *verbose* and *dry_run* flags  are as for

   982    :func:`mkpath`.

   983 

   984 

   985 .. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

   986 

   987    Copy an entire directory tree *src* to a new location *dst*.  Both *src* and

   988    *dst* must be directory names.  If *src* is not a directory, raise

   989    :exc:`DistutilsFileError`.  If *dst* does  not exist, it is created with

   990    :func:`mkpath`.  The end result of the  copy is that every file in *src* is

   991    copied to *dst*, and  directories under *src* are recursively copied to *dst*.

   992    Return the list of files that were copied or might have been copied, using their

   993    output name. The return value is unaffected by *update* or *dry_run*: it is

   994    simply the list of all files under *src*, with the names changed to be under

   995    *dst*.

   996 

   997    *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in

   998    :mod:`distutils.file_util`; note that they only apply to regular files, not to

   999    directories.  If *preserve_symlinks* is true, symlinks will be copied as

  1000    symlinks (on platforms that support them!); otherwise (the default), the

  1001    destination of the symlink will be copied.  *update* and *verbose* are the same

  1002    as for :func:`copy_file`.

  1003 

  1004 

  1005 .. function:: remove_tree(directory[, verbose=0, dry_run=0])

  1006 

  1007    Recursively remove *directory* and all files and directories underneath it. Any

  1008    errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is

  1009    true).

  1010 

  1011 **\*\*** Some of this could be replaced with the shutil module? **\*\***

  1012 

  1013 

  1014 :mod:`distutils.file_util` --- Single file operations

  1015 =====================================================

  1016 

  1017 .. module:: distutils.file_util

  1018    :synopsis: Utility functions for operating on single files

  1019 

  1020 

  1021 This module contains some utility functions for operating on individual files.

  1022 

  1023 

  1024 .. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

  1025 

  1026    Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there

  1027    with the same name; otherwise, it must be a filename. (If the file exists, it

  1028    will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the

  1029    file's mode (type and permission bits, or whatever is analogous on the

  1030    current platform) is copied. If *preserve_times* is true (the default), the

  1031    last-modified and last-access times are copied as well. If *update* is true,

  1032    *src* will only be copied if *dst* does not exist, or if *dst* does exist but

  1033    is older than *src*.

  1034 

  1035    *link* allows you to make hard links (using :func:`os.link`) or symbolic links

  1036    (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or

  1037    ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*

  1038    on systems that don't support it: :func:`copy_file` doesn't check if hard or

  1039    symbolic linking is available.  It uses :func:`_copy_file_contents` to copy file

  1040    contents.

  1041 

  1042    Return a tuple ``(dest_name, copied)``: *dest_name* is the actual  name of the

  1043    output file, and *copied* is true if the file was copied  (or would have been

  1044    copied, if *dry_run* true).

  1045 

  1046    .. % XXX if the destination file already exists, we clobber it if

  1047    .. % copying, but blow up if linking.  Hmmm.  And I don't know what

  1048    .. % macostools.copyfile() does.  Should definitely be consistent, and

  1049    .. % should probably blow up if destination exists and we would be

  1050    .. % changing it (ie. it's not already a hard/soft link to src OR

  1051    .. % (not update) and (src newer than dst)).

  1052 

  1053 

  1054 .. function:: move_file(src, dst[, verbose, dry_run])

  1055 

  1056    Move file *src* to *dst*. If *dst* is a directory, the file will be moved into

  1057    it with the same name; otherwise, *src* is just renamed to *dst*.  Returns the

  1058    new full name of the file.

  1059 

  1060    .. warning::

  1061 

  1062       Handles cross-device moves on Unix using :func:`copy_file`.   What about other

  1063       systems???

  1064 

  1065 

  1066 .. function:: write_file(filename, contents)

  1067 

  1068    Create a file called *filename* and write *contents* (a sequence of strings

  1069    without line terminators) to it.

  1070 

  1071 

  1072 :mod:`distutils.util` --- Miscellaneous other utility functions

  1073 ===============================================================

  1074 

  1075 .. module:: distutils.util

  1076    :synopsis: Miscellaneous other utility functions

  1077 

  1078 

  1079 This module contains other assorted bits and pieces that don't fit into  any

  1080 other utility module.

  1081 

  1082 

  1083 .. function:: get_platform()

  1084 

  1085    Return a string that identifies the current platform.  This is used mainly to

  1086    distinguish platform-specific build directories and platform-specific built

  1087    distributions.  Typically includes the OS name and version and the architecture

  1088    (as supplied by 'os.uname()'), although the exact information included depends

  1089    on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only

  1090    runs on SGI hardware), but for Linux the kernel version isn't particularly

  1091    important.

  1092 

  1093    Examples of returned values:

  1094 

  1095    * ``linux-i586``

  1096    * ``linux-alpha``

  1097    * ``solaris-2.6-sun4u``

  1098    * ``irix-5.3``

  1099    * ``irix64-6.2``

  1100 

  1101    For non-POSIX platforms, currently just returns ``sys.platform``.

  1102 

  1103    .. % XXX isn't this also provided by some other non-distutils module?

  1104 

  1105 

  1106 .. function:: convert_path(pathname)

  1107 

  1108    Return 'pathname' as a name that will work on the native filesystem, i.e. split

  1109    it on '/' and put it back together again using the current directory separator.

  1110    Needed because filenames in the setup script are always supplied in Unix style,

  1111    and have to be converted to the local convention before we can actually use them

  1112    in the filesystem.  Raises :exc:`ValueError` on non-Unix-ish systems if

  1113    *pathname* either  starts or ends with a slash.

  1114 

  1115 

  1116 .. function:: change_root(new_root, pathname)

  1117 

  1118    Return *pathname* with *new_root* prepended.  If *pathname* is relative, this is

  1119    equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making

  1120    *pathname* relative and then joining the two, which is tricky on DOS/Windows.

  1121 

  1122 

  1123 .. function:: check_environ()

  1124 

  1125    Ensure that 'os.environ' has all the environment variables we guarantee that

  1126    users can use in config files, command-line options, etc.  Currently this

  1127    includes:

  1128 

  1129    * :envvar:`HOME` - user's home directory (Unix only)

  1130    * :envvar:`PLAT` - description of the current platform, including hardware and

  1131      OS (see :func:`get_platform`)

  1132 

  1133 

  1134 .. function:: subst_vars(s, local_vars)

  1135