Edit File: sourcedist.html
<!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>4. Creating a Source Distribution — Python v2.6.6 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: '2.6.6', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python v2.6.6 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 v2.6.6 documentation" href="../index.html" /> <link rel="up" title="Distributing Python Modules" href="index.html" /> <link rel="next" title="5. Creating Built Distributions" href="builtdist.html" /> <link rel="prev" title="3. Writing the Setup Configuration File" href="configfile.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="../modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li> <li class="right" > <a href="builtdist.html" title="5. Creating Built Distributions" accesskey="N">next</a> |</li> <li class="right" > <a href="configfile.html" title="3. Writing the Setup Configuration File" 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 v2.6.6 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="creating-a-source-distribution"> <span id="source-dist"></span><h1>4. Creating a Source Distribution<a class="headerlink" href="#creating-a-source-distribution" title="Permalink to this headline">¶</a></h1> <p>As shown in section <a class="reference external" href="introduction.html#distutils-simple-example"><em>A Simple Example</em></a>, you use the <strong>sdist</strong> command to create a source distribution. In the simplest case,</p> <div class="highlight-python"><pre>python setup.py sdist</pre> </div> <p>(assuming you haven’t specified any <strong>sdist</strong> options in the setup script or config file), <strong>sdist</strong> creates the archive of the default format for the current platform. The default format is a gzip’ed tar file (<tt class="docutils literal"><span class="pre">.tar.gz</span></tt>) on Unix, and ZIP file on Windows.</p> <p>You can specify as many formats as you like using the <em class="xref">--formats</em> option, for example:</p> <div class="highlight-python"><pre>python setup.py sdist --formats=gztar,zip</pre> </div> <p>to create a gzipped tarball and a zip file. The available formats are:</p> <table border="1" class="docutils"> <colgroup> <col width="24%" /> <col width="56%" /> <col width="20%" /> </colgroup> <thead valign="bottom"> <tr><th class="head">Format</th> <th class="head">Description</th> <th class="head">Notes</th> </tr> </thead> <tbody valign="top"> <tr><td><tt class="docutils literal"><span class="pre">zip</span></tt></td> <td>zip file (<tt class="docutils literal"><span class="pre">.zip</span></tt>)</td> <td>(1),(3)</td> </tr> <tr><td><tt class="docutils literal"><span class="pre">gztar</span></tt></td> <td>gzip’ed tar file (<tt class="docutils literal"><span class="pre">.tar.gz</span></tt>)</td> <td>(2),(4)</td> </tr> <tr><td><tt class="docutils literal"><span class="pre">bztar</span></tt></td> <td>bzip2’ed tar file (<tt class="docutils literal"><span class="pre">.tar.bz2</span></tt>)</td> <td>(4)</td> </tr> <tr><td><tt class="docutils literal"><span class="pre">ztar</span></tt></td> <td>compressed tar file (<tt class="docutils literal"><span class="pre">.tar.Z</span></tt>)</td> <td>(4)</td> </tr> <tr><td><tt class="docutils literal"><span class="pre">tar</span></tt></td> <td>tar file (<tt class="docutils literal"><span class="pre">.tar</span></tt>)</td> <td>(4)</td> </tr> </tbody> </table> <p>Notes:</p> <ol class="arabic simple"> <li>default on Windows</li> <li>default on Unix</li> <li>requires either external <strong>zip</strong> utility or <a title="Read and write ZIP-format archive files." class="reference external" href="../library/zipfile.html#module-zipfile"><tt class="xref docutils literal"><span class="pre">zipfile</span></tt></a> module (part of the standard Python library since Python 1.6)</li> <li>requires external utilities: <strong>tar</strong> and possibly one of <strong>gzip</strong>, <strong>bzip2</strong>, or <strong>compress</strong></li> </ol> <div class="section" id="specifying-the-files-to-distribute"> <span id="manifest"></span><h2>4.1. Specifying the files to distribute<a class="headerlink" href="#specifying-the-files-to-distribute" title="Permalink to this headline">¶</a></h2> <p>If you don’t supply an explicit list of files (or instructions on how to generate one), the <strong>sdist</strong> command puts a minimal default set into the source distribution:</p> <ul class="simple"> <li>all Python source files implied by the <em class="xref">py_modules</em> and <em class="xref">packages</em> options</li> <li>all C source files mentioned in the <em class="xref">ext_modules</em> or <em class="xref">libraries</em> options</li> <li>scripts identified by the <em class="xref">scripts</em> option</li> <li>anything that looks like a test script: <tt class="docutils literal"><span class="pre">test/test*.py</span></tt> (currently, the Distutils don’t do anything with test scripts except include them in source distributions, but in the future there will be a standard for testing Python module distributions)</li> <li><tt class="docutils literal"><span class="pre">README.txt</span></tt> (or <tt class="docutils literal"><span class="pre">README</span></tt>), <tt class="docutils literal"><span class="pre">setup.py</span></tt> (or whatever you called your setup script), and <tt class="docutils literal"><span class="pre">setup.cfg</span></tt></li> </ul> <p>Sometimes this is enough, but usually you will want to specify additional files to distribute. The typical way to do this is to write a <em>manifest template</em>, called <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> by default. The manifest template is just a list of instructions for how to generate your manifest file, <tt class="docutils literal"><span class="pre">MANIFEST</span></tt>, which is the exact list of files to include in your source distribution. The <strong>sdist</strong> command processes this template and generates a manifest based on its instructions and what it finds in the filesystem.</p> <p>If you prefer to roll your own manifest file, the format is simple: one filename per line, regular files (or symlinks to them) only. If you do supply your own <tt class="docutils literal"><span class="pre">MANIFEST</span></tt>, you must specify everything: the default set of files described above does not apply in this case.</p> <p>The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils’ own manifest template:</p> <div class="highlight-python"><pre>include *.txt recursive-include examples *.txt *.py prune examples/sample?/build</pre> </div> <p>The meanings should be fairly clear: include all files in the distribution root matching <tt class="docutils literal"><span class="pre">*.txt</span></tt>, all files anywhere under the <tt class="docutils literal"><span class="pre">examples</span></tt> directory matching <tt class="docutils literal"><span class="pre">*.txt</span></tt> or <tt class="docutils literal"><span class="pre">*.py</span></tt>, and exclude all directories matching <tt class="docutils literal"><span class="pre">examples/sample?/build</span></tt>. All of this is done <em>after</em> the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the <em class="xref">--no-defaults</em> option to disable the standard set entirely.) There are several other commands available in the manifest template mini-language; see section <a class="reference external" href="commandref.html#sdist-cmd"><em>Creating a source distribution: the sdist command</em></a>.</p> <p>The order of commands in the manifest template matters: initially, we have the list of default files as described above, and each command in the template adds to or removes from that list of files. Once we have fully processed the manifest template, we remove files that should not be included in the source distribution:</p> <ul class="simple"> <li>all files in the Distutils “build” tree (default <tt class="docutils literal"><span class="pre">build/</span></tt>)</li> <li>all files in directories named <tt class="docutils literal"><span class="pre">RCS</span></tt>, <tt class="docutils literal"><span class="pre">CVS</span></tt>, <tt class="docutils literal"><span class="pre">.svn</span></tt>, <tt class="docutils literal"><span class="pre">.hg</span></tt>, <tt class="docutils literal"><span class="pre">.git</span></tt>, <tt class="docutils literal"><span class="pre">.bzr</span></tt> or <tt class="docutils literal"><span class="pre">_darcs</span></tt></li> </ul> <p>Now we have our complete list of files, which is written to the manifest for future reference, and then used to build the source distribution archive(s).</p> <p>You can disable the default set of included files with the <em class="xref">--no-defaults</em> option, and you can disable the standard exclude set with <em class="xref">--no-prune</em>.</p> <p>Following the Distutils’ own manifest template, let’s trace how the <strong>sdist</strong> command builds the list of files to include in the Distutils source distribution:</p> <ol class="arabic simple"> <li>include all Python source files in the <tt class="docutils literal"><span class="pre">distutils</span></tt> and <tt class="docutils literal"><span class="pre">distutils/command</span></tt> subdirectories (because packages corresponding to those two directories were mentioned in the <em class="xref">packages</em> option in the setup script—see section <a class="reference external" href="setupscript.html#setup-script"><em>Writing the Setup Script</em></a>)</li> <li>include <tt class="docutils literal"><span class="pre">README.txt</span></tt>, <tt class="docutils literal"><span class="pre">setup.py</span></tt>, and <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> (standard files)</li> <li>include <tt class="docutils literal"><span class="pre">test/test*.py</span></tt> (standard files)</li> <li>include <tt class="docutils literal"><span class="pre">*.txt</span></tt> in the distribution root (this will find <tt class="docutils literal"><span class="pre">README.txt</span></tt> a second time, but such redundancies are weeded out later)</li> <li>include anything matching <tt class="docutils literal"><span class="pre">*.txt</span></tt> or <tt class="docutils literal"><span class="pre">*.py</span></tt> in the sub-tree under <tt class="docutils literal"><span class="pre">examples</span></tt>,</li> <li>exclude all files in the sub-trees starting at directories matching <tt class="docutils literal"><span class="pre">examples/sample?/build</span></tt>—this may exclude files included by the previous two steps, so it’s important that the <tt class="docutils literal"><span class="pre">prune</span></tt> command in the manifest template comes after the <tt class="docutils literal"><span class="pre">recursive-include</span></tt> command</li> <li>exclude the entire <tt class="docutils literal"><span class="pre">build</span></tt> tree, and any <tt class="docutils literal"><span class="pre">RCS</span></tt>, <tt class="docutils literal"><span class="pre">CVS</span></tt>, <tt class="docutils literal"><span class="pre">.svn</span></tt>, <tt class="docutils literal"><span class="pre">.hg</span></tt>, <tt class="docutils literal"><span class="pre">.git</span></tt>, <tt class="docutils literal"><span class="pre">.bzr</span></tt> and <tt class="docutils literal"><span class="pre">_darcs</span></tt> directories</li> </ol> <p>Just like in the setup script, file and directory names in the manifest template should always be slash-separated; the Distutils will take care of converting them to the standard representation on your platform. That way, the manifest template is portable across operating systems.</p> </div> <div class="section" id="manifest-related-options"> <span id="manifest-options"></span><h2>4.2. Manifest-related options<a class="headerlink" href="#manifest-related-options" title="Permalink to this headline">¶</a></h2> <p>The normal course of operations for the <strong>sdist</strong> command is as follows:</p> <ul class="simple"> <li>if the manifest file, <tt class="docutils literal"><span class="pre">MANIFEST</span></tt> doesn’t exist, read <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> and create the manifest</li> <li>if neither <tt class="docutils literal"><span class="pre">MANIFEST</span></tt> nor <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> exist, create a manifest with just the default file set</li> <li>if either <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt> or the setup script (<tt class="docutils literal"><span class="pre">setup.py</span></tt>) are more recent than <tt class="docutils literal"><span class="pre">MANIFEST</span></tt>, recreate <tt class="docutils literal"><span class="pre">MANIFEST</span></tt> by reading <tt class="docutils literal"><span class="pre">MANIFEST.in</span></tt></li> <li>use the list of files now in <tt class="docutils literal"><span class="pre">MANIFEST</span></tt> (either just generated or read in) to create the source distribution archive(s)</li> </ul> <p>There are a couple of options that modify this behaviour. First, use the <em class="xref">--no-defaults</em> and <em class="xref">--no-prune</em> to disable the standard “include” and “exclude” sets.</p> <p>Second, you might just want to (re)generate the manifest, but not create a source distribution:</p> <div class="highlight-python"><pre>python setup.py sdist --manifest-only</pre> </div> <p><em class="xref">-o</em> is a shortcut for <em class="xref">--manifest-only</em>.</p> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference external" href="#">4. Creating a Source Distribution</a><ul> <li><a class="reference external" href="#specifying-the-files-to-distribute">4.1. Specifying the files to distribute</a></li> <li><a class="reference external" href="#manifest-related-options">4.2. Manifest-related options</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="configfile.html" title="previous chapter">3. Writing the Setup Configuration File</a></p> <h4>Next topic</h4> <p class="topless"><a href="builtdist.html" title="next chapter">5. Creating Built Distributions</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/sourcedist.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="../modindex.html" title="Global Module Index" >modules</a> |</li> <li class="right" > <a href="builtdist.html" title="5. Creating Built Distributions" >next</a> |</li> <li class="right" > <a href="configfile.html" title="3. Writing the Setup Configuration File" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="../index.html">Python v2.6.6 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 Jul 20, 2011. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.6. </div> </body> </html>
Back to File Manager