sam-t2/devtools/v8plus/html/python/dist/setup-config.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="source-dist.html" />
<link rel="prev" href="setup-script.html" />
<link rel="parent" href="dist.html" />
<link rel="next" href="source-dist.html" />
<meta name='aesop' content='information' />
<title>3. Writing the Setup Configuration File</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="2.8 Debugging the setup"
  href="node14.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="Distributing Python Modules"
  href="dist.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="4. Creating a Source"
  href="source-dist.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="node14.html">2.8 Debugging the setup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="source-dist.html">4. Creating a Source</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION003000000000000000000"></A>
<A NAME="setup-config"></A>
<BR>
3. Writing the Setup Configuration File
</H1>

<P>
Often, it's not possible to write down everything needed to build a
distribution <em>a priori</em>: you may need to get some information from
the user, or from the user's system, in order to proceed.  As long as
that information is fairly simple--a list of directories to search for
C header files or libraries, for example--then providing a
configuration file, <span class="file">setup.cfg</span>, for users to edit is a cheap and
easy way to solicit it.  Configuration files also let you provide
default values for any command option, which the installer can then
override either on the command-line or by editing the config file.

<P>
The setup configuration file is a useful middle-ground between the setup
script--which, ideally, would be opaque to installers<A NAME="tex2html1"
  HREF="#foot393"><SUP>3.1</SUP></A>--and the command-line to the setup
script, which is outside of your control and entirely up to the
installer.  In fact, <span class="file">setup.cfg</span> (and any other Distutils
configuration files present on the target system) are processed after
the contents of the setup script, but before the command-line.  This has
several useful consequences:

<UL>
<LI>installers can override some of what you put in <span class="file">setup.py</span> by
  editing <span class="file">setup.cfg</span>
</LI>
<LI>you can provide non-standard defaults for options that are not
  easily set in <span class="file">setup.py</span>
</LI>
<LI>installers can override anything in <span class="file">setup.cfg</span> using the
  command-line options to <span class="file">setup.py</span>
</LI>
</UL>

<P>
The basic syntax of the configuration file is simple:

<P>
<div class="verbatim"><pre>
[command]
option=value
...
</pre></div>

<P>
where <var>command</var> is one of the Distutils commands (e.g.
<code class="du-command">build_py</code>, <code class="du-command">install</code>), and <var>option</var> is one of
the options that command supports.  Any number of options can be
supplied for each command, and any number of command sections can be
included in the file.  Blank lines are ignored, as are comments, which
run from a "<tt class="character">#</tt>" character until the end of the line.  Long
option values can be split across multiple lines simply by indenting
the continuation lines.

<P>
You can find out the list of options supported by a particular command
with the universal <b class="programopt">--help</b> option, e.g.

<P>
<div class="verbatim"><pre>
&gt; python setup.py --help build_ext
[...]
Options for 'build_ext' command:
  --build-lib (-b)     directory for compiled extension modules
  --build-temp (-t)    directory for temporary files (build by-products)
  --inplace (-i)       ignore build-lib and put compiled extensions into the
                       source directory alongside your pure Python modules
  --include-dirs (-I)  list of directories to search for header files
  --define (-D)        C preprocessor macros to define
  --undef (-U)         C preprocessor macros to undefine
[...]
</pre></div>

<P>
Note that an option spelled <b class="programopt">--foo-bar</b> on the command-line
is spelled <span class="du-option">foo_bar</span> in configuration files.

<P>
For example, say you want your extensions to be built
``in-place''--that is, you have an extension <tt class="module">pkg.ext</tt>, and you
want the compiled extension file (<span class="file">ext.so</span> on <span class="Unix">Unix</span>, say) to be put
in the same source directory as your pure Python modules
<tt class="module">pkg.mod1</tt> and <tt class="module">pkg.mod2</tt>.  You can always use the
<b class="programopt">--inplace</b> option on the command-line to ensure this:

<P>
<div class="verbatim"><pre>
python setup.py build_ext --inplace
</pre></div>

<P>
But this requires that you always specify the <code class="du-command">build_ext</code>
command explicitly, and remember to provide <b class="programopt">--inplace</b>.
An easier way is to ``set and forget'' this option, by encoding it in
<span class="file">setup.cfg</span>, the configuration file for this distribution:

<P>
<div class="verbatim"><pre>
[build_ext]
inplace=1
</pre></div>

<P>
This will affect all builds of this module distribution, whether or not
you explicitly specify <code class="du-command">build_ext</code>.  If you include
<span class="file">setup.cfg</span> in your source distribution, it will also affect
end-user builds--which is probably a bad idea for this option, since
always building extensions in-place would break installation of the
module distribution.  In certain peculiar cases, though, modules are
built right in their installation directory, so this is conceivably a
useful ability.  (Distributing extensions that expect to be built in
their installation directory is almost always a bad idea, though.)

<P>
Another example: certain commands take a lot of options that don't
change from run to run; for example, <code class="du-command">bdist_rpm</code> needs to know
everything required to generate a ``spec'' file for creating an RPM
distribution.  Some of this information comes from the setup script, and
some is automatically generated by the Distutils (such as the list of
files installed).  But some of it has to be supplied as options to
<code class="du-command">bdist_rpm</code>, which would be very tedious to do on the
command-line for every run.  Hence, here is a snippet from the
Distutils' own <span class="file">setup.cfg</span>:

<P>
<div class="verbatim"><pre>
[bdist_rpm]
release = 1
packager = Greg Ward &lt;gward@python.net&gt;
doc_files = CHANGES.txt
            README.txt
            USAGE.txt
            doc/
            examples/
</pre></div>

<P>
Note that the <span class="du-option">doc_files</span> option is simply a
whitespace-separated string split across multiple lines for readability.

<P>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seetitle">
    <dt><em class="citetitle"><a href="../inst/config-syntax.html"
        >Installing Python
            Modules</a></em></dt>
    <dd>More information on the configuration files is
            available in the manual for system administrators.</dd>
  </dl>
</div>

<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot393">... installers</A><A
 href="setup-config.html#tex2html1"><SUP>3.1</SUP></A></DT>
<DD>This
  ideal probably won't be achieved until auto-configuration is fully
  supported by the Distutils.

</DD>
</DL>
<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="2.8 Debugging the setup"
  href="node14.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="Distributing Python Modules"
  href="dist.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="4. Creating a Source"
  href="source-dist.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="node14.html">2.8 Debugging the setup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dist.html">Distributing Python Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="source-dist.html">4. Creating a Source</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>