View file File name : configfile.html Content : <!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> <title>3. Writing the Setup Configuration File — Python 2.7.18 documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> <script src="../_static/jquery.js"></script> <script src="../_static/underscore.js"></script> <script src="../_static/doctools.js"></script> <script src="../_static/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 2.7.18 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="copyright" title="Copyright" href="../copyright.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" /> <link rel="canonical" href="file:///usr/share/doc/python2.7/html/distutils/configfile.html" /> <script type="text/javascript" src="../_static/copybutton.js"></script> </head><body> <div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;"> This document is for an old version of Python that is <a href="https://devguide.python.org/devcycle/#end-of-life-branches">no longer supported</a>. You should install the python3 and python3-doc packages and read the <a href="file:///usr/share/doc/python3-doc/html/distutils/configfile.html"> Python documentation for the Python3 version packaged in this release</a>. </div> <div class="related" role="navigation" aria-label="related navigation"> <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="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.18 documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li> <li class="nav-item nav-item-this"><a href=""><span class="section-number">3. </span>Writing the Setup Configuration File</a></li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="writing-the-setup-configuration-file"> <span id="setup-config"></span><h1><span class="section-number">3. </span>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, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>, 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 brackets" 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, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> (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><p>installers can override some of what you put in <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by editing <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code></p></li> <li><p>you can provide non-standard defaults for options that are not easily set in <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code></p></li> <li><p>installers can override anything in <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> using the command-line options to <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code></p></li> </ul> <p>The basic syntax of the configuration file is simple:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">'#'</span></code> 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 <code class="xref std std-option docutils literal notranslate"><span class="pre">--help</span></code> option, e.g.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s1">'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 <code class="xref std std-option docutils literal notranslate"><span class="pre">--foo-bar</span></code> on the command-line is spelled <code class="docutils literal notranslate"><span class="pre">foo_bar</span></code> in configuration files.</p> <p id="distutils-build-ext-inplace">For example, say you want your extensions to be built āin-placeāāthat is, you have an extension <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.ext</span></code>, and you want the compiled extension file (<code class="file docutils literal notranslate"><span class="pre">ext.so</span></code> on Unix, say) to be put in the same source directory as your pure Python modules <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.mod1</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.mod2</span></code>. You can always use the <code class="xref std std-option docutils literal notranslate"><span class="pre">--inplace</span></code> option on the command-line to ensure this:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="xref std std-option docutils literal notranslate"><span class="pre">--inplace</span></code>. An easier way is to āset and forgetā this option, by encoding it in <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>, the configuration file for this distribution:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> 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 <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">doc_files</span></code> option is simply a whitespace-separated string split across multiple lines for readability.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt><a class="reference internal" href="../install/index.html#inst-config-syntax"><span class="std std-ref">Syntax of config files</span></a> in āInstalling Python Modulesā</dt><dd><p>More information on the configuration files is available in the manual for system administrators.</p> </dd> </dl> </div> <p class="rubric">Footnotes</p> <dl class="footnote brackets"> <dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt> <dd><p>This ideal probably wonāt be achieved until auto-configuration is fully supported by the Distutils.</p> </dd> </dl> </section> <div class="clearer"></div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h4>Previous topic</h4> <p class="topless"><a href="setupscript.html" title="previous chapter"><span class="section-number">2. </span>Writing the Setup Script</a></p> <h4>Next topic</h4> <p class="topless"><a href="sourcedist.html" title="next chapter"><span class="section-number">4. </span>Creating a Source Distribution</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/distutils/configfile.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3 id="searchlabel">Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search.html" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </div> <script>$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <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="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.18 documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li> <li class="nav-item nav-item-this"><a href=""><span class="section-number">3. </span>Writing the Setup Configuration File</a></li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 1990-2024, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="https://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on December 09, 2024. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 4.3.2. </div> </body> </html>