10.1 distutils.core -- Core Distutils functionality

# 10.1 `distutils.core` -- Core Distutils functionality

The `distutils.core` module is the only module that needs to be installed to use the Distutils. It provides the `setup()` (which is called from the setup script). Indirectly provides the `distutils.dist.Distribution` and `distutils.cmd.Command` class.

`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 package | See `distutils.version`
  description | A single line describing the package | a string
  long_description | Longer description of the package | a string
  author | The name of the package author | a string
  author_email | The email address of the package author | a string
  maintainer | The name of the current maintainer, if different from the author | a string
  maintainer_email | The email address of the current maintainer, if different from the author |
  url | A URL for the package (homepage) | a URL
  download_url | A URL to download the package | a URL
  packages | A list of Python packages that distutils will manipulate | a list of strings
  py_modules | A list of Python modules that distutils will manipulate | a list of strings
  scripts | A list of standalone script files to be built and installed | a list of strings
  ext_modules | A list of Python extensions to be built | A list of instances of `distutils.core.Extension`
  classifiers | A list of categories for the package | The list of available categorizations is at http://cheeseshop.python.org/pypi?:action=list_classifiers.
  distclass | the `Distribution` class to use | A subclass of `distutils.core.Distribution`
  script_name | The name of the setup.py script - defaults to `sys.argv[0]` | a string
  script_args | Arguments to supply to the setup script | a list of strings
  options | default options for the setup script | a string
  license | The license for the package |
  keywords | Descriptive meta-data. See PEP 314 |
  platforms |  |
  cmdclass | A mapping of command names to `Command` subclasses | a dictionary

`run_setup`( | script_name[, script_args=`None`, stop_after=`'run'`])

  Run a setup script in a somewhat controlled environment, and return the `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 `setup()`), or the contents of the config files or command-line.

  script_name is a file that will be run with `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 `setup()` when to stop processing; possible values:

  value | description
  --- | ---
  init | Stop after the `Distribution` instance has been created and populated with the keyword arguments to `setup()`
  config | Stop after config files have been parsed (and their data stored in the `Distribution` instance)
  commandline | Stop after the command-line (`sys.argv[1:]` or script_args) have been parsed (and the data stored in the `Distribution` instance.)
  run | Stop after all commands have been run (the same as if `setup()` had been called in the usual way). This is the default value.

In addition, the `distutils.core` module exposed a number of classes that live elsewhere.

- `Extension` from `distutils.extension`
- `Command` from `distutils.cmd`
- `Distribution` from `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 extension, including any packages -- ie. not a filename or pathname, but Python dotted name | string
  sources | list of source filenames, relative to the distribution root (where the setup script lives), in Unix form (slash-separated) for portability. Source files may be C, C++, SWIG (.i), platform-specific resource files, or whatever else is recognized by the `build_ext` command as source for a Python extension. | string
  include_dirs | list of directories to search for C/C++ header files (in Unix form for portability) | string
  define_macros | list of macros to define; each macro is defined using a 2-tuple, where 'value' is either the string to define it to or `None` to define it without a particular value (equivalent of `#define FOO` in source or -DFOO on Unix C compiler command line) | (string,string) tuple or (name,`None`)
  undef_macros | list of macros to undefine explicitly | string
  library_dirs | list of directories to search for C/C++ libraries at link time | string
  libraries | list of library names (not filenames or paths) to link against | string
  runtime_library_dirs | list of directories to search for C/C++ libraries at run time (for shared extensions, this is when the extension is loaded) | string
  extra_objects | list of extra files to link with (eg. object files not implied by 'sources', static library that must be explicitly specified, binary resource files, etc.) | string
  extra_compile_args | any extra platform- and compiler-specific information to use when compiling the source files in 'sources'. For platforms and compilers where a command line makes sense, this is typically a list of command-line arguments, but for other platforms it could be anything. | string
  extra_link_args | any extra platform- and compiler-specific information to use when linking object files together to create the extension (or to create a new static Python interpreter). Similar interpretation as for 'extra_compile_args'. | string
  export_symbols | list of symbols to be exported from a shared extension. Not used on all platforms, and not generally necessary for Python extensions, which typically export exactly one symbol: `init` + extension_name. | string
  depends | list of files that the extension depends on | string
  language | extension language (i.e. `'c'`, `'c++'`, `'objc'`). Will be detected from the source extensions if not provided. | string

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

  See the `setup()` function for a list of keyword arguments accepted by the Distribution constructor. `setup()` creates a Distribution instance.

class `Command`
  A `Command` class (or rather, an instance of one of its subclasses) implement a single distutils command.