<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<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>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<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>
<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>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION0010100000000000000000">
10.1 <tt class=
"module">distutils.core
</tt> -- Core Distutils functionality
</A>
<A NAME=
"module-distutils.core"></A>
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.
<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>
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.
<div class=
"center"><table class=
"realtable">
<th class=
"center">argument name
</th>
<th class=
"left" >value
</th>
<th class=
"left" >type
</th>
<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></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>
<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>
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.
<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
<var>stop_after
</var> tells
<tt class=
"function">setup()
</tt> when to stop processing; possible
<div class=
"center"><table class=
"realtable">
<th class=
"center">value
</th>
<th class=
"left" >description
</th>
<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
In addition, the
<tt class=
"module">distutils.core
</tt> module exposed a number of
classes that live elsewhere.
<LI><tt class=
"class">Extension
</tt> from
<tt class=
"module"><a href=
"module-distutils.extension.html">distutils.extension
</a></tt>
<LI><tt class=
"class">Command
</tt> from
<tt class=
"module"><a href=
"module-distutils.cmd.html">distutils.cmd
</a></tt>
<LI><tt class=
"class">Distribution
</tt> from
<tt class=
"module"><a href=
"module-distutils.dist.html">distutils.dist
</a></tt>
A short description of each of these follows, but see the relevant
module for the full reference.
<dl><dt><b><span class=
"typelabel">class
</span> <tt id='l2h-
8' xml:id='l2h-
8'
class=
"class">Extension
</tt></b>
The Extension class describes a single C or C++extension module in a
setup script. It accepts the following keyword arguments in its
<div class=
"center"><table class=
"realtable">
<th class=
"center">argument name
</th>
<th class=
"left" >value
</th>
<th class=
"left" >type
</th>
<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
<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
<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
<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
<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> +
<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 class=
"left" >string
</td></tr></tbody>
<dl><dt><b><span class=
"typelabel">class
</span> <tt id='l2h-
9' xml:id='l2h-
9'
class=
"class">Distribution
</tt></b>
A
<tt class=
"class">Distribution
</tt> describes how to build, install and package up a
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
<dl><dt><b><span class=
"typelabel">class
</span> <tt id='l2h-
10' xml:id='l2h-
10'
class=
"class">Command
</tt></b>
A
<tt class=
"class">Command
</tt> class (or rather, an instance of one of its subclasses)
implement a single distutils command.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<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>
<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>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.