# 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
  --- | --- | ---
  <argument name>name</argument> | The name of the package | a string
  <argument name>version</argument> | The version number of the package | See `distutils.version`
  <argument name>description</argument> | A single line describing the package | a string
  <argument name>long_description</argument> | Longer description of the package | a string
  <argument name>author</argument> | The name of the package author | a string
  <argument name>author_email</argument> | The email address of the package author | a string
  <argument name>maintainer</argument> | The name of the current maintainer, if different from the author | a string
  <argument name>maintainer_email</argument> | The email address of the current maintainer, if different from the author |
  <argument name>url</argument> | A URL for the package (homepage) | a URL
  <argument name>download_url</argument> | A URL to download the package | a URL
  <argument name>packages</argument> | A list of Python packages that distutils will manipulate | a list of strings
  <argument name>py_modules</argument> | A list of Python modules that distutils will manipulate | a list of strings
  <argument name>scripts</argument> | A list of standalone script files to be built and installed | a list of strings
  <argument name>ext_modules</argument> | A list of Python extensions to be built | A list of instances of `distutils.core.Extension`
  <argument name>classifiers</argument> | A list of Trove categories for the package | XXX link to better definition
  <argument name>distclass</argument> | the `Distribution` class to use | A subclass of `distutils.core.Distribution`
  <argument name>script_name</argument> | The name of the setup.py script - defaults to `sys.argv[0]` | a string
  <argument name>script_args</argument> | Arguments to supply to the setup script | a list of strings
  <argument name>options</argument> | default options for the setup script | a string
  <argument name>license</argument> | The license for the package |
  <argument name>keywords</argument> | Descriptive meta-data. See PEP 314 |
  <argument name>platforms</argument> |  |
  <argument name>cmdclass</argument> | 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
  --- | ---
  <argument name>init</argument> | Stop after the `Distribution` instance has been created and populated with the keyword arguments to `setup()`
  <argument name>config</argument> | Stop after config files have been parsed (and their data stored in the `Distribution` instance)
  <argument name>commandline</argument> | Stop after the command-line (`sys.argv[1:]` or script_args) have been parsed (and the data stored in the `Distribution` instance.)
  <argument name>run</argument> | 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 it's constructor

  argument name | value | type
  --- | --- | ---
  <argument name>name</argument> | the full name of the extension, including any packages -- ie. not a filename or pathname, but Python dotted name | string
  <argument name>sources</argument> | 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
  <argument name>include_dirs</argument> | list of directories to search for C/C++ header files (in Unix form for portability) | string
  <argument name>define_macros</argument> | 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`)
  <argument name>undef_macros</argument> | list of macros to undefine explicitly | string
  <argument name>library_dirs</argument> | list of directories to search for C/C++ libraries at link time | string
  <argument name>libraries</argument> | list of library names (not filenames or paths) to link against | string
  <argument name>runtime_library_dirs</argument> | list of directories to search for C/C++ libraries at run time (for shared extensions, this is when the extension is loaded) | string
  <argument name>extra_objects</argument> | 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
  <argument name>extra_compile_args</argument> | 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
  <argument name>extra_link_args</argument> | 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
  <argument name>export_symbols</argument> | 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
  <argument name>depends</argument> | list of files that the extension depends on | string
  <argument name>language</argument> | 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 it's subclasses) implement a single distutils command.