sam-t2/devtools/amd64/html/python/dist/module-distutils.core.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="dist.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="dist.html" title='Distributing Python Modules' />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-distutils.ccompiler.html" />
<link rel="prev" href="api-reference.html" />
<link rel="parent" href="api-reference.html" />
<link rel="next" href="module-distutils.ccompiler.html" />
<meta name='aesop' content='information' />
<title>10.1 distutils.core -- Core Distutils functionality</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="10. API Reference"
  href="api-reference.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="10. API Reference"
  href="api-reference.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="10.2 distutils.ccompiler  "
  href="module-distutils.ccompiler.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="api-reference.html">10. API Reference</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-distutils.ccompiler.html">10.2 distutils.ccompiler  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0010100000000000000000">
10.1 <tt class="module">distutils.core</tt> -- Core Distutils functionality</A>
</H1>

<P>
<A NAME="module-distutils.core"></A>

<P>
The <tt class="module">distutils.core</tt> module is the only module that needs to be
installed to use the Distutils. It provides the <tt class="function">setup()</tt> (which
is called from the setup script). Indirectly provides the
<tt class="class">distutils.dist.Distribution</tt> and <tt class="class">distutils.cmd.Command</tt> class.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-6' xml:id='l2h-6' class="function">setup</tt></b>(</nobr></td>
  <td><var>arguments</var>)</td></tr></table></dt>
<dd>
The basic do-everything function that does most everything you could ever
ask for from a Distutils method. See XXXXX

<P>
The setup function takes a large number of arguments. These
are laid out in the following table.

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">argument name</th>
      <th class="left"  >value</th>
      <th class="left"  >type</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><argument name>name</argument></td>
        <td class="left"  >The name of the package</td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>version</argument></td>
        <td class="left"  >The version number of the package</td>
        <td class="left"  >See <tt class="module"><a href="module-distutils.version.html">distutils.version</a></tt></td></tr>
    <tr><td class="center" valign="baseline"><argument name>description</argument></td>
        <td class="left"  >A single line describing the package</td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>long_description</argument></td>
        <td class="left"  >Longer description of the package</td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>author</argument></td>
        <td class="left"  >The name of the package author</td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>author_email</argument></td>
        <td class="left"  >The email address of the package author</td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>maintainer</argument></td>
        <td class="left"  >The name of the current maintainer, if different from the author</td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>maintainer_email</argument></td>
        <td class="left"  >The email address of the current maintainer, if different from the author</td>
        <td class="left"  ></td></tr>
    <tr><td class="center" valign="baseline"><argument name>url</argument></td>
        <td class="left"  >A URL for the package (homepage)</td>
        <td class="left"  >a URL</td></tr>
    <tr><td class="center" valign="baseline"><argument name>download_url</argument></td>
        <td class="left"  >A URL to download the package</td>
        <td class="left"  >a URL</td></tr>
    <tr><td class="center" valign="baseline"><argument name>packages</argument></td>
        <td class="left"  >A list of Python packages that distutils will manipulate</td>
        <td class="left"  >a list of strings</td></tr>
    <tr><td class="center" valign="baseline"><argument name>py_modules</argument></td>
        <td class="left"  >A list of Python modules that distutils will manipulate</td>
        <td class="left"  >a list of strings</td></tr>
    <tr><td class="center" valign="baseline"><argument name>scripts</argument></td>
        <td class="left"  >A list of standalone script files to be built and installed</td>
        <td class="left"  >a list of strings</td></tr>
    <tr><td class="center" valign="baseline"><argument name>ext_modules</argument></td>
        <td class="left"  >A list of Python extensions to be built</td>
        <td class="left"  >A list of
instances of <tt class="class">distutils.core.Extension</tt></td></tr>
    <tr><td class="center" valign="baseline"><argument name>classifiers</argument></td>
        <td class="left"  >A list of Trove categories for the package</td>
        <td class="left"  >XXX link to better definition</td></tr>
    <tr><td class="center" valign="baseline"><argument name>distclass</argument></td>
        <td class="left"  >the <tt class="class">Distribution</tt> class to use</td>
        <td class="left"  >A subclass of <tt class="class">distutils.core.Distribution</tt></td></tr>
    <tr><td class="center" valign="baseline"><argument name>script_name</argument></td>
        <td class="left"  >The name of the setup.py script - defaults to <code>sys.argv[0]</code></td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>script_args</argument></td>
        <td class="left"  >Arguments to supply to the setup script</td>
        <td class="left"  >a list of strings</td></tr>
    <tr><td class="center" valign="baseline"><argument name>options</argument></td>
        <td class="left"  >default options for the setup script</td>
        <td class="left"  >a string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>license</argument></td>
        <td class="left"  >The license for the package</td>
        <td class="left"  ></td></tr>
    <tr><td class="center" valign="baseline"><argument name>keywords</argument></td>
        <td class="left"  >Descriptive meta-data. See <a class="rfc" id='rfcref-5120' xml:id='rfcref-5120'
href="http://www.python.org/peps/pep-0314.html">PEP 314</a></td>
        <td class="left"  ></td></tr>
    <tr><td class="center" valign="baseline"><argument name>platforms</argument></td>
        <td class="left"  ></td>
        <td class="left"  ></td></tr>
    <tr><td class="center" valign="baseline"><argument name>cmdclass</argument></td>
        <td class="left"  >A mapping of command names to <tt class="class">Command</tt> subclasses</td>
        <td class="left"  >a dictionary</td></tr></tbody>
</table></div>

<P>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-7' xml:id='l2h-7' class="function">run_setup</tt></b>(</nobr></td>
  <td><var>script_name</var><big>[</big><var>, script_args=<code>None</code>, stop_after=<code>'run'</code></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Run a setup script in a somewhat controlled environment, and return
the <tt class="class">distutils.dist.Distribution</tt> instance that drives things.
This is useful if you need to find out the distribution meta-data
(passed as keyword args from <var>script</var> to <tt class="function">setup()</tt>), or
the contents of the config files or command-line.

<P>
<var>script_name</var> is a file that will be run with <tt class="function">execfile()</tt>
<code>sys.argv[0]</code> will be replaced with <var>script</var> for the duration of the
call.  <var>script_args</var> is a list of strings; if supplied,
<code>sys.argv[1:]</code> will be replaced by <var>script_args</var> for the duration
of the call.

<P>
<var>stop_after</var> tells <tt class="function">setup()</tt> when to stop processing; possible
values:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">value</th>
      <th class="left"  >description</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><argument name>init</argument></td>
        <td class="left"  >Stop after the <tt class="class">Distribution</tt> instance has been created
and populated with the keyword arguments to <tt class="function">setup()</tt></td></tr>
    <tr><td class="center" valign="baseline"><argument name>config</argument></td>
        <td class="left"  >Stop after config files have been parsed (and their data
stored in the <tt class="class">Distribution</tt> instance)</td></tr>
    <tr><td class="center" valign="baseline"><argument name>commandline</argument></td>
        <td class="left"  >Stop after the command-line (<code>sys.argv[1:]</code> or
<var>script_args</var>) have been parsed (and the data stored in the
<tt class="class">Distribution</tt> instance.)</td></tr>
    <tr><td class="center" valign="baseline"><argument name>run</argument></td>
        <td class="left"  >Stop after all commands have been run (the same as
if <tt class="function">setup()</tt> had been called in the usual way). This is the default
value.</td></tr></tbody>
</table></div>
</dl>

<P>
In addition, the <tt class="module">distutils.core</tt> module exposed a number of
classes that live elsewhere.

<P>

<UL>
<LI><tt class="class">Extension</tt> from <tt class="module"><a href="module-distutils.extension.html">distutils.extension</a></tt>
</LI>
<LI><tt class="class">Command</tt> from <tt class="module"><a href="module-distutils.cmd.html">distutils.cmd</a></tt>
</LI>
<LI><tt class="class">Distribution</tt> from <tt class="module"><a href="module-distutils.dist.html">distutils.dist</a></tt>
</LI>
</UL>

<P>
A short description of each of these follows, but see the relevant
module for the full reference.

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-8' xml:id='l2h-8' class="class">Extension</tt></b>
<dd>

<P>
The Extension class describes a single C or C++extension module in a
setup script. It accepts the following keyword arguments in its
constructor

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">argument name</th>
      <th class="left"  >value</th>
      <th class="left"  >type</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><argument name>name</argument></td>
        <td class="left"  >the full name of the extension, including any packages
-- ie. <em>not</em> a filename or pathname, but Python dotted name</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>sources</argument></td>
        <td class="left"  >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 <code class="du-command">build_ext</code>
command as source for a Python extension.</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>include_dirs</argument></td>
        <td class="left"  >list of directories to search for C/C++ header
files (in <span class="Unix">Unix</span> form for portability)</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>define_macros</argument></td>
        <td class="left"  >list of macros to define; each macro is defined
using a 2-tuple, where 'value' is either the string to define it to or
<code>None</code> to define it without a particular value (equivalent of
<code>#define FOO</code> in source or <b class="programopt">-DFOO</b> on <span class="Unix">Unix</span> C
compiler command line) </td>
        <td class="left"  > (string,string)
tuple or (name,<code>None</code>) </td></tr>
    <tr><td class="center" valign="baseline"><argument name>undef_macros</argument></td>
        <td class="left"  >list of macros to undefine explicitly</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>library_dirs</argument></td>
        <td class="left"  >list of directories to search for C/C++ libraries
at link time </td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>libraries</argument></td>
        <td class="left"  >list of library names (not filenames or paths) to
link against </td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>runtime_library_dirs</argument></td>
        <td class="left"  >list of directories to search for C/C++
libraries at run time (for shared extensions, this is when the extension
is loaded)</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>extra_objects</argument></td>
        <td class="left"  >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.)</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>extra_compile_args</argument></td>
        <td class="left"  >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.</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>extra_link_args</argument></td>
        <td class="left"  >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'.</td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>export_symbols</argument></td>
        <td class="left"  >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: <code>init</code> +
extension_name. </td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>depends</argument></td>
        <td class="left"  >list of files that the extension depends on </td>
        <td class="left"  >string</td></tr>
    <tr><td class="center" valign="baseline"><argument name>language</argument></td>
        <td class="left"  >extension language (i.e. <code>'c'</code>, <code>'c++'</code>,
<code>'objc'</code>). Will be detected from the source extensions if not provided.
</td>
        <td class="left"  >string</td></tr></tbody>
</table></div>
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-9' xml:id='l2h-9' class="class">Distribution</tt></b>
<dd>
A <tt class="class">Distribution</tt> describes how to build, install and package up a
Python software package.

<P>
See the <tt class="function">setup()</tt> function for a list of keyword arguments accepted
by the Distribution constructor. <tt class="function">setup()</tt> creates a Distribution
instance.
</dl>

<P>
<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-10' xml:id='l2h-10' class="class">Command</tt></b>
<dd>
A <tt class="class">Command</tt> class (or rather, an instance of one of its subclasses)
implement a single distutils command.
</dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="10. API Reference"
  href="api-reference.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="10. API Reference"
  href="api-reference.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="10.2 distutils.ccompiler  "
  href="module-distutils.ccompiler.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Distributing Python Modules</td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="api-reference.html">10. API Reference</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-distutils.ccompiler.html">10.2 distutils.ccompiler  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>