.. _api-reference:

*************

API Reference

*************

:mod:`distutils.core` --- Core Distutils functionality

======================================================

.. module:: distutils.core

   :synopsis: The core Distutils functionality

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

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

setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and

:class:`distutils.cmd.Command` class.

.. function:: setup(arguments)

   The basic do-everything function that does most everything you could ever ask

   for from a Distutils method. See XXXXX

   The setup function takes a large number of arguments. These are laid out in the

   following table.

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | argument name      | value                          | type                                                        |

   +====================+================================+=============================================================+

   | *name*             | The name of the package        | a string                                                    |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *version*          | The version number of the      | See :mod:`distutils.version`                                |

   |                    | package                        |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *description*      | A single line describing the   | a string                                                    |

   |                    | package                        |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *long_description* | Longer description of the      | a string                                                    |

   |                    | package                        |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *author*           | The name of the package author | a string                                                    |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *author_email*     | The email address of the       | a string                                                    |

   |                    | package author                 |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *maintainer*       | The name of the current        | a string                                                    |

   |                    | maintainer, if different from  |                                                             |

   |                    | the author                     |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *maintainer_email* | The email address of the       |                                                             |

   |                    | current maintainer, if         |                                                             |

   |                    | different from the author      |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *url*              | A URL for the package          | a URL                                                       |

   |                    | (homepage)                     |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *download_url*     | A URL to download the package  | a URL                                                       |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *packages*         | A list of Python packages that | a list of strings                                           |

   |                    | distutils will manipulate      |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *py_modules*       | A list of Python modules that  | a list of strings                                           |

   |                    | distutils will manipulate      |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *scripts*          | A list of standalone script    | a list of strings                                           |

   |                    | files to be built and          |                                                             |

   |                    | installed                      |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *ext_modules*      | A list of Python extensions to | A list of  instances of                                     |

   |                    | be built                       | :class:`distutils.core.Extension`                           |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *classifiers*      | A list of categories for the   | The list of available                                       |

   |                    | package                        | categorizations is at                                       |

   |                    |                                | http://pypi.python.org/pypi?:action=list_classifiers.       |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *distclass*        | the :class:`Distribution`      | A subclass of                                               |

   |                    | class to use                   | :class:`distutils.core.Distribution`                        |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *script_name*      | The name of the setup.py       | a string                                                    |

   |                    | script - defaults to           |                                                             |

   |                    | ``sys.argv[0]``                |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *script_args*      | Arguments to supply to the     | a list of strings                                           |

   |                    | setup script                   |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *options*          | default options for the setup  | a string                                                    |

   |                    | script                         |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *license*          | The license for the package    |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *keywords*         | Descriptive meta-data. See     |                                                             |

   |                    | :pep:`314`                     |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *platforms*        |                                |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

   | *cmdclass*         | A mapping of command names to  | a dictionary                                                |

   |                    | :class:`Command` subclasses    |                                                             |

   +--------------------+--------------------------------+-------------------------------------------------------------+

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

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

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

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

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

   command-line.

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

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

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

   for the duration  of the call.

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

   +---------------+---------------------------------------------+

   | value         | description                                 |

   +===============+=============================================+

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

   |               | instance has been created  and populated    |

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

   +---------------+---------------------------------------------+

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

   |               | (and their data stored in the               |

   |               | :class:`Distribution` instance)             |

   +---------------+---------------------------------------------+

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

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

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

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

   +---------------+---------------------------------------------+

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

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

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

   |               | value.                                      |

   +---------------+---------------------------------------------+

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

live elsewhere.

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

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

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

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

the full reference.

.. class:: Extension

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

   script. It accepts the following keyword arguments in its constructor

   +------------------------+--------------------------------+---------------------------+

   | argument name          | value                          | type                      |

   +========================+================================+===========================+

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

   |                        | extension, including any       |                           |

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

   |                        | filename or pathname, but      |                           |

   |                        | Python dotted name             |                           |

   +------------------------+--------------------------------+---------------------------+

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

   |                        | relative to the distribution   |                           |

   |                        | root (where the setup script   |                           |

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

   |                        | separated) for portability.    |                           |

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

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

   |                        | resource files, or whatever    |                           |

   |                        | else is recognized by the      |                           |

   |                        | :command:`build_ext` command   |                           |

   |                        | as source for a Python         |                           |

   |                        | extension.                     |                           |

   +------------------------+--------------------------------+---------------------------+

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

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

   |                        | Unix form for portability)     |                           |

   +------------------------+--------------------------------+---------------------------+

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

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

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

   |                        | either the string to define it |                           |

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

   |                        | without a particular value     |                           |

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

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

   |                        | on Unix C compiler command     |                           |

   |                        | line)                          |                           |

   +------------------------+--------------------------------+---------------------------+

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

   |                        | explicitly                     |                           |

   +------------------------+--------------------------------+---------------------------+

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

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

   |                        | time                           |                           |

   +------------------------+--------------------------------+---------------------------+

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

   |                        | filenames or paths) to link    |                           |

   |                        | against                        |                           |

   +------------------------+--------------------------------+---------------------------+

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

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

   |                        | time (for shared extensions,   |                           |

   |                        | this is when the extension is  |                           |

   |                        | loaded)                        |                           |

   +------------------------+--------------------------------+---------------------------+

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

   |                        | with (eg. object files not     |                           |

   |                        | implied by 'sources', static   |                           |

   |                        | library that must be           |                           |

   |                        | explicitly specified, binary   |                           |

   |                        | resource files, etc.)          |                           |

   +------------------------+--------------------------------+---------------------------+

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

   |                        | compiler-specific information  |                           |

   |                        | to use when compiling the      |                           |

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

   |                        | platforms and compilers where  |                           |

   |                        | a command line makes sense,    |                           |

   |                        | this is typically a list of    |                           |

   |                        | command-line arguments, but    |                           |

   |                        | for other platforms it could   |                           |

   |                        | be anything.                   |                           |

   +------------------------+--------------------------------+---------------------------+

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

   |                        | compiler-specific information  |                           |

   |                        | to use when linking object     |                           |

   |                        | files together to create the   |                           |

   |                        | extension (or to create a new  |                           |

   |                        | static Python interpreter).    |                           |

   |                        | Similar interpretation as for  |                           |

   |                        | 'extra_compile_args'.          |                           |

   +------------------------+--------------------------------+---------------------------+

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

   |                        | from a shared extension. Not   |                           |

   |                        | used on all platforms, and not |                           |

   |                        | generally necessary for Python |                           |

   |                        | extensions, which typically    |                           |

   |                        | export exactly one symbol:     |                           |

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

   +------------------------+--------------------------------+---------------------------+

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

   |                        | extension depends on           |                           |

   +------------------------+--------------------------------+---------------------------+

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

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

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

   |                        | from the source extensions if  |                           |

   |                        | not provided.                  |                           |

   +------------------------+--------------------------------+---------------------------+

.. class:: Distribution

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

   software package.

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

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

.. class:: Command

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

   implement a single distutils command.

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

===================================================

.. module:: distutils.ccompiler

   :synopsis: Abstract CCompiler class

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

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

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

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

libraries and the like.

This module provides the following functions.

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

   Generate linker options for searching library directories and linking with

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

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

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

   format strings passed in).

.. function:: gen_preprocess_options(macros, include_dirs)

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

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

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

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

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

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

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

   Visual C++.

.. function:: get_default_compiler(osname, platform)

   Determine the default compiler to use for the given platform.

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

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

   the platform in question.

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

   are not given.

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

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

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

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

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

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

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

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

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

   ignored.

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

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

.. function:: show_compilers()

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

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

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

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

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

   used by several compiler classes.

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

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

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

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

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

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

   or per-link basis.

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

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

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

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

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

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

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

   instance of the Compiler class.

   .. method:: CCompiler.add_include_dir(dir)

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

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

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

   .. method:: CCompiler.set_include_dirs(dirs)

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

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

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

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

      may search by default.

   .. method:: CCompiler.add_library(libname)

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

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

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

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

      (depending on the platform).

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

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

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

      libraries as many times as they are mentioned.

   .. method:: CCompiler.set_libraries(libnames)

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

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

      system libraries that the linker may include by default.

   .. method:: CCompiler.add_library_dir(dir)

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

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

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

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

   .. method:: CCompiler.set_library_dirs(dirs)

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

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

      default.

   .. method:: CCompiler.add_runtime_library_dir(dir)

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

      at runtime.

   .. method:: CCompiler.set_runtime_library_dirs(dirs)

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

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

      runtime linker may search by default.

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

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

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

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

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

   .. method:: CCompiler.undefine_macro(name)

      Undefine a preprocessor macro for all compilations driven by this compiler

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

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

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

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

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

   .. method:: CCompiler.add_link_object(object)

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

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

      link driven by this compiler object.

   .. method:: CCompiler.set_link_objects(objects)

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

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

      include by default (such as system libraries).

   The following methods implement methods for autodetection of compiler  options,

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

   .. method:: CCompiler.detect_language(sources)

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

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

      list) to do the job.

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

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

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

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

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

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

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

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

      environment by providing additional include files and paths and libraries and

      paths.

   .. method:: CCompiler.library_dir_option(dir)

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

      libraries.

   .. method:: CCompiler.library_option(lib)

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

      shared library or executable.

   .. method:: CCompiler.runtime_library_dir_option(dir)

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

      runtime libraries.

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

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

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

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

      attribute), but most will have:

      +--------------+------------------------------------------+

      | attribute    | description                              |

      +==============+==========================================+

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

      +--------------+------------------------------------------+

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

      |              | libraries                                |

      +--------------+------------------------------------------+

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

      +--------------+------------------------------------------+

      | *archiver*   | static library creator                   |

      +--------------+------------------------------------------+