<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>3. Writing the Setup Configuration File — Python v3.2.2 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '3.2.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v3.2.2 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python v3.2.2 documentation" href="../index.html" />
<link rel="up" title="Distributing Python Modules" href="index.html" />
<link rel="next" title="4. Creating a Source Distribution" href="sourcedist.html" />
<link rel="prev" title="2. Writing the Setup Script" href="setupscript.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v3.2.2 documentation</a> »</li>
<li><a href="index.html" accesskey="U">Distributing Python Modules</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="writing-the-setup-configuration-file">
<span id="setup-config"></span><h1>3. Writing the Setup Configuration File<a class="headerlink" href="#writing-the-setup-configuration-file" title="Permalink to this headline">ΒΆ</a></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, <tt class="file docutils literal"><span class="pre">setup.cfg</span></tt>, 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>
<p>The setup configuration file is a useful middle-ground between the setup script
—which, ideally, would be opaque to installers <a class="footnote-reference" href="#id2" id="id1">[1]</a>—and the command-line to
the setup script, which is outside of your control and entirely up to the
installer. In fact, <tt class="file docutils literal"><span class="pre">setup.cfg</span></tt> (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:</p>
<ul class="simple">
<li>installers can override some of what you put in <tt class="file docutils literal"><span class="pre">setup.py</span></tt> by editing
<tt class="file docutils literal"><span class="pre">setup.cfg</span></tt></li>
<li>you can provide non-standard defaults for options that are not easily set in
<tt class="file docutils literal"><span class="pre">setup.py</span></tt></li>
<li>installers can override anything in <tt class="file docutils literal"><span class="pre">setup.cfg</span></tt> using the command-line
options to <tt class="file docutils literal"><span class="pre">setup.py</span></tt></li>
</ul>
<p>The basic syntax of the configuration file is simple:</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="p">[</span><span class="n">command</span><span class="p">]</span>
<span class="n">option</span><span class="o">=</span><span class="n">value</span>
<span class="o">...</span>
</pre></div>
</div>
<p>where <em>command</em> is one of the Distutils commands (e.g. <strong class="command">build_py</strong>,
<strong class="command">install</strong>), and <em>option</em> 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="docutils literal"><span class="pre">'#'</span></tt> character until the end of the line. Long
option values can be split across multiple lines simply by indenting the
continuation lines.</p>
<p>You can find out the list of options supported by a particular command with the
universal <a class="reference internal" href="../using/cmdline.html#cmdoption--help"><em class="xref std std-option">--help</em></a> option, e.g.</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="o">></span> <span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="n">help</span> <span class="n">build_ext</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>
<span class="n">Options</span> <span class="k">for</span> <span class="s">'build_ext'</span> <span class="n">command</span><span class="p">:</span>
<span class="o">--</span><span class="n">build</span><span class="o">-</span><span class="n">lib</span> <span class="p">(</span><span class="o">-</span><span class="n">b</span><span class="p">)</span> <span class="n">directory</span> <span class="k">for</span> <span class="n">compiled</span> <span class="n">extension</span> <span class="n">modules</span>
<span class="o">--</span><span class="n">build</span><span class="o">-</span><span class="n">temp</span> <span class="p">(</span><span class="o">-</span><span class="n">t</span><span class="p">)</span> <span class="n">directory</span> <span class="k">for</span> <span class="n">temporary</span> <span class="n">files</span> <span class="p">(</span><span class="n">build</span> <span class="n">by</span><span class="o">-</span><span class="n">products</span><span class="p">)</span>
<span class="o">--</span><span class="n">inplace</span> <span class="p">(</span><span class="o">-</span><span class="n">i</span><span class="p">)</span> <span class="n">ignore</span> <span class="n">build</span><span class="o">-</span><span class="n">lib</span> <span class="ow">and</span> <span class="n">put</span> <span class="n">compiled</span> <span class="n">extensions</span> <span class="n">into</span> <span class="n">the</span>
<span class="n">source</span> <span class="n">directory</span> <span class="n">alongside</span> <span class="n">your</span> <span class="n">pure</span> <span class="n">Python</span> <span class="n">modules</span>
<span class="o">--</span><span class="n">include</span><span class="o">-</span><span class="n">dirs</span> <span class="p">(</span><span class="o">-</span><span class="n">I</span><span class="p">)</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">directories</span> <span class="n">to</span> <span class="n">search</span> <span class="k">for</span> <span class="n">header</span> <span class="n">files</span>
<span class="o">--</span><span class="n">define</span> <span class="p">(</span><span class="o">-</span><span class="n">D</span><span class="p">)</span> <span class="n">C</span> <span class="n">preprocessor</span> <span class="n">macros</span> <span class="n">to</span> <span class="n">define</span>
<span class="o">--</span><span class="n">undef</span> <span class="p">(</span><span class="o">-</span><span class="n">U</span><span class="p">)</span> <span class="n">C</span> <span class="n">preprocessor</span> <span class="n">macros</span> <span class="n">to</span> <span class="n">undefine</span>
<span class="o">--</span><span class="n">swig</span><span class="o">-</span><span class="n">opts</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">SWIG</span> <span class="n">command</span> <span class="n">line</span> <span class="n">options</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>Note that an option spelled <em class="xref std std-option">--foo-bar</em> on the command-line is spelled
<em class="xref std std-option">foo_bar</em> in configuration files.</p>
<p>For example, say you want your extensions to be built “in-place”—that is, you
have an extension <tt class="xref py py-mod docutils literal"><span class="pre">pkg.ext</span></tt>, and you want the compiled extension file
(<tt class="file docutils literal"><span class="pre">ext.so</span></tt> on Unix, say) to be put in the same source directory as your
pure Python modules <tt class="xref py py-mod docutils literal"><span class="pre">pkg.mod1</span></tt> and <tt class="xref py py-mod docutils literal"><span class="pre">pkg.mod2</span></tt>. You can always use the
<em class="xref std std-option">--inplace</em> option on the command-line to ensure this:</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build_ext</span> <span class="o">--</span><span class="n">inplace</span>
</pre></div>
</div>
<p>But this requires that you always specify the <strong class="command">build_ext</strong> command
explicitly, and remember to provide <em class="xref std std-option">--inplace</em>. An easier way is to
“set and forget” this option, by encoding it in <tt class="file docutils literal"><span class="pre">setup.cfg</span></tt>, the
configuration file for this distribution:</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="p">[</span><span class="n">build_ext</span><span class="p">]</span>
<span class="n">inplace</span><span class="o">=</span><span class="mi">1</span>
</pre></div>
</div>
<p>This will affect all builds of this module distribution, whether or not you
explicitly specify <strong class="command">build_ext</strong>. If you include <tt class="file docutils literal"><span class="pre">setup.cfg</span></tt> 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>
<p>Another example: certain commands take a lot of options that don’t change from
run to run; for example, <strong class="command">bdist_rpm</strong> 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 <strong class="command">bdist_rpm</strong>, which would be very tedious to do
on the command-line for every run. Hence, here is a snippet from the Distutils’
own <tt class="file docutils literal"><span class="pre">setup.cfg</span></tt>:</p>
<div class="highlight-python3"><div class="highlight"><pre><span class="p">[</span><span class="n">bdist_rpm</span><span class="p">]</span>
<span class="n">release</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">packager</span> <span class="o">=</span> <span class="n">Greg</span> <span class="n">Ward</span> <span class="o"><</span><span class="n">gward</span><span class="nd">@python</span><span class="o">.</span><span class="n">net</span><span class="o">></span>
<span class="n">doc_files</span> <span class="o">=</span> <span class="n">CHANGES</span><span class="o">.</span><span class="n">txt</span>
<span class="n">README</span><span class="o">.</span><span class="n">txt</span>
<span class="n">USAGE</span><span class="o">.</span><span class="n">txt</span>
<span class="n">doc</span><span class="o">/</span>
<span class="n">examples</span><span class="o">/</span>
</pre></div>
</div>
<p>Note that the <em class="xref std std-option">doc_files</em> option is simply a whitespace-separated string
split across multiple lines for readability.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="../install/index.html#inst-config-syntax"><em>Syntax of config files</em></a> in “Installing Python Modules”</dt>
<dd>More information on the configuration files is available in the manual for
system administrators.</dd>
</dl>
</div>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This ideal probably won’t be achieved until auto-configuration is fully
supported by the Distutils.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="setupscript.html"
title="previous chapter">2. Writing the Setup Script</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="sourcedist.html"
title="next chapter">4. Creating a Source Distribution</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li><a href="../_sources/distutils/configfile.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
>next</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v3.2.2 documentation</a> »</li>
<li><a href="index.html" >Distributing Python Modules</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Sep 04, 2011.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
contrib-backports
>
by-pkgid
>
3ba3bd1608c672ba2129b098a48e9e4d
>
files
>
517
