add files
This commit is contained in:
Caleb Fontenot
2095
python-3.7.4-docs-html/distutils/apiref.html
Normal file
2095
python-3.7.4-docs-html/distutils/apiref.html
Normal file
File diff suppressed because it is too large
Load Diff
667
python-3.7.4-docs-html/distutils/builtdist.html
Normal file
667
python-3.7.4-docs-html/distutils/builtdist.html
Normal file
@@ -0,0 +1,667 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>5. Creating Built Distributions — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="6. Examples" href="examples.html" />
|
||||
<link rel="prev" title="4. Creating a Source Distribution" href="sourcedist.html" />
|
||||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/builtdist.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="examples.html" title="6. Examples"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="sourcedist.html" title="4. Creating a Source Distribution"
|
||||
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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="creating-built-distributions">
|
||||
<span id="built-dist"></span><h1>5. Creating Built Distributions<a class="headerlink" href="#creating-built-distributions" title="Permalink to this headline">¶</a></h1>
|
||||
<p>A “built distribution” is what you’re probably used to thinking of either as a
|
||||
“binary package” or an “installer” (depending on your background). It’s not
|
||||
necessarily binary, though, because it might contain only Python source code
|
||||
and/or byte-code; and we don’t call it a package, because that word is already
|
||||
spoken for in Python. (And “installer” is a term specific to the world of
|
||||
mainstream desktop systems.)</p>
|
||||
<p>A built distribution is how you make life as easy as possible for installers of
|
||||
your module distribution: for users of RPM-based Linux systems, it’s a binary
|
||||
RPM; for Windows users, it’s an executable installer; for Debian-based Linux
|
||||
users, it’s a Debian package; and so forth. Obviously, no one person will be
|
||||
able to create built distributions for every platform under the sun, so the
|
||||
Distutils are designed to enable module developers to concentrate on their
|
||||
specialty—writing code and creating source distributions—while an
|
||||
intermediary species called <em>packagers</em> springs up to turn source distributions
|
||||
into built distributions for as many platforms as there are packagers.</p>
|
||||
<p>Of course, the module developer could be their own packager; or the packager could
|
||||
be a volunteer “out there” somewhere who has access to a platform which the
|
||||
original developer does not; or it could be software periodically grabbing new
|
||||
source distributions and turning them into built distributions for as many
|
||||
platforms as the software has access to. Regardless of who they are, a packager
|
||||
uses the setup script and the <strong class="command">bdist</strong> command family to generate built
|
||||
distributions.</p>
|
||||
<p>As a simple example, if I run the following command in the Distutils source
|
||||
tree:</p>
|
||||
<div class="highlight-python3 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">bdist</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>then the Distutils builds my module distribution (the Distutils itself in this
|
||||
case), does a “fake” installation (also in the <code class="file docutils literal notranslate"><span class="pre">build</span></code> directory), and
|
||||
creates the default type of built distribution for my platform. The default
|
||||
format for built distributions is a “dumb” tar file on Unix, and a simple
|
||||
executable installer on Windows. (That tar file is considered “dumb” because it
|
||||
has to be unpacked in a specific location to work.)</p>
|
||||
<p>Thus, the above command on a Unix system creates
|
||||
<code class="file docutils literal notranslate"><span class="pre">Distutils-1.0.</span><em><span class="pre">plat</span></em><span class="pre">.tar.gz</span></code>; unpacking this tarball from the right place
|
||||
installs the Distutils just as though you had downloaded the source distribution
|
||||
and run <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>. (The “right place” is either the root of
|
||||
the filesystem or Python’s <code class="file docutils literal notranslate"><em><span class="pre">prefix</span></em></code> directory, depending on the options
|
||||
given to the <strong class="command">bdist_dumb</strong> command; the default is to make dumb
|
||||
distributions relative to <code class="file docutils literal notranslate"><em><span class="pre">prefix</span></em></code>.)</p>
|
||||
<p>Obviously, for pure Python distributions, this isn’t any simpler than just
|
||||
running <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>—but for non-pure distributions, which
|
||||
include extensions that would need to be compiled, it can mean the difference
|
||||
between someone being able to use your extensions or not. And creating “smart”
|
||||
built distributions, such as an RPM package or an executable installer for
|
||||
Windows, is far more convenient for users even if your distribution doesn’t
|
||||
include any extensions.</p>
|
||||
<p>The <strong class="command">bdist</strong> command has a <code class="xref std std-option docutils literal notranslate"><span class="pre">--formats</span></code> option, similar to the
|
||||
<strong class="command">sdist</strong> command, which you can use to select the types of built
|
||||
distribution to generate: for example,</p>
|
||||
<div class="highlight-python3 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">bdist</span> <span class="o">--</span><span class="nb">format</span><span class="o">=</span><span class="nb">zip</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>would, when run on a Unix system, create
|
||||
<code class="file docutils literal notranslate"><span class="pre">Distutils-1.0.</span><em><span class="pre">plat</span></em><span class="pre">.zip</span></code>—again, this archive would be unpacked
|
||||
from the root directory to install the Distutils.</p>
|
||||
<p>The available formats for built distributions are:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 25%" />
|
||||
<col style="width: 58%" />
|
||||
<col style="width: 17%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Format</p></th>
|
||||
<th class="head"><p>Description</p></th>
|
||||
<th class="head"><p>Notes</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">gztar</span></code></p></td>
|
||||
<td><p>gzipped tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.gz</span></code>)</p></td>
|
||||
<td><p>(1)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">bztar</span></code></p></td>
|
||||
<td><p>bzipped tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.bz2</span></code>)</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">xztar</span></code></p></td>
|
||||
<td><p>xzipped tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.xz</span></code>)</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">ztar</span></code></p></td>
|
||||
<td><p>compressed tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.Z</span></code>)</p></td>
|
||||
<td><p>(3)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">tar</span></code></p></td>
|
||||
<td><p>tar file (<code class="file docutils literal notranslate"><span class="pre">.tar</span></code>)</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">zip</span></code></p></td>
|
||||
<td><p>zip file (<code class="file docutils literal notranslate"><span class="pre">.zip</span></code>)</p></td>
|
||||
<td><p>(2),(4)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">rpm</span></code></p></td>
|
||||
<td><p>RPM</p></td>
|
||||
<td><p>(5)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">pkgtool</span></code></p></td>
|
||||
<td><p>Solaris <strong class="program">pkgtool</strong></p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">sdux</span></code></p></td>
|
||||
<td><p>HP-UX <strong class="program">swinstall</strong></p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">wininst</span></code></p></td>
|
||||
<td><p>self-extracting ZIP file for
|
||||
Windows</p></td>
|
||||
<td><p>(4)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">msi</span></code></p></td>
|
||||
<td><p>Microsoft Installer.</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for the <code class="docutils literal notranslate"><span class="pre">xztar</span></code> format.</p>
|
||||
</div>
|
||||
<p>Notes:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>default on Unix</p></li>
|
||||
<li><p>default on Windows</p></li>
|
||||
<li><p>requires external <strong class="program">compress</strong> utility.</p></li>
|
||||
<li><p>requires either external <strong class="program">zip</strong> utility or <a class="reference internal" href="../library/zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> module (part
|
||||
of the standard Python library since Python 1.6)</p></li>
|
||||
<li><p>requires external <strong class="program">rpm</strong> utility, version 3.0.4 or better (use <code class="docutils literal notranslate"><span class="pre">rpm</span>
|
||||
<span class="pre">--version</span></code> to find out which version you have)</p></li>
|
||||
</ol>
|
||||
<p>You don’t have to use the <strong class="command">bdist</strong> command with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--formats</span></code>
|
||||
option; you can also use the command that directly implements the format you’re
|
||||
interested in. Some of these <strong class="command">bdist</strong> “sub-commands” actually generate
|
||||
several similar formats; for instance, the <strong class="command">bdist_dumb</strong> command
|
||||
generates all the “dumb” archive formats (<code class="docutils literal notranslate"><span class="pre">tar</span></code>, <code class="docutils literal notranslate"><span class="pre">gztar</span></code>, <code class="docutils literal notranslate"><span class="pre">bztar</span></code>,
|
||||
<code class="docutils literal notranslate"><span class="pre">xztar</span></code>, <code class="docutils literal notranslate"><span class="pre">ztar</span></code>, and <code class="docutils literal notranslate"><span class="pre">zip</span></code>), and <strong class="command">bdist_rpm</strong> generates both
|
||||
binary and source RPMs. The <strong class="command">bdist</strong> sub-commands, and the formats
|
||||
generated by each, are:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 41%" />
|
||||
<col style="width: 59%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Command</p></th>
|
||||
<th class="head"><p>Formats</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p><strong class="command">bdist_dumb</strong></p></td>
|
||||
<td><p>tar, gztar, bztar, xztar, ztar, zip</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><strong class="command">bdist_rpm</strong></p></td>
|
||||
<td><p>rpm, srpm</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><strong class="command">bdist_wininst</strong></p></td>
|
||||
<td><p>wininst</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><strong class="command">bdist_msi</strong></p></td>
|
||||
<td><p>msi</p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The following sections give details on the individual <strong class="command">bdist_*</strong>
|
||||
commands.</p>
|
||||
<div class="section" id="creating-rpm-packages">
|
||||
<span id="creating-rpms"></span><h2>5.1. Creating RPM packages<a class="headerlink" href="#creating-rpm-packages" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The RPM format is used by many popular Linux distributions, including Red Hat,
|
||||
SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux
|
||||
distributions) is your usual environment, creating RPM packages for other users
|
||||
of that same distribution is trivial. Depending on the complexity of your module
|
||||
distribution and differences between Linux distributions, you may also be able
|
||||
to create RPMs that work on different RPM-based distributions.</p>
|
||||
<p>The usual way to create an RPM of your module distribution is to run the
|
||||
<strong class="command">bdist_rpm</strong> command:</p>
|
||||
<div class="highlight-python3 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">bdist_rpm</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>or the <strong class="command">bdist</strong> command with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--format</span></code> option:</p>
|
||||
<div class="highlight-python3 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">bdist</span> <span class="o">--</span><span class="n">formats</span><span class="o">=</span><span class="n">rpm</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The former allows you to specify RPM-specific options; the latter allows you to
|
||||
easily specify multiple formats in one run. If you need to do both, you can
|
||||
explicitly specify multiple <strong class="command">bdist_*</strong> commands and their options:</p>
|
||||
<div class="highlight-python3 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">bdist_rpm</span> <span class="o">--</span><span class="n">packager</span><span class="o">=</span><span class="s2">"John Doe <jdoe@example.org>"</span> \
|
||||
<span class="n">bdist_wininst</span> <span class="o">--</span><span class="n">target</span><span class="o">-</span><span class="n">version</span><span class="o">=</span><span class="s2">"2.0"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Creating RPM packages is driven by a <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file, much as using the
|
||||
Distutils is driven by the setup script. To make your life easier, the
|
||||
<strong class="command">bdist_rpm</strong> command normally creates a <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file based on the
|
||||
information you supply in the setup script, on the command line, and in any
|
||||
Distutils configuration files. Various options and sections in the
|
||||
<code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file are derived from options in the setup script as follows:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 48%" />
|
||||
<col style="width: 52%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>RPM <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file option or section</p></th>
|
||||
<th class="head"><p>Distutils setup script option</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p>Name</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">name</span></code></p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Summary (in preamble)</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">description</span></code></p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Version</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">version</span></code></p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Vendor</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">author</span></code> and <code class="docutils literal notranslate"><span class="pre">author_email</span></code>,
|
||||
or — & <code class="docutils literal notranslate"><span class="pre">maintainer</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">maintainer_email</span></code></p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Copyright</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">license</span></code></p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Url</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">url</span></code></p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>%description (section)</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">long_description</span></code></p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Additionally, there are many options in <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> files that don’t have
|
||||
corresponding options in the setup script. Most of these are handled through
|
||||
options to the <strong class="command">bdist_rpm</strong> command as follows:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 36%" />
|
||||
<col style="width: 34%" />
|
||||
<col style="width: 29%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>RPM <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file option
|
||||
or section</p></th>
|
||||
<th class="head"><p><strong class="command">bdist_rpm</strong> option</p></th>
|
||||
<th class="head"><p>default value</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p>Release</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">release</span></code></p></td>
|
||||
<td><p>“1”</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Group</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">group</span></code></p></td>
|
||||
<td><p>“Development/Libraries”</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Vendor</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">vendor</span></code></p></td>
|
||||
<td><p>(see above)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Packager</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">packager</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Provides</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">provides</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Requires</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">requires</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Conflicts</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">conflicts</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>Obsoletes</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">obsoletes</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Distribution</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">distribution_name</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p>BuildRequires</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">build_requires</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p>Icon</p></td>
|
||||
<td><p><code class="docutils literal notranslate"><span class="pre">icon</span></code></p></td>
|
||||
<td><p>(none)</p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Obviously, supplying even a few of these options on the command-line would be
|
||||
tedious and error-prone, so it’s usually best to put them in the setup
|
||||
configuration file, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>—see section <a class="reference internal" href="configfile.html#setup-config"><span class="std std-ref">Writing the Setup Configuration File</span></a>. If
|
||||
you distribute or package many Python module distributions, you might want to
|
||||
put options that apply to all of them in your personal Distutils configuration
|
||||
file (<code class="file docutils literal notranslate"><span class="pre">~/.pydistutils.cfg</span></code>). If you want to temporarily disable
|
||||
this file, you can pass the <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-user-cfg</span></code> option to <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
|
||||
<p>There are three steps to building a binary RPM package, all of which are
|
||||
handled automatically by the Distutils:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>create a <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file, which describes the package (analogous to the
|
||||
Distutils setup script; in fact, much of the information in the setup script
|
||||
winds up in the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file)</p></li>
|
||||
<li><p>create the source RPM</p></li>
|
||||
<li><p>create the “binary” RPM (which may or may not contain binary code, depending
|
||||
on whether your module distribution contains Python extensions)</p></li>
|
||||
</ol>
|
||||
<p>Normally, RPM bundles the last two steps together; when you use the Distutils,
|
||||
all three steps are typically bundled together.</p>
|
||||
<p>If you wish, you can separate these three steps. You can use the
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">--spec-only</span></code> option to make <strong class="command">bdist_rpm</strong> just create the
|
||||
<code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file and exit; in this case, the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file will be
|
||||
written to the “distribution directory”—normally <code class="file docutils literal notranslate"><span class="pre">dist/</span></code>, but
|
||||
customizable with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--dist-dir</span></code> option. (Normally, the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code>
|
||||
file winds up deep in the “build tree,” in a temporary directory created by
|
||||
<strong class="command">bdist_rpm</strong>.)</p>
|
||||
</div>
|
||||
<div class="section" id="creating-windows-installers">
|
||||
<span id="creating-wininst"></span><h2>5.2. Creating Windows Installers<a class="headerlink" href="#creating-windows-installers" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Executable installers are the natural format for binary distributions on
|
||||
Windows. They display a nice graphical user interface, display some information
|
||||
about the module distribution to be installed taken from the metadata in the
|
||||
setup script, let the user select a few options, and start or cancel the
|
||||
installation.</p>
|
||||
<p>Since the metadata is taken from the setup script, creating Windows installers
|
||||
is usually as easy as running:</p>
|
||||
<div class="highlight-python3 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">bdist_wininst</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>or the <strong class="command">bdist</strong> command with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--formats</span></code> option:</p>
|
||||
<div class="highlight-python3 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">bdist</span> <span class="o">--</span><span class="n">formats</span><span class="o">=</span><span class="n">wininst</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you have a pure module distribution (only containing pure Python modules and
|
||||
packages), the resulting installer will be version independent and have a name
|
||||
like <code class="file docutils literal notranslate"><span class="pre">foo-1.0.win32.exe</span></code>. Note that creating <code class="docutils literal notranslate"><span class="pre">wininst</span></code> binary
|
||||
distributions in only supported on Windows systems.</p>
|
||||
<p>If you have a non-pure distribution, the extensions can only be created on a
|
||||
Windows platform, and will be Python version dependent. The installer filename
|
||||
will reflect this and now has the form <code class="file docutils literal notranslate"><span class="pre">foo-1.0.win32-py2.0.exe</span></code>. You
|
||||
have to create a separate installer for every Python version you want to
|
||||
support.</p>
|
||||
<p>The installer will try to compile pure modules into <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> after installation
|
||||
on the target system in normal and optimizing mode. If you don’t want this to
|
||||
happen for some reason, you can run the <strong class="command">bdist_wininst</strong> command with
|
||||
the <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-target-compile</span></code> and/or the <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-target-optimize</span></code>
|
||||
option.</p>
|
||||
<p>By default the installer will display the cool “Python Powered” logo when it is
|
||||
run, but you can also supply your own 152x261 bitmap which must be a Windows
|
||||
<code class="file docutils literal notranslate"><span class="pre">.bmp</span></code> file with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--bitmap</span></code> option.</p>
|
||||
<p>The installer will also display a large title on the desktop background window
|
||||
when it is run, which is constructed from the name of your distribution and the
|
||||
version number. This can be changed to another text by using the
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">--title</span></code> option.</p>
|
||||
<p>The installer file will be written to the “distribution directory” — normally
|
||||
<code class="file docutils literal notranslate"><span class="pre">dist/</span></code>, but customizable with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--dist-dir</span></code> option.</p>
|
||||
</div>
|
||||
<div class="section" id="cross-compiling-on-windows">
|
||||
<span id="cross-compile-windows"></span><h2>5.3. Cross-compiling on Windows<a class="headerlink" href="#cross-compiling-on-windows" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Starting with Python 2.6, distutils is capable of cross-compiling between
|
||||
Windows platforms. In practice, this means that with the correct tools
|
||||
installed, you can use a 32bit version of Windows to create 64bit extensions
|
||||
and vice-versa.</p>
|
||||
<p>To build for an alternate platform, specify the <code class="xref std std-option docutils literal notranslate"><span class="pre">--plat-name</span></code> option
|
||||
to the build command. Valid values are currently ‘win32’, and ‘win-amd64’.
|
||||
For example, on a 32bit version of Windows, you could execute:</p>
|
||||
<div class="highlight-python3 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</span> <span class="o">--</span><span class="n">plat</span><span class="o">-</span><span class="n">name</span><span class="o">=</span><span class="n">win</span><span class="o">-</span><span class="n">amd64</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>to build a 64bit version of your extension. The Windows Installers also
|
||||
support this option, so the command:</p>
|
||||
<div class="highlight-python3 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</span> <span class="o">--</span><span class="n">plat</span><span class="o">-</span><span class="n">name</span><span class="o">=</span><span class="n">win</span><span class="o">-</span><span class="n">amd64</span> <span class="n">bdist_wininst</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>would create a 64bit installation executable on your 32bit version of Windows.</p>
|
||||
<p>To cross-compile, you must download the Python source code and cross-compile
|
||||
Python itself for the platform you are targeting - it is not possible from a
|
||||
binary installation of Python (as the .lib etc file for other platforms are
|
||||
not included.) In practice, this means the user of a 32 bit operating
|
||||
system will need to use Visual Studio 2008 to open the
|
||||
<code class="file docutils literal notranslate"><span class="pre">PCbuild/PCbuild.sln</span></code> solution in the Python source tree and build the
|
||||
“x64” configuration of the ‘pythoncore’ project before cross-compiling
|
||||
extensions is possible.</p>
|
||||
<p>Note that by default, Visual Studio 2008 does not install 64bit compilers or
|
||||
tools. You may need to reexecute the Visual Studio setup process and select
|
||||
these tools (using Control Panel->[Add/Remove] Programs is a convenient way to
|
||||
check or modify your existing install.)</p>
|
||||
<div class="section" id="the-postinstallation-script">
|
||||
<span id="postinstallation-script"></span><h3>5.3.1. The Postinstallation script<a class="headerlink" href="#the-postinstallation-script" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Starting with Python 2.3, a postinstallation script can be specified with the
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">--install-script</span></code> option. The basename of the script must be
|
||||
specified, and the script filename must also be listed in the scripts argument
|
||||
to the setup function.</p>
|
||||
<p>This script will be run at installation time on the target system after all the
|
||||
files have been copied, with <code class="docutils literal notranslate"><span class="pre">argv[1]</span></code> set to <code class="xref std std-option docutils literal notranslate"><span class="pre">-install</span></code>, and again at
|
||||
uninstallation time before the files are removed with <code class="docutils literal notranslate"><span class="pre">argv[1]</span></code> set to
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">-remove</span></code>.</p>
|
||||
<p>The installation script runs embedded in the windows installer, every output
|
||||
(<code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code>, <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>) is redirected into a buffer and will be
|
||||
displayed in the GUI after the script has finished.</p>
|
||||
<p>Some functions especially useful in this context are available as additional
|
||||
built-in functions in the installation script.</p>
|
||||
<dl class="function">
|
||||
<dt id="directory_created">
|
||||
<code class="descname">directory_created</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#directory_created" title="Permalink to this definition">¶</a></dt>
|
||||
<dt id="file_created">
|
||||
<code class="descname">file_created</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#file_created" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><p>These functions should be called when a directory or file is created by the
|
||||
postinstall script at installation time. It will register <em>path</em> with the
|
||||
uninstaller, so that it will be removed when the distribution is uninstalled.
|
||||
To be safe, directories are only removed if they are empty.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="function">
|
||||
<dt id="get_special_folder_path">
|
||||
<code class="descname">get_special_folder_path</code><span class="sig-paren">(</span><em>csidl_string</em><span class="sig-paren">)</span><a class="headerlink" href="#get_special_folder_path" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><p>This function can be used to retrieve special folder locations on Windows like
|
||||
the Start Menu or the Desktop. It returns the full path to the folder.
|
||||
<em>csidl_string</em> must be one of the following strings:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="s2">"CSIDL_APPDATA"</span>
|
||||
|
||||
<span class="s2">"CSIDL_COMMON_STARTMENU"</span>
|
||||
<span class="s2">"CSIDL_STARTMENU"</span>
|
||||
|
||||
<span class="s2">"CSIDL_COMMON_DESKTOPDIRECTORY"</span>
|
||||
<span class="s2">"CSIDL_DESKTOPDIRECTORY"</span>
|
||||
|
||||
<span class="s2">"CSIDL_COMMON_STARTUP"</span>
|
||||
<span class="s2">"CSIDL_STARTUP"</span>
|
||||
|
||||
<span class="s2">"CSIDL_COMMON_PROGRAMS"</span>
|
||||
<span class="s2">"CSIDL_PROGRAMS"</span>
|
||||
|
||||
<span class="s2">"CSIDL_FONTS"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the folder cannot be retrieved, <a class="reference internal" href="../library/exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised.</p>
|
||||
<p>Which folders are available depends on the exact Windows version, and probably
|
||||
also the configuration. For details refer to Microsoft’s documentation of the
|
||||
<code class="xref c c-func docutils literal notranslate"><span class="pre">SHGetSpecialFolderPath()</span></code> function.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="function">
|
||||
<dt id="create_shortcut">
|
||||
<code class="descname">create_shortcut</code><span class="sig-paren">(</span><em>target</em>, <em>description</em>, <em>filename</em><span class="optional">[</span>, <em>arguments</em><span class="optional">[</span>, <em>workdir</em><span class="optional">[</span>, <em>iconpath</em><span class="optional">[</span>, <em>iconindex</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#create_shortcut" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><p>This function creates a shortcut. <em>target</em> is the path to the program to be
|
||||
started by the shortcut. <em>description</em> is the description of the shortcut.
|
||||
<em>filename</em> is the title of the shortcut that the user will see. <em>arguments</em>
|
||||
specifies the command line arguments, if any. <em>workdir</em> is the working directory
|
||||
for the program. <em>iconpath</em> is the file containing the icon for the shortcut,
|
||||
and <em>iconindex</em> is the index of the icon in the file <em>iconpath</em>. Again, for
|
||||
details consult the Microsoft documentation for the <code class="xref py py-class docutils literal notranslate"><span class="pre">IShellLink</span></code>
|
||||
interface.</p>
|
||||
</dd></dl>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="vista-user-access-control-uac">
|
||||
<h2>5.4. Vista User Access Control (UAC)<a class="headerlink" href="#vista-user-access-control-uac" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Starting with Python 2.6, bdist_wininst supports a <code class="xref std std-option docutils literal notranslate"><span class="pre">--user-access-control</span></code>
|
||||
option. The default is ‘none’ (meaning no UAC handling is done), and other
|
||||
valid values are ‘auto’ (meaning prompt for UAC elevation if Python was
|
||||
installed for all users) and ‘force’ (meaning always prompt for elevation).</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">5. Creating Built Distributions</a><ul>
|
||||
<li><a class="reference internal" href="#creating-rpm-packages">5.1. Creating RPM packages</a></li>
|
||||
<li><a class="reference internal" href="#creating-windows-installers">5.2. Creating Windows Installers</a></li>
|
||||
<li><a class="reference internal" href="#cross-compiling-on-windows">5.3. Cross-compiling on Windows</a><ul>
|
||||
<li><a class="reference internal" href="#the-postinstallation-script">5.3.1. The Postinstallation script</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#vista-user-access-control-uac">5.4. Vista User Access Control (UAC)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h4>Previous topic</h4>
|
||||
<p class="topless"><a href="sourcedist.html"
|
||||
title="previous chapter">4. Creating a Source Distribution</a></p>
|
||||
<h4>Next topic</h4>
|
||||
<p class="topless"><a href="examples.html"
|
||||
title="next chapter">6. Examples</a></p>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/builtdist.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="examples.html" title="6. Examples"
|
||||
>next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="sourcedist.html" title="4. Creating a Source Distribution"
|
||||
>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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
263
python-3.7.4-docs-html/distutils/commandref.html
Normal file
263
python-3.7.4-docs-html/distutils/commandref.html
Normal file
@@ -0,0 +1,263 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>8. Command Reference — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="9. API Reference" href="apiref.html" />
|
||||
<link rel="prev" title="7. Extending Distutils" href="extending.html" />
|
||||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/commandref.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="apiref.html" title="9. API Reference"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="extending.html" title="7. Extending Distutils"
|
||||
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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="command-reference">
|
||||
<span id="reference"></span><h1>8. Command Reference<a class="headerlink" href="#command-reference" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="section" id="installing-modules-the-install-command-family">
|
||||
<span id="install-cmd"></span><h2>8.1. Installing modules: the <strong class="command">install</strong> command family<a class="headerlink" href="#installing-modules-the-install-command-family" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The install command ensures that the build commands have been run and then runs
|
||||
the subcommands <strong class="command">install_lib</strong>, <strong class="command">install_data</strong> and
|
||||
<strong class="command">install_scripts</strong>.</p>
|
||||
<div class="section" id="install-data">
|
||||
<span id="install-data-cmd"></span><h3>8.1.1. <strong class="command">install_data</strong><a class="headerlink" href="#install-data" title="Permalink to this headline">¶</a></h3>
|
||||
<p>This command installs all data files provided with the distribution.</p>
|
||||
</div>
|
||||
<div class="section" id="install-scripts">
|
||||
<span id="install-scripts-cmd"></span><h3>8.1.2. <strong class="command">install_scripts</strong><a class="headerlink" href="#install-scripts" title="Permalink to this headline">¶</a></h3>
|
||||
<p>This command installs all (Python) scripts in the distribution.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="creating-a-source-distribution-the-sdist-command">
|
||||
<span id="sdist-cmd"></span><h2>8.2. Creating a source distribution: the <strong class="command">sdist</strong> command<a class="headerlink" href="#creating-a-source-distribution-the-sdist-command" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The manifest template commands are:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 48%" />
|
||||
<col style="width: 52%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Command</p></th>
|
||||
<th class="head"><p>Description</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p><strong class="command">include pat1 pat2 ...</strong></p></td>
|
||||
<td><p>include all files matching any of the listed
|
||||
patterns</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><strong class="command">exclude pat1 pat2 ...</strong></p></td>
|
||||
<td><p>exclude all files matching any of the listed
|
||||
patterns</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><strong class="command">recursive-include dir pat1 pat2
|
||||
...</strong></p></td>
|
||||
<td><p>include all files under <em>dir</em> matching any of
|
||||
the listed patterns</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><strong class="command">recursive-exclude dir pat1 pat2
|
||||
...</strong></p></td>
|
||||
<td><p>exclude all files under <em>dir</em> matching any of
|
||||
the listed patterns</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><strong class="command">global-include pat1 pat2 ...</strong></p></td>
|
||||
<td><p>include all files anywhere in the source tree
|
||||
matching — & any of the listed patterns</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><strong class="command">global-exclude pat1 pat2 ...</strong></p></td>
|
||||
<td><p>exclude all files anywhere in the source tree
|
||||
matching — & any of the listed patterns</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><strong class="command">prune dir</strong></p></td>
|
||||
<td><p>exclude all files under <em>dir</em></p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><strong class="command">graft dir</strong></p></td>
|
||||
<td><p>include all files under <em>dir</em></p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The patterns here are Unix-style “glob” patterns: <code class="docutils literal notranslate"><span class="pre">*</span></code> matches any sequence of
|
||||
regular filename characters, <code class="docutils literal notranslate"><span class="pre">?</span></code> matches any single regular filename
|
||||
character, and <code class="docutils literal notranslate"><span class="pre">[range]</span></code> matches any of the characters in <em>range</em> (e.g.,
|
||||
<code class="docutils literal notranslate"><span class="pre">a-z</span></code>, <code class="docutils literal notranslate"><span class="pre">a-zA-Z</span></code>, <code class="docutils literal notranslate"><span class="pre">a-f0-9_.</span></code>). The definition of “regular filename
|
||||
character” is platform-specific: on Unix it is anything except slash; on Windows
|
||||
anything except backslash or colon.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">8. Command Reference</a><ul>
|
||||
<li><a class="reference internal" href="#installing-modules-the-install-command-family">8.1. Installing modules: the <strong class="command">install</strong> command family</a><ul>
|
||||
<li><a class="reference internal" href="#install-data">8.1.1. <strong class="command">install_data</strong></a></li>
|
||||
<li><a class="reference internal" href="#install-scripts">8.1.2. <strong class="command">install_scripts</strong></a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#creating-a-source-distribution-the-sdist-command">8.2. Creating a source distribution: the <strong class="command">sdist</strong> command</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h4>Previous topic</h4>
|
||||
<p class="topless"><a href="extending.html"
|
||||
title="previous chapter">7. Extending Distutils</a></p>
|
||||
<h4>Next topic</h4>
|
||||
<p class="topless"><a href="apiref.html"
|
||||
title="next chapter">9. API Reference</a></p>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/commandref.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="apiref.html" title="9. API Reference"
|
||||
>next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="extending.html" title="7. Extending Distutils"
|
||||
>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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
294
python-3.7.4-docs-html/distutils/configfile.html
Normal file
294
python-3.7.4-docs-html/distutils/configfile.html
Normal file
@@ -0,0 +1,294 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>3. Writing the Setup Configuration File — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="https://docs.python.org/3/distutils/configfile.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<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, <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-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[command]</span>
|
||||
<span class="na">option</span><span class="o">=</span><span class="s">value</span>
|
||||
<span class="na">...</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-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python setup.py --help build_ext
|
||||
<span class="go">[...]</span>
|
||||
<span class="go">Options for 'build_ext' command:</span>
|
||||
<span class="go"> --build-lib (-b) directory for compiled extension modules</span>
|
||||
<span class="go"> --build-temp (-t) directory for temporary files (build by-products)</span>
|
||||
<span class="go"> --inplace (-i) ignore build-lib and put compiled extensions into the</span>
|
||||
<span class="go"> source directory alongside your pure Python modules</span>
|
||||
<span class="go"> --include-dirs (-I) list of directories to search for header files</span>
|
||||
<span class="go"> --define (-D) C preprocessor macros to define</span>
|
||||
<span class="go"> --undef (-U) C preprocessor macros to undefine</span>
|
||||
<span class="go"> --swig-opts list of SWIG command line options</span>
|
||||
<span class="go">[...]</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-sh notranslate"><div class="highlight"><pre><span></span>python setup.py build_ext --inplace
|
||||
</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-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[build_ext]</span>
|
||||
<span class="na">inplace</span><span class="o">=</span><span class="s">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-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[bdist_rpm]</span>
|
||||
<span class="na">release</span> <span class="o">=</span> <span class="s">1</span>
|
||||
<span class="na">packager</span> <span class="o">=</span> <span class="s">Greg Ward <gward@python.net></span>
|
||||
<span class="na">doc_files</span> <span class="o">=</span> <span class="s">CHANGES.txt</span>
|
||||
<span class="s"> README.txt</span>
|
||||
<span class="s"> USAGE.txt</span>
|
||||
<span class="s"> doc/</span>
|
||||
<span class="s"> examples/</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>
|
||||
</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">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>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/configfile.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
489
python-3.7.4-docs-html/distutils/examples.html
Normal file
489
python-3.7.4-docs-html/distutils/examples.html
Normal file
@@ -0,0 +1,489 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>6. Examples — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="7. Extending Distutils" href="extending.html" />
|
||||
<link rel="prev" title="5. Creating Built Distributions" href="builtdist.html" />
|
||||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/examples.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="extending.html" title="7. Extending Distutils"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="builtdist.html" title="5. Creating Built Distributions"
|
||||
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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="examples">
|
||||
<span id="id1"></span><h1>6. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h1>
|
||||
<p>This chapter provides a number of basic examples to help get started with
|
||||
distutils. Additional information about using distutils can be found in the
|
||||
Distutils Cookbook.</p>
|
||||
<div class="admonition seealso">
|
||||
<p class="admonition-title">See also</p>
|
||||
<dl class="simple">
|
||||
<dt><a class="reference external" href="https://wiki.python.org/moin/Distutils/Cookbook">Distutils Cookbook</a></dt><dd><p>Collection of recipes showing how to achieve more control over distutils.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section" id="pure-python-distribution-by-module">
|
||||
<span id="pure-mod"></span><h2>6.1. Pure Python distribution (by module)<a class="headerlink" href="#pure-python-distribution-by-module" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you’re just distributing a couple of modules, especially if they don’t live
|
||||
in a particular package, you can specify them individually using the
|
||||
<code class="docutils literal notranslate"><span class="pre">py_modules</span></code> option in the setup script.</p>
|
||||
<p>In the simplest case, you’ll have two files to worry about: a setup script and
|
||||
the single module you’re distributing, <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code> in this example:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>(In all diagrams in this section, <em><root></em> will refer to the distribution root
|
||||
directory.) A minimal setup script to describe this situation would be:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Note that the name of the distribution is specified independently with the
|
||||
<code class="docutils literal notranslate"><span class="pre">name</span></code> option, and there’s no rule that says it has to be the same as
|
||||
the name of the sole module in the distribution (although that’s probably a good
|
||||
convention to follow). However, the distribution name is used to generate
|
||||
filenames, so you should stick to letters, digits, underscores, and hyphens.</p>
|
||||
<p>Since <code class="docutils literal notranslate"><span class="pre">py_modules</span></code> is a list, you can of course specify multiple
|
||||
modules, eg. if you’re distributing modules <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">bar</span></code>, your
|
||||
setup might look like this:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>and the setup script might be</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can put module source files into another directory, but if you have enough
|
||||
modules to do that, it’s probably easier to specify modules by package rather
|
||||
than listing them individually.</p>
|
||||
</div>
|
||||
<div class="section" id="pure-python-distribution-by-package">
|
||||
<span id="pure-pkg"></span><h2>6.2. Pure Python distribution (by package)<a class="headerlink" href="#pure-python-distribution-by-package" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you have more than a couple of modules to distribute, especially if they are
|
||||
in multiple packages, it’s probably easier to specify whole packages rather than
|
||||
individual modules. This works even if your modules are not in a package; you
|
||||
can just tell the Distutils to process modules from the root package, and that
|
||||
works the same as any other package (except that you don’t have to have an
|
||||
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> file).</p>
|
||||
<p>The setup script from the last example could also be written as</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">''</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>(The empty string stands for the root package.)</p>
|
||||
<p>If those two files are moved into a subdirectory, but remain in the root
|
||||
package, e.g.:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">src</span><span class="o">/</span> <span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>then you would still specify the root package, but you have to tell the
|
||||
Distutils where source files in the root package live:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">''</span><span class="p">:</span> <span class="s1">'src'</span><span class="p">},</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">''</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>More typically, though, you will want to distribute multiple modules in the same
|
||||
package (or in sub-packages). For example, if the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">bar</span></code>
|
||||
modules belong in package <code class="xref py py-mod docutils literal notranslate"><span class="pre">foobar</span></code>, one way to layout your source tree is</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foobar</span><span class="o">/</span>
|
||||
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This is in fact the default layout expected by the Distutils, and the one that
|
||||
requires the least work to describe in your setup script:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you want to put modules in directories not named for their package, then you
|
||||
need to use the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> option again. For example, if the
|
||||
<code class="file docutils literal notranslate"><span class="pre">src</span></code> directory holds modules in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foobar</span></code> package:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">src</span><span class="o">/</span>
|
||||
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>an appropriate setup script would be</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">'foobar'</span><span class="p">:</span> <span class="s1">'src'</span><span class="p">},</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Or, you might put modules from your main package right in the distribution
|
||||
root:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>in which case your setup script would be</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">'foobar'</span><span class="p">:</span> <span class="s1">''</span><span class="p">},</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>(The empty string also stands for the current directory.)</p>
|
||||
<p>If you have sub-packages, they must be explicitly listed in <code class="docutils literal notranslate"><span class="pre">packages</span></code>,
|
||||
but any entries in <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> automatically extend to sub-packages.
|
||||
(In other words, the Distutils does <em>not</em> scan your source tree, trying to
|
||||
figure out which directories correspond to Python packages by looking for
|
||||
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> files.) Thus, if the default layout grows a sub-package:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foobar</span><span class="o">/</span>
|
||||
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">subfoo</span><span class="o">/</span>
|
||||
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">blah</span><span class="o">.</span><span class="n">py</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>then the corresponding setup script would be</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">,</span> <span class="s1">'foobar.subfoo'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="single-extension-module">
|
||||
<span id="single-ext"></span><h2>6.3. Single extension module<a class="headerlink" href="#single-extension-module" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Extension modules are specified using the <code class="docutils literal notranslate"><span class="pre">ext_modules</span></code> option.
|
||||
<code class="docutils literal notranslate"><span class="pre">package_dir</span></code> has no effect on where extension source files are found;
|
||||
it only affects the source for pure Python modules. The simplest case, a
|
||||
single extension module in a single C source file, is:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
|
||||
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">c</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> extension belongs in the root package, the setup script for
|
||||
this could be</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="kn">from</span> <span class="nn">distutils.extension</span> <span class="k">import</span> <span class="n">Extension</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the extension actually belongs in a package, say <code class="xref py py-mod docutils literal notranslate"><span class="pre">foopkg</span></code>, then</p>
|
||||
<p>With exactly the same source tree layout, this extension can be put in the
|
||||
<code class="xref py py-mod docutils literal notranslate"><span class="pre">foopkg</span></code> package simply by changing the name of the extension:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="kn">from</span> <span class="nn">distutils.extension</span> <span class="k">import</span> <span class="n">Extension</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foopkg.foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="checking-a-package">
|
||||
<h2>6.4. Checking a package<a class="headerlink" href="#checking-a-package" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">check</span></code> command allows you to verify if your package meta-data
|
||||
meet the minimum requirements to build a distribution.</p>
|
||||
<p>To run it, just call it using your <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> script. If something is
|
||||
missing, <code class="docutils literal notranslate"><span class="pre">check</span></code> will display a warning.</p>
|
||||
<p>Let’s take an example with a simple script:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Running the <code class="docutils literal notranslate"><span class="pre">check</span></code> command will display some warnings:</p>
|
||||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python setup.py check
|
||||
<span class="go">running check</span>
|
||||
<span class="go">warning: check: missing required meta-data: version, url</span>
|
||||
<span class="go">warning: check: missing meta-data: either (author and author_email) or</span>
|
||||
<span class="go"> (maintainer and maintainer_email) must be supplied</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you use the reStructuredText syntax in the <code class="docutils literal notranslate"><span class="pre">long_description</span></code> field and
|
||||
<a class="reference external" href="http://docutils.sourceforge.net">docutils</a> is installed you can check if the syntax is fine with the
|
||||
<code class="docutils literal notranslate"><span class="pre">check</span></code> command, using the <code class="docutils literal notranslate"><span class="pre">restructuredtext</span></code> option.</p>
|
||||
<p>For example, if the <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> script is changed like this:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
|
||||
<span class="n">desc</span> <span class="o">=</span> <span class="s2">"""</span><span class="se">\</span>
|
||||
<span class="s2">My description</span>
|
||||
<span class="s2">==============</span>
|
||||
|
||||
<span class="s2">This is the description of the ``foobar`` package.</span>
|
||||
<span class="s2">"""</span>
|
||||
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s1">'1'</span><span class="p">,</span> <span class="n">author</span><span class="o">=</span><span class="s1">'tarek'</span><span class="p">,</span>
|
||||
<span class="n">author_email</span><span class="o">=</span><span class="s1">'tarek@ziade.org'</span><span class="p">,</span>
|
||||
<span class="n">url</span><span class="o">=</span><span class="s1">'http://example.com'</span><span class="p">,</span> <span class="n">long_description</span><span class="o">=</span><span class="n">desc</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Where the long description is broken, <code class="docutils literal notranslate"><span class="pre">check</span></code> will be able to detect it
|
||||
by using the <code class="xref py py-mod docutils literal notranslate"><span class="pre">docutils</span></code> parser:</p>
|
||||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python setup.py check --restructuredtext
|
||||
<span class="go">running check</span>
|
||||
<span class="go">warning: check: Title underline too short. (line 2)</span>
|
||||
<span class="go">warning: check: Could not finish the parsing.</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="reading-the-metadata">
|
||||
<h2>6.5. Reading the metadata<a class="headerlink" href="#reading-the-metadata" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The <a class="reference internal" href="apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.core.setup()</span></code></a> function provides a command-line interface
|
||||
that allows you to query the metadata fields of a project through the
|
||||
<code class="docutils literal notranslate"><span class="pre">setup.py</span></code> script of a given project:</p>
|
||||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python setup.py --name
|
||||
<span class="go">distribute</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This call reads the <code class="docutils literal notranslate"><span class="pre">name</span></code> metadata by running the
|
||||
<a class="reference internal" href="apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.core.setup()</span></code></a> function. Although, when a source or binary
|
||||
distribution is created with Distutils, the metadata fields are written
|
||||
in a static file called <code class="file docutils literal notranslate"><span class="pre">PKG-INFO</span></code>. When a Distutils-based project is
|
||||
installed in Python, the <code class="file docutils literal notranslate"><span class="pre">PKG-INFO</span></code> file is copied alongside the modules
|
||||
and packages of the distribution under <code class="file docutils literal notranslate"><span class="pre">NAME-VERSION-pyX.X.egg-info</span></code>,
|
||||
where <code class="docutils literal notranslate"><span class="pre">NAME</span></code> is the name of the project, <code class="docutils literal notranslate"><span class="pre">VERSION</span></code> its version as defined
|
||||
in the Metadata, and <code class="docutils literal notranslate"><span class="pre">pyX.X</span></code> the major and minor version of Python like
|
||||
<code class="docutils literal notranslate"><span class="pre">2.7</span></code> or <code class="docutils literal notranslate"><span class="pre">3.2</span></code>.</p>
|
||||
<p>You can read back this static file, by using the
|
||||
<code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.dist.DistributionMetadata</span></code> class and its
|
||||
<code class="xref py py-func docutils literal notranslate"><span class="pre">read_pkg_file()</span></code> method:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">distutils.dist</span> <span class="k">import</span> <span class="n">DistributionMetadata</span>
|
||||
<span class="gp">>>> </span><span class="n">metadata</span> <span class="o">=</span> <span class="n">DistributionMetadata</span><span class="p">()</span>
|
||||
<span class="gp">>>> </span><span class="n">metadata</span><span class="o">.</span><span class="n">read_pkg_file</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="s1">'distribute-0.6.8-py2.7.egg-info'</span><span class="p">))</span>
|
||||
<span class="gp">>>> </span><span class="n">metadata</span><span class="o">.</span><span class="n">name</span>
|
||||
<span class="go">'distribute'</span>
|
||||
<span class="gp">>>> </span><span class="n">metadata</span><span class="o">.</span><span class="n">version</span>
|
||||
<span class="go">'0.6.8'</span>
|
||||
<span class="gp">>>> </span><span class="n">metadata</span><span class="o">.</span><span class="n">description</span>
|
||||
<span class="go">'Easily download, build, install, upgrade, and uninstall Python packages'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Notice that the class can also be instantiated with a metadata file path to
|
||||
loads its values:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pkg_info_path</span> <span class="o">=</span> <span class="s1">'distribute-0.6.8-py2.7.egg-info'</span>
|
||||
<span class="gp">>>> </span><span class="n">DistributionMetadata</span><span class="p">(</span><span class="n">pkg_info_path</span><span class="p">)</span><span class="o">.</span><span class="n">name</span>
|
||||
<span class="go">'distribute'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">6. Examples</a><ul>
|
||||
<li><a class="reference internal" href="#pure-python-distribution-by-module">6.1. Pure Python distribution (by module)</a></li>
|
||||
<li><a class="reference internal" href="#pure-python-distribution-by-package">6.2. Pure Python distribution (by package)</a></li>
|
||||
<li><a class="reference internal" href="#single-extension-module">6.3. Single extension module</a></li>
|
||||
<li><a class="reference internal" href="#checking-a-package">6.4. Checking a package</a></li>
|
||||
<li><a class="reference internal" href="#reading-the-metadata">6.5. Reading the metadata</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h4>Previous topic</h4>
|
||||
<p class="topless"><a href="builtdist.html"
|
||||
title="previous chapter">5. Creating Built Distributions</a></p>
|
||||
<h4>Next topic</h4>
|
||||
<p class="topless"><a href="extending.html"
|
||||
title="next chapter">7. Extending Distutils</a></p>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/examples.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="extending.html" title="7. Extending Distutils"
|
||||
>next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="builtdist.html" title="5. Creating Built Distributions"
|
||||
>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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
262
python-3.7.4-docs-html/distutils/extending.html
Normal file
262
python-3.7.4-docs-html/distutils/extending.html
Normal file
@@ -0,0 +1,262 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>7. Extending Distutils — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="8. Command Reference" href="commandref.html" />
|
||||
<link rel="prev" title="6. Examples" href="examples.html" />
|
||||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/extending.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="commandref.html" title="8. Command Reference"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="examples.html" title="6. Examples"
|
||||
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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="extending-distutils">
|
||||
<span id="id1"></span><h1>7. Extending Distutils<a class="headerlink" href="#extending-distutils" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Distutils can be extended in various ways. Most extensions take the form of new
|
||||
commands or replacements for existing commands. New commands may be written to
|
||||
support new types of platform-specific packaging, for example, while
|
||||
replacements for existing commands may be made to modify details of how the
|
||||
command operates on a package.</p>
|
||||
<p>Most extensions of the distutils are made within <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> scripts that
|
||||
want to modify existing commands; many simply add a few file extensions that
|
||||
should be copied into packages in addition to <code class="file docutils literal notranslate"><span class="pre">.py</span></code> files as a
|
||||
convenience.</p>
|
||||
<p>Most distutils command implementations are subclasses of the
|
||||
<a class="reference internal" href="apiref.html#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.cmd.Command</span></code></a> class. New commands may directly inherit from
|
||||
<code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code>, while replacements often derive from <code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code>
|
||||
indirectly, directly subclassing the command they are replacing. Commands are
|
||||
required to derive from <code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code>.</p>
|
||||
<div class="section" id="integrating-new-commands">
|
||||
<h2>7.1. Integrating new commands<a class="headerlink" href="#integrating-new-commands" title="Permalink to this headline">¶</a></h2>
|
||||
<p>There are different ways to integrate new command implementations into
|
||||
distutils. The most difficult is to lobby for the inclusion of the new features
|
||||
in distutils itself, and wait for (and require) a version of Python that
|
||||
provides that support. This is really hard for many reasons.</p>
|
||||
<p>The most common, and possibly the most reasonable for most needs, is to include
|
||||
the new implementations with your <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> script, and cause the
|
||||
<a class="reference internal" href="apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.core.setup()</span></code></a> function use them:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.command.build_py</span> <span class="k">import</span> <span class="n">build_py</span> <span class="k">as</span> <span class="n">_build_py</span>
|
||||
<span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
|
||||
<span class="k">class</span> <span class="nc">build_py</span><span class="p">(</span><span class="n">_build_py</span><span class="p">):</span>
|
||||
<span class="sd">"""Specialized Python source builder."""</span>
|
||||
|
||||
<span class="c1"># implement whatever needs to be different...</span>
|
||||
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">cmdclass</span><span class="o">=</span><span class="p">{</span><span class="s1">'build_py'</span><span class="p">:</span> <span class="n">build_py</span><span class="p">},</span>
|
||||
<span class="o">...</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This approach is most valuable if the new implementations must be used to use a
|
||||
particular package, as everyone interested in the package will need to have the
|
||||
new command implementation.</p>
|
||||
<p>Beginning with Python 2.4, a third option is available, intended to allow new
|
||||
commands to be added which can support existing <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> scripts without
|
||||
requiring modifications to the Python installation. This is expected to allow
|
||||
third-party extensions to provide support for additional packaging systems, but
|
||||
the commands can be used for anything distutils commands can be used for. A new
|
||||
configuration option, <code class="docutils literal notranslate"><span class="pre">command_packages</span></code> (command-line option
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">--command-packages</span></code>), can be used to specify additional packages to be
|
||||
searched for modules implementing commands. Like all distutils options, this
|
||||
can be specified on the command line or in a configuration file. This option
|
||||
can only be set in the <code class="docutils literal notranslate"><span class="pre">[global]</span></code> section of a configuration file, or before
|
||||
any commands on the command line. If set in a configuration file, it can be
|
||||
overridden from the command line; setting it to an empty string on the command
|
||||
line causes the default to be used. This should never be set in a configuration
|
||||
file provided with a package.</p>
|
||||
<p>This new option can be used to add any number of packages to the list of
|
||||
packages searched for command implementations; multiple package names should be
|
||||
separated by commas. When not specified, the search is only performed in the
|
||||
<a class="reference internal" href="apiref.html#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command</span></code></a> package. When <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> is run with the option
|
||||
<code class="docutils literal notranslate"><span class="pre">--command-packages</span> <span class="pre">distcmds,buildcmds</span></code>, however, the packages
|
||||
<a class="reference internal" href="apiref.html#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command</span></code></a>, <code class="xref py py-mod docutils literal notranslate"><span class="pre">distcmds</span></code>, and <code class="xref py py-mod docutils literal notranslate"><span class="pre">buildcmds</span></code> will be searched
|
||||
in that order. New commands are expected to be implemented in modules of the
|
||||
same name as the command by classes sharing the same name. Given the example
|
||||
command line option above, the command <strong class="command">bdist_openpkg</strong> could be
|
||||
implemented by the class <code class="xref py py-class docutils literal notranslate"><span class="pre">distcmds.bdist_openpkg.bdist_openpkg</span></code> or
|
||||
<code class="xref py py-class docutils literal notranslate"><span class="pre">buildcmds.bdist_openpkg.bdist_openpkg</span></code>.</p>
|
||||
</div>
|
||||
<div class="section" id="adding-new-distribution-types">
|
||||
<h2>7.2. Adding new distribution types<a class="headerlink" href="#adding-new-distribution-types" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Commands that create distributions (files in the <code class="file docutils literal notranslate"><span class="pre">dist/</span></code> directory) need
|
||||
to add <code class="docutils literal notranslate"><span class="pre">(command,</span> <span class="pre">filename)</span></code> pairs to <code class="docutils literal notranslate"><span class="pre">self.distribution.dist_files</span></code> so that
|
||||
<strong class="command">upload</strong> can upload it to PyPI. The <em>filename</em> in the pair contains no
|
||||
path information, only the name of the file itself. In dry-run mode, pairs
|
||||
should still be added to represent what would have been created.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">7. Extending Distutils</a><ul>
|
||||
<li><a class="reference internal" href="#integrating-new-commands">7.1. Integrating new commands</a></li>
|
||||
<li><a class="reference internal" href="#adding-new-distribution-types">7.2. Adding new distribution types</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h4>Previous topic</h4>
|
||||
<p class="topless"><a href="examples.html"
|
||||
title="previous chapter">6. Examples</a></p>
|
||||
<h4>Next topic</h4>
|
||||
<p class="topless"><a href="commandref.html"
|
||||
title="next chapter">8. Command Reference</a></p>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/extending.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="commandref.html" title="8. Command Reference"
|
||||
>next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="examples.html" title="6. Examples"
|
||||
>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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
309
python-3.7.4-docs-html/distutils/index.html
Normal file
309
python-3.7.4-docs-html/distutils/index.html
Normal file
@@ -0,0 +1,309 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Distributing Python Modules (Legacy version) — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="1. An Introduction to Distutils" href="introduction.html" />
|
||||
<link rel="prev" title="History and License" href="../license.html" />
|
||||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/index.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="introduction.html" title="1. An Introduction to Distutils"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="../license.html" title="History and License"
|
||||
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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="distributing-python-modules-legacy-version">
|
||||
<span id="distutils-index"></span><h1>Distributing Python Modules (Legacy version)<a class="headerlink" href="#distributing-python-modules-legacy-version" title="Permalink to this headline">¶</a></h1>
|
||||
<dl class="field-list simple">
|
||||
<dt class="field-odd">Authors</dt>
|
||||
<dd class="field-odd"><p>Greg Ward, Anthony Baxter</p>
|
||||
</dd>
|
||||
<dt class="field-even">Email</dt>
|
||||
<dd class="field-even"><p><a class="reference external" href="mailto:distutils-sig%40python.org">distutils-sig<span>@</span>python<span>.</span>org</a></p>
|
||||
</dd>
|
||||
</dl>
|
||||
<div class="admonition seealso">
|
||||
<p class="admonition-title">See also</p>
|
||||
<dl class="simple">
|
||||
<dt><a class="reference internal" href="../distributing/index.html#distributing-index"><span class="std std-ref">Distributing Python Modules</span></a></dt><dd><p>The up to date module distribution documentations</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
<p>This document describes the Python Distribution Utilities (“Distutils”) from
|
||||
the module developer’s point of view, describing how to use the Distutils to
|
||||
make Python modules and extensions easily available to a wider audience with
|
||||
very little overhead for build/release/install mechanics.</p>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>This guide only covers the basic tools for building and distributing
|
||||
extensions that are provided as part of this version of Python. Third party
|
||||
tools offer easier to use and more secure alternatives. Refer to the <a class="reference external" href="https://packaging.python.org/guides/tool-recommendations/">quick
|
||||
recommendations section</a>
|
||||
in the Python Packaging User Guide for more information.</p>
|
||||
</div>
|
||||
<div class="toctree-wrapper compound">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="introduction.html">1. An Introduction to Distutils</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="introduction.html#concepts-terminology">1.1. Concepts & Terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="introduction.html#a-simple-example">1.2. A Simple Example</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="introduction.html#general-python-terminology">1.3. General Python terminology</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="introduction.html#distutils-specific-terminology">1.4. Distutils-specific terminology</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="setupscript.html">2. Writing the Setup Script</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#listing-whole-packages">2.1. Listing whole packages</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#listing-individual-modules">2.2. Listing individual modules</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#describing-extension-modules">2.3. Describing extension modules</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#relationships-between-distributions-and-packages">2.4. Relationships between Distributions and Packages</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#installing-scripts">2.5. Installing Scripts</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#installing-package-data">2.6. Installing Package Data</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#installing-additional-files">2.7. Installing Additional Files</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#additional-meta-data">2.8. Additional meta-data</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#debugging-the-setup-script">2.9. Debugging the setup script</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="configfile.html">3. Writing the Setup Configuration File</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="sourcedist.html">4. Creating a Source Distribution</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sourcedist.html#specifying-the-files-to-distribute">4.1. Specifying the files to distribute</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="sourcedist.html#manifest-related-options">4.2. Manifest-related options</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="builtdist.html">5. Creating Built Distributions</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#creating-rpm-packages">5.1. Creating RPM packages</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#creating-windows-installers">5.2. Creating Windows Installers</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#cross-compiling-on-windows">5.3. Cross-compiling on Windows</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#vista-user-access-control-uac">5.4. Vista User Access Control (UAC)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">6. Examples</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="examples.html#pure-python-distribution-by-module">6.1. Pure Python distribution (by module)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="examples.html#pure-python-distribution-by-package">6.2. Pure Python distribution (by package)</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="examples.html#single-extension-module">6.3. Single extension module</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="examples.html#checking-a-package">6.4. Checking a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="examples.html#reading-the-metadata">6.5. Reading the metadata</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="extending.html">7. Extending Distutils</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="extending.html#integrating-new-commands">7.1. Integrating new commands</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="extending.html#adding-new-distribution-types">7.2. Adding new distribution types</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="commandref.html">8. Command Reference</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="commandref.html#installing-modules-the-install-command-family">8.1. Installing modules: the <strong class="command">install</strong> command family</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="commandref.html#creating-a-source-distribution-the-sdist-command">8.2. Creating a source distribution: the <strong class="command">sdist</strong> command</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="apiref.html">9. API Reference</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.core">9.1. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.core</span></code> — Core Distutils functionality</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.ccompiler">9.2. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.ccompiler</span></code> — CCompiler base class</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.unixccompiler">9.3. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.unixccompiler</span></code> — Unix C Compiler</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.msvccompiler">9.4. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.msvccompiler</span></code> — Microsoft Compiler</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.bcppcompiler">9.5. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.bcppcompiler</span></code> — Borland Compiler</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.cygwinccompiler">9.6. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.cygwincompiler</span></code> — Cygwin Compiler</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.archive_util">9.7. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.archive_util</span></code> — Archiving utilities</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.dep_util">9.8. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.dep_util</span></code> — Dependency checking</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.dir_util">9.9. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.dir_util</span></code> — Directory tree operations</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.file_util">9.10. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.file_util</span></code> — Single file operations</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.util">9.11. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.util</span></code> — Miscellaneous other utility functions</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.dist">9.12. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.dist</span></code> — The Distribution class</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.extension">9.13. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.extension</span></code> — The Extension class</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.debug">9.14. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.debug</span></code> — Distutils debug mode</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.errors">9.15. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.errors</span></code> — Distutils exceptions</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.fancy_getopt">9.16. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.fancy_getopt</span></code> — Wrapper around the standard getopt module</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.filelist">9.17. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.filelist</span></code> — The FileList class</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.log">9.18. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.log</span></code> — Simple PEP 282-style logging</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.spawn">9.19. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.spawn</span></code> — Spawn a sub-process</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.sysconfig">9.20. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code> — System configuration information</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.text_file">9.21. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.text_file</span></code> — The TextFile class</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.version">9.22. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.version</span></code> — Version number classes</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.cmd">9.23. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.cmd</span></code> — Abstract base class for Distutils commands</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#creating-a-new-distutils-command">9.24. Creating a new Distutils command</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command">9.25. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command</span></code> — Individual Distutils commands</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist">9.26. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist</span></code> — Build a binary installer</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_packager">9.27. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_packager</span></code> — Abstract base class for packagers</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_dumb">9.28. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_dumb</span></code> — Build a “dumb” installer</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_msi">9.29. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_msi</span></code> — Build a Microsoft Installer binary package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_rpm">9.30. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_rpm</span></code> — Build a binary distribution as a Redhat RPM and SRPM</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_wininst">9.31. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_wininst</span></code> — Build a Windows installer</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.sdist">9.32. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.sdist</span></code> — Build a source distribution</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build">9.33. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build</span></code> — Build all files of a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_clib">9.34. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_clib</span></code> — Build any C libraries in a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_ext">9.35. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_ext</span></code> — Build any extensions in a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_py">9.36. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_py</span></code> — Build the .py/.pyc files of a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_scripts">9.37. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_scripts</span></code> — Build the scripts of a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.clean">9.38. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.clean</span></code> — Clean a package build area</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.config">9.39. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.config</span></code> — Perform package configuration</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install">9.40. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install</span></code> — Install a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_data">9.41. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_data</span></code> — Install data files from a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_headers">9.42. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_headers</span></code> — Install C/C++ header files from a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_lib">9.43. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_lib</span></code> — Install library files from a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_scripts">9.44. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_scripts</span></code> — Install script files from a package</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.register">9.45. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.register</span></code> — Register a module with the Python Package Index</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.check">9.46. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.check</span></code> — Check the meta-data of a package</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="../license.html"
|
||||
title="previous chapter">History and License</a></p>
|
||||
<h4>Next topic</h4>
|
||||
<p class="topless"><a href="introduction.html"
|
||||
title="next chapter">1. An Introduction to Distutils</a></p>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/index.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="introduction.html" title="1. An Introduction to Distutils"
|
||||
>next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="../license.html" title="History and License"
|
||||
>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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
364
python-3.7.4-docs-html/distutils/introduction.html
Normal file
364
python-3.7.4-docs-html/distutils/introduction.html
Normal file
@@ -0,0 +1,364 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>1. An Introduction to Distutils — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="2. Writing the Setup Script" href="setupscript.html" />
|
||||
<link rel="prev" title="Distributing Python Modules (Legacy version)" href="index.html" />
|
||||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/introduction.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="setupscript.html" title="2. Writing the Setup Script"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="index.html" title="Distributing Python Modules (Legacy version)"
|
||||
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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="an-introduction-to-distutils">
|
||||
<span id="distutils-intro"></span><h1>1. An Introduction to Distutils<a class="headerlink" href="#an-introduction-to-distutils" title="Permalink to this headline">¶</a></h1>
|
||||
<p>This document covers using the Distutils to distribute your Python modules,
|
||||
concentrating on the role of developer/distributor: if you’re looking for
|
||||
information on installing Python modules, you should refer to the
|
||||
<a class="reference internal" href="../install/index.html#install-index"><span class="std std-ref">Installing Python Modules (Legacy version)</span></a> chapter.</p>
|
||||
<div class="section" id="concepts-terminology">
|
||||
<span id="distutils-concepts"></span><h2>1.1. Concepts & Terminology<a class="headerlink" href="#concepts-terminology" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Using the Distutils is quite simple, both for module developers and for
|
||||
users/administrators installing third-party modules. As a developer, your
|
||||
responsibilities (apart from writing solid, well-documented and well-tested
|
||||
code, of course!) are:</p>
|
||||
<ul class="simple">
|
||||
<li><p>write a setup script (<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by convention)</p></li>
|
||||
<li><p>(optional) write a setup configuration file</p></li>
|
||||
<li><p>create a source distribution</p></li>
|
||||
<li><p>(optional) create one or more built (binary) distributions</p></li>
|
||||
</ul>
|
||||
<p>Each of these tasks is covered in this document.</p>
|
||||
<p>Not all module developers have access to a multitude of platforms, so it’s not
|
||||
always feasible to expect them to create a multitude of built distributions. It
|
||||
is hoped that a class of intermediaries, called <em>packagers</em>, will arise to
|
||||
address this need. Packagers will take source distributions released by module
|
||||
developers, build them on one or more platforms, and release the resulting built
|
||||
distributions. Thus, users on the most popular platforms will be able to
|
||||
install most popular Python module distributions in the most natural way for
|
||||
their platform, without having to run a single setup script or compile a line of
|
||||
code.</p>
|
||||
</div>
|
||||
<div class="section" id="a-simple-example">
|
||||
<span id="distutils-simple-example"></span><h2>1.2. A Simple Example<a class="headerlink" href="#a-simple-example" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The setup script is usually quite simple, although since it’s written in Python,
|
||||
there are no arbitrary limits to what you can do with it, though you should be
|
||||
careful about putting arbitrarily expensive operations in your setup script.
|
||||
Unlike, say, Autoconf-style configure scripts, the setup script may be run
|
||||
multiple times in the course of building and installing your module
|
||||
distribution.</p>
|
||||
<p>If all you want to do is distribute a module called <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code>, contained in a
|
||||
file <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code>, then your setup script can be as simple as this:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Some observations:</p>
|
||||
<ul class="simple">
|
||||
<li><p>most information that you supply to the Distutils is supplied as keyword
|
||||
arguments to the <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> function</p></li>
|
||||
<li><p>those keyword arguments fall into two categories: package metadata (name,
|
||||
version number) and information about what’s in the package (a list of pure
|
||||
Python modules, in this case)</p></li>
|
||||
<li><p>modules are specified by module name, not filename (the same will hold true
|
||||
for packages and extensions)</p></li>
|
||||
<li><p>it’s recommended that you supply a little more metadata, in particular your
|
||||
name, email address and a URL for the project (see section <a class="reference internal" href="setupscript.html#setup-script"><span class="std std-ref">Writing the Setup Script</span></a>
|
||||
for an example)</p></li>
|
||||
</ul>
|
||||
<p>To create a source distribution for this module, you would create a setup
|
||||
script, <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, containing the above code, and run this command from a
|
||||
terminal:</p>
|
||||
<div class="highlight-python3 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">sdist</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For Windows, open a command prompt window (<span class="menuselection">Start ‣
|
||||
Accessories</span>) and change the command to:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p><strong class="command">sdist</strong> will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
|
||||
containing your setup script <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, and your module <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code>.
|
||||
The archive file will be named <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (or <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>), and
|
||||
will unpack into a directory <code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code>.</p>
|
||||
<p>If an end-user wishes to install your <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> module, all they have to do is
|
||||
download <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (or <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>), unpack it, and—from the
|
||||
<code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code> directory—run</p>
|
||||
<div class="highlight-python3 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">install</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>which will ultimately copy <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code> to the appropriate directory for
|
||||
third-party modules in their Python installation.</p>
|
||||
<p>This simple example demonstrates some fundamental concepts of the Distutils.
|
||||
First, both developers and installers have the same basic user interface, i.e.
|
||||
the setup script. The difference is which Distutils <em>commands</em> they use: the
|
||||
<strong class="command">sdist</strong> command is almost exclusively for module developers, while
|
||||
<strong class="command">install</strong> is more often for installers (although most developers will
|
||||
want to install their own code occasionally).</p>
|
||||
<p>If you want to make things really easy for your users, you can create one or
|
||||
more built distributions for them. For instance, if you are running on a
|
||||
Windows machine, and want to make things easy for other Windows users, you can
|
||||
create an executable installer (the most appropriate type of built distribution
|
||||
for this platform) with the <strong class="command">bdist_wininst</strong> command. For example:</p>
|
||||
<div class="highlight-python3 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">bdist_wininst</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>will create an executable installer, <code class="file docutils literal notranslate"><span class="pre">foo-1.0.win32.exe</span></code>, in the current
|
||||
directory.</p>
|
||||
<p>Other useful built distribution formats are RPM, implemented by the
|
||||
<strong class="command">bdist_rpm</strong> command, Solaris <strong class="program">pkgtool</strong>
|
||||
(<strong class="command">bdist_pkgtool</strong>), and HP-UX <strong class="program">swinstall</strong>
|
||||
(<strong class="command">bdist_sdux</strong>). For example, the following command will create an RPM
|
||||
file called <code class="file docutils literal notranslate"><span class="pre">foo-1.0.noarch.rpm</span></code>:</p>
|
||||
<div class="highlight-python3 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">bdist_rpm</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>(The <strong class="command">bdist_rpm</strong> command uses the <strong class="command">rpm</strong> executable, therefore
|
||||
this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
|
||||
Mandrake Linux.)</p>
|
||||
<p>You can find out what distribution formats are available at any time by running</p>
|
||||
<div class="highlight-python3 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">bdist</span> <span class="o">--</span><span class="n">help</span><span class="o">-</span><span class="n">formats</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="general-python-terminology">
|
||||
<span id="python-terms"></span><h2>1.3. General Python terminology<a class="headerlink" href="#general-python-terminology" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you’re reading this document, you probably have a good idea of what modules,
|
||||
extensions, and so forth are. Nevertheless, just to be sure that everyone is
|
||||
operating from a common starting point, we offer the following glossary of
|
||||
common Python terms:</p>
|
||||
<dl class="simple">
|
||||
<dt>module</dt><dd><p>the basic unit of code reusability in Python: a block of code imported by some
|
||||
other code. Three types of modules concern us here: pure Python modules,
|
||||
extension modules, and packages.</p>
|
||||
</dd>
|
||||
<dt>pure Python module</dt><dd><p>a module written in Python and contained in a single <code class="file docutils literal notranslate"><span class="pre">.py</span></code> file (and
|
||||
possibly associated <code class="file docutils literal notranslate"><span class="pre">.pyc</span></code> files). Sometimes referred to as a
|
||||
“pure module.”</p>
|
||||
</dd>
|
||||
<dt>extension module</dt><dd><p>a module written in the low-level language of the Python implementation: C/C++
|
||||
for Python, Java for Jython. Typically contained in a single dynamically
|
||||
loadable pre-compiled file, e.g. a shared object (<code class="file docutils literal notranslate"><span class="pre">.so</span></code>) file for Python
|
||||
extensions on Unix, a DLL (given the <code class="file docutils literal notranslate"><span class="pre">.pyd</span></code> extension) for Python
|
||||
extensions on Windows, or a Java class file for Jython extensions. (Note that
|
||||
currently, the Distutils only handles C/C++ extensions for Python.)</p>
|
||||
</dd>
|
||||
<dt>package</dt><dd><p>a module that contains other modules; typically contained in a directory in the
|
||||
filesystem and distinguished from other directories by the presence of a file
|
||||
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code>.</p>
|
||||
</dd>
|
||||
<dt>root package</dt><dd><p>the root of the hierarchy of packages. (This isn’t really a package, since it
|
||||
doesn’t have an <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> file. But we have to call it something.)
|
||||
The vast majority of the standard library is in the root package, as are many
|
||||
small, standalone third-party modules that don’t belong to a larger module
|
||||
collection. Unlike regular packages, modules in the root package can be found in
|
||||
many directories: in fact, every directory listed in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> contributes
|
||||
modules to the root package.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section" id="distutils-specific-terminology">
|
||||
<span id="distutils-term"></span><h2>1.4. Distutils-specific terminology<a class="headerlink" href="#distutils-specific-terminology" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The following terms apply more specifically to the domain of distributing Python
|
||||
modules using the Distutils:</p>
|
||||
<dl class="simple">
|
||||
<dt>module distribution</dt><dd><p>a collection of Python modules distributed together as a single downloadable
|
||||
resource and meant to be installed <em>en masse</em>. Examples of some well-known
|
||||
module distributions are NumPy, SciPy, Pillow,
|
||||
or mxBase. (This would be called a <em>package</em>, except that term is
|
||||
already taken in the Python context: a single module distribution may contain
|
||||
zero, one, or many Python packages.)</p>
|
||||
</dd>
|
||||
<dt>pure module distribution</dt><dd><p>a module distribution that contains only pure Python modules and packages.
|
||||
Sometimes referred to as a “pure distribution.”</p>
|
||||
</dd>
|
||||
<dt>non-pure module distribution</dt><dd><p>a module distribution that contains at least one extension module. Sometimes
|
||||
referred to as a “non-pure distribution.”</p>
|
||||
</dd>
|
||||
<dt>distribution root</dt><dd><p>the top-level directory of your source tree (or source distribution); the
|
||||
directory where <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> exists. Generally <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> will be
|
||||
run from this directory.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">1. An Introduction to Distutils</a><ul>
|
||||
<li><a class="reference internal" href="#concepts-terminology">1.1. Concepts & Terminology</a></li>
|
||||
<li><a class="reference internal" href="#a-simple-example">1.2. A Simple Example</a></li>
|
||||
<li><a class="reference internal" href="#general-python-terminology">1.3. General Python terminology</a></li>
|
||||
<li><a class="reference internal" href="#distutils-specific-terminology">1.4. Distutils-specific terminology</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h4>Previous topic</h4>
|
||||
<p class="topless"><a href="index.html"
|
||||
title="previous chapter">Distributing Python Modules (Legacy version)</a></p>
|
||||
<h4>Next topic</h4>
|
||||
<p class="topless"><a href="setupscript.html"
|
||||
title="next chapter">2. Writing the Setup Script</a></p>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/introduction.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="setupscript.html" title="2. Writing the Setup Script"
|
||||
>next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="index.html" title="Distributing Python Modules (Legacy version)"
|
||||
>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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
164
python-3.7.4-docs-html/distutils/packageindex.html
Normal file
164
python-3.7.4-docs-html/distutils/packageindex.html
Normal file
@@ -0,0 +1,164 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>The Python Package Index (PyPI) — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/packageindex.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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><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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="the-python-package-index-pypi">
|
||||
<span id="package-index"></span><h1>The Python Package Index (PyPI)<a class="headerlink" href="#the-python-package-index-pypi" title="Permalink to this headline">¶</a></h1>
|
||||
<p>The <a class="reference external" href="https://pypi.org">Python Package Index (PyPI)</a> stores metadata describing distributions
|
||||
packaged with distutils and other publishing tools, as well the distribution
|
||||
archives themselves.</p>
|
||||
<p>References to up to date PyPI documentation can be found at
|
||||
<a class="reference internal" href="../distributing/index.html#publishing-python-packages"><span class="std std-ref">Reading the Python Packaging User Guide</span></a>.</p>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/packageindex.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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><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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
886
python-3.7.4-docs-html/distutils/setupscript.html
Normal file
886
python-3.7.4-docs-html/distutils/setupscript.html
Normal file
@@ -0,0 +1,886 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>2. Writing the Setup Script — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="3. Writing the Setup Configuration File" href="configfile.html" />
|
||||
<link rel="prev" title="1. An Introduction to Distutils" href="introduction.html" />
|
||||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/setupscript.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="configfile.html" title="3. Writing the Setup Configuration File"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="introduction.html" title="1. An Introduction to Distutils"
|
||||
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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="writing-the-setup-script">
|
||||
<span id="setup-script"></span><h1>2. Writing the Setup Script<a class="headerlink" href="#writing-the-setup-script" title="Permalink to this headline">¶</a></h1>
|
||||
<p>The setup script is the centre of all activity in building, distributing, and
|
||||
installing modules using the Distutils. The main purpose of the setup script is
|
||||
to describe your module distribution to the Distutils, so that the various
|
||||
commands that operate on your modules do the right thing. As we saw in section
|
||||
<a class="reference internal" href="introduction.html#distutils-simple-example"><span class="std std-ref">A Simple Example</span></a> above, the setup script consists mainly of a call to
|
||||
<code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>, and most information supplied to the Distutils by the module
|
||||
developer is supplied as keyword arguments to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>.</p>
|
||||
<p>Here’s a slightly more involved example, which we’ll follow for the next couple
|
||||
of sections: the Distutils’ own setup script. (Keep in mind that although the
|
||||
Distutils are included with Python 1.6 and later, they also have an independent
|
||||
existence so that Python 1.5.2 users can use them to install other module
|
||||
distributions. The Distutils’ own setup script, shown here, is used to install
|
||||
the package into Python 1.5.2.)</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
|
||||
|
||||
<span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
|
||||
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'Distutils'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">description</span><span class="o">=</span><span class="s1">'Python Distribution Utilities'</span><span class="p">,</span>
|
||||
<span class="n">author</span><span class="o">=</span><span class="s1">'Greg Ward'</span><span class="p">,</span>
|
||||
<span class="n">author_email</span><span class="o">=</span><span class="s1">'gward@python.net'</span><span class="p">,</span>
|
||||
<span class="n">url</span><span class="o">=</span><span class="s1">'https://www.python.org/sigs/distutils-sig/'</span><span class="p">,</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'distutils'</span><span class="p">,</span> <span class="s1">'distutils.command'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>There are only two differences between this and the trivial one-file
|
||||
distribution presented in section <a class="reference internal" href="introduction.html#distutils-simple-example"><span class="std std-ref">A Simple Example</span></a>: more metadata, and the
|
||||
specification of pure Python modules by package, rather than by module. This is
|
||||
important since the Distutils consist of a couple of dozen modules split into
|
||||
(so far) two packages; an explicit list of every module would be tedious to
|
||||
generate and difficult to maintain. For more information on the additional
|
||||
meta-data, see section <a class="reference internal" href="#meta-data"><span class="std std-ref">Additional meta-data</span></a>.</p>
|
||||
<p>Note that any pathnames (files or directories) supplied in the setup script
|
||||
should be written using the Unix convention, i.e. slash-separated. The
|
||||
Distutils will take care of converting this platform-neutral representation into
|
||||
whatever is appropriate on your current platform before actually using the
|
||||
pathname. This makes your setup script portable across operating systems, which
|
||||
of course is one of the major goals of the Distutils. In this spirit, all
|
||||
pathnames in this document are slash-separated.</p>
|
||||
<p>This, of course, only applies to pathnames given to Distutils functions. If
|
||||
you, for example, use standard Python functions such as <a class="reference internal" href="../library/glob.html#glob.glob" title="glob.glob"><code class="xref py py-func docutils literal notranslate"><span class="pre">glob.glob()</span></code></a> or
|
||||
<a class="reference internal" href="../library/os.html#os.listdir" title="os.listdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.listdir()</span></code></a> to specify files, you should be careful to write portable
|
||||
code instead of hardcoding path separators:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s1">'mydir'</span><span class="p">,</span> <span class="s1">'subdir'</span><span class="p">,</span> <span class="s1">'*.html'</span><span class="p">))</span>
|
||||
<span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s1">'mydir'</span><span class="p">,</span> <span class="s1">'subdir'</span><span class="p">))</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="listing-whole-packages">
|
||||
<span id="listing-packages"></span><h2>2.1. Listing whole packages<a class="headerlink" href="#listing-whole-packages" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">packages</span></code> option tells the Distutils to process (build, distribute,
|
||||
install, etc.) all pure Python modules found in each package mentioned in the
|
||||
<code class="docutils literal notranslate"><span class="pre">packages</span></code> list. In order to do this, of course, there has to be a
|
||||
correspondence between package names and directories in the filesystem. The
|
||||
default correspondence is the most obvious one, i.e. package <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a> is
|
||||
found in the directory <code class="file docutils literal notranslate"><span class="pre">distutils</span></code> relative to the distribution root.
|
||||
Thus, when you say <code class="docutils literal notranslate"><span class="pre">packages</span> <span class="pre">=</span> <span class="pre">['foo']</span></code> in your setup script, you are
|
||||
promising that the Distutils will find a file <code class="file docutils literal notranslate"><span class="pre">foo/__init__.py</span></code> (which
|
||||
might be spelled differently on your system, but you get the idea) relative to
|
||||
the directory where your setup script lives. If you break this promise, the
|
||||
Distutils will issue a warning but still process the broken package anyway.</p>
|
||||
<p>If you use a different convention to lay out your source directory, that’s no
|
||||
problem: you just have to supply the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> option to tell the
|
||||
Distutils about your convention. For example, say you keep all Python source
|
||||
under <code class="file docutils literal notranslate"><span class="pre">lib</span></code>, so that modules in the “root package” (i.e., not in any
|
||||
package at all) are in <code class="file docutils literal notranslate"><span class="pre">lib</span></code>, modules in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> package are in
|
||||
<code class="file docutils literal notranslate"><span class="pre">lib/foo</span></code>, and so forth. Then you would put</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">package_dir</span> <span class="o">=</span> <span class="p">{</span><span class="s1">''</span><span class="p">:</span> <span class="s1">'lib'</span><span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>in your setup script. The keys to this dictionary are package names, and an
|
||||
empty package name stands for the root package. The values are directory names
|
||||
relative to your distribution root. In this case, when you say <code class="docutils literal notranslate"><span class="pre">packages</span> <span class="pre">=</span>
|
||||
<span class="pre">['foo']</span></code>, you are promising that the file <code class="file docutils literal notranslate"><span class="pre">lib/foo/__init__.py</span></code> exists.</p>
|
||||
<p>Another possible convention is to put the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> package right in
|
||||
<code class="file docutils literal notranslate"><span class="pre">lib</span></code>, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo.bar</span></code> package in <code class="file docutils literal notranslate"><span class="pre">lib/bar</span></code>, etc. This would be
|
||||
written in the setup script as</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">package_dir</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'lib'</span><span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>A <code class="docutils literal notranslate"><span class="pre">package:</span> <span class="pre">dir</span></code> entry in the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> dictionary implicitly
|
||||
applies to all packages below <em>package</em>, so the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo.bar</span></code> case is
|
||||
automatically handled here. In this example, having <code class="docutils literal notranslate"><span class="pre">packages</span> <span class="pre">=</span> <span class="pre">['foo',</span>
|
||||
<span class="pre">'foo.bar']</span></code> tells the Distutils to look for <code class="file docutils literal notranslate"><span class="pre">lib/__init__.py</span></code> and
|
||||
<code class="file docutils literal notranslate"><span class="pre">lib/bar/__init__.py</span></code>. (Keep in mind that although <code class="docutils literal notranslate"><span class="pre">package_dir</span></code>
|
||||
applies recursively, you must explicitly list all packages in
|
||||
<code class="docutils literal notranslate"><span class="pre">packages</span></code>: the Distutils will <em>not</em> recursively scan your source tree
|
||||
looking for any directory with an <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> file.)</p>
|
||||
</div>
|
||||
<div class="section" id="listing-individual-modules">
|
||||
<span id="listing-modules"></span><h2>2.2. Listing individual modules<a class="headerlink" href="#listing-individual-modules" title="Permalink to this headline">¶</a></h2>
|
||||
<p>For a small module distribution, you might prefer to list all modules rather
|
||||
than listing packages—especially the case of a single module that goes in the
|
||||
“root package” (i.e., no package at all). This simplest case was shown in
|
||||
section <a class="reference internal" href="introduction.html#distutils-simple-example"><span class="std std-ref">A Simple Example</span></a>; here is a slightly more involved example:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">py_modules</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'mod1'</span><span class="p">,</span> <span class="s1">'pkg.mod2'</span><span class="p">]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This describes two modules, one of them in the “root” package, the other in the
|
||||
<code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg</span></code> package. Again, the default package/directory layout implies that
|
||||
these two modules can be found in <code class="file docutils literal notranslate"><span class="pre">mod1.py</span></code> and <code class="file docutils literal notranslate"><span class="pre">pkg/mod2.py</span></code>, and
|
||||
that <code class="file docutils literal notranslate"><span class="pre">pkg/__init__.py</span></code> exists as well. And again, you can override the
|
||||
package/directory correspondence using the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> option.</p>
|
||||
</div>
|
||||
<div class="section" id="describing-extension-modules">
|
||||
<span id="describing-extensions"></span><h2>2.3. Describing extension modules<a class="headerlink" href="#describing-extension-modules" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Just as writing Python extension modules is a bit more complicated than writing
|
||||
pure Python modules, describing them to the Distutils is a bit more complicated.
|
||||
Unlike pure modules, it’s not enough just to list modules or packages and expect
|
||||
the Distutils to go out and find the right files; you have to specify the
|
||||
extension name, source file(s), and any compile/link requirements (include
|
||||
directories, libraries to link with, etc.).</p>
|
||||
<p>All of this is done through another keyword argument to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>, the
|
||||
<code class="docutils literal notranslate"><span class="pre">ext_modules</span></code> option. <code class="docutils literal notranslate"><span class="pre">ext_modules</span></code> is just a list of
|
||||
<a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> instances, each of which describes a
|
||||
single extension module.
|
||||
Suppose your distribution includes a single extension, called <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> and
|
||||
implemented by <code class="file docutils literal notranslate"><span class="pre">foo.c</span></code>. If no additional instructions to the
|
||||
compiler/linker are needed, describing this extension is quite simple:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code> class can be imported from <a class="reference internal" href="apiref.html#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.core</span></code></a> along
|
||||
with <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. Thus, the setup script for a module distribution that
|
||||
contains only this one extension and nothing else might be:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">Extension</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">,</span>
|
||||
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
|
||||
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code> class (actually, the underlying extension-building
|
||||
machinery implemented by the <strong class="command">build_ext</strong> command) supports a great deal
|
||||
of flexibility in describing Python extensions, which is explained in the
|
||||
following sections.</p>
|
||||
<div class="section" id="extension-names-and-packages">
|
||||
<h3>2.3.1. Extension names and packages<a class="headerlink" href="#extension-names-and-packages" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The first argument to the <a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> constructor is
|
||||
always the name of the extension, including any package names. For example,</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'src/foo1.c'</span><span class="p">,</span> <span class="s1">'src/foo2.c'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>describes an extension that lives in the root package, while</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'pkg.foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'src/foo1.c'</span><span class="p">,</span> <span class="s1">'src/foo2.c'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>describes the same extension in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg</span></code> package. The source files and
|
||||
resulting object code are identical in both cases; the only difference is where
|
||||
in the filesystem (and therefore where in Python’s namespace hierarchy) the
|
||||
resulting extension lives.</p>
|
||||
<p>If you have a number of extensions all in the same package (or all under the
|
||||
same base package), use the <code class="docutils literal notranslate"><span class="pre">ext_package</span></code> keyword argument to
|
||||
<code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. For example,</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">ext_package</span><span class="o">=</span><span class="s1">'pkg'</span><span class="p">,</span>
|
||||
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">]),</span>
|
||||
<span class="n">Extension</span><span class="p">(</span><span class="s1">'subpkg.bar'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'bar.c'</span><span class="p">])],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>will compile <code class="file docutils literal notranslate"><span class="pre">foo.c</span></code> to the extension <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.foo</span></code>, and <code class="file docutils literal notranslate"><span class="pre">bar.c</span></code> to
|
||||
<code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.subpkg.bar</span></code>.</p>
|
||||
</div>
|
||||
<div class="section" id="extension-source-files">
|
||||
<h3>2.3.2. Extension source files<a class="headerlink" href="#extension-source-files" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The second argument to the <a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> constructor is
|
||||
a list of source
|
||||
files. Since the Distutils currently only support C, C++, and Objective-C
|
||||
extensions, these are normally C/C++/Objective-C source files. (Be sure to use
|
||||
appropriate extensions to distinguish C++ source files: <code class="file docutils literal notranslate"><span class="pre">.cc</span></code> and
|
||||
<code class="file docutils literal notranslate"><span class="pre">.cpp</span></code> seem to be recognized by both Unix and Windows compilers.)</p>
|
||||
<p>However, you can also include SWIG interface (<code class="file docutils literal notranslate"><span class="pre">.i</span></code>) files in the list; the
|
||||
<strong class="command">build_ext</strong> command knows how to deal with SWIG extensions: it will run
|
||||
SWIG on the interface file and compile the resulting C/C++ file into your
|
||||
extension.</p>
|
||||
<p>This warning notwithstanding, options to SWIG can be currently passed like
|
||||
this:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'_foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.i'</span><span class="p">],</span>
|
||||
<span class="n">swig_opts</span><span class="o">=</span><span class="p">[</span><span class="s1">'-modern'</span><span class="p">,</span> <span class="s1">'-I../include'</span><span class="p">])],</span>
|
||||
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Or on the commandline like this:</p>
|
||||
<div class="highlight-python3 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="n">build_ext</span> <span class="o">--</span><span class="n">swig</span><span class="o">-</span><span class="n">opts</span><span class="o">=</span><span class="s2">"-modern -I../include"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>On some platforms, you can include non-source files that are processed by the
|
||||
compiler and included in your extension. Currently, this just means Windows
|
||||
message text (<code class="file docutils literal notranslate"><span class="pre">.mc</span></code>) files and resource definition (<code class="file docutils literal notranslate"><span class="pre">.rc</span></code>) files for
|
||||
Visual C++. These will be compiled to binary resource (<code class="file docutils literal notranslate"><span class="pre">.res</span></code>) files and
|
||||
linked into the executable.</p>
|
||||
</div>
|
||||
<div class="section" id="preprocessor-options">
|
||||
<h3>2.3.3. Preprocessor options<a class="headerlink" href="#preprocessor-options" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Three optional arguments to <a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> will help if
|
||||
you need to specify include directories to search or preprocessor macros to
|
||||
define/undefine: <code class="docutils literal notranslate"><span class="pre">include_dirs</span></code>, <code class="docutils literal notranslate"><span class="pre">define_macros</span></code>, and <code class="docutils literal notranslate"><span class="pre">undef_macros</span></code>.</p>
|
||||
<p>For example, if your extension requires header files in the <code class="file docutils literal notranslate"><span class="pre">include</span></code>
|
||||
directory under your distribution root, use the <code class="docutils literal notranslate"><span class="pre">include_dirs</span></code> option:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">],</span> <span class="n">include_dirs</span><span class="o">=</span><span class="p">[</span><span class="s1">'include'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can specify absolute directories there; if you know that your extension will
|
||||
only be built on Unix systems with X11R6 installed to <code class="file docutils literal notranslate"><span class="pre">/usr</span></code>, you can get
|
||||
away with</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">],</span> <span class="n">include_dirs</span><span class="o">=</span><span class="p">[</span><span class="s1">'/usr/include/X11'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You should avoid this sort of non-portable usage if you plan to distribute your
|
||||
code: it’s probably better to write C code like</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1">#include <X11/Xlib.h></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you need to include header files from some other Python extension, you can
|
||||
take advantage of the fact that header files are installed in a consistent way
|
||||
by the Distutils <strong class="command">install_headers</strong> command. For example, the Numerical
|
||||
Python header files are installed (on a standard Unix installation) to
|
||||
<code class="file docutils literal notranslate"><span class="pre">/usr/local/include/python1.5/Numerical</span></code>. (The exact location will differ
|
||||
according to your platform and Python installation.) Since the Python include
|
||||
directory—<code class="file docutils literal notranslate"><span class="pre">/usr/local/include/python1.5</span></code> in this case—is always
|
||||
included in the search path when building Python extensions, the best approach
|
||||
is to write C code like</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1">#include <Numerical/arrayobject.h></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you must put the <code class="file docutils literal notranslate"><span class="pre">Numerical</span></code> include directory right into your header
|
||||
search path, though, you can find that directory using the Distutils
|
||||
<a class="reference internal" href="apiref.html#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code></a> module:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.sysconfig</span> <span class="k">import</span> <span class="n">get_python_inc</span>
|
||||
<span class="n">incdir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">get_python_inc</span><span class="p">(</span><span class="n">plat_specific</span><span class="o">=</span><span class="mi">1</span><span class="p">),</span> <span class="s1">'Numerical'</span><span class="p">)</span>
|
||||
<span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">include_dirs</span><span class="o">=</span><span class="p">[</span><span class="n">incdir</span><span class="p">]),</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Even though this is quite portable—it will work on any Python installation,
|
||||
regardless of platform—it’s probably easier to just write your C code in the
|
||||
sensible way.</p>
|
||||
<p>You can define and undefine pre-processor macros with the <code class="docutils literal notranslate"><span class="pre">define_macros</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">undef_macros</span></code> options. <code class="docutils literal notranslate"><span class="pre">define_macros</span></code> takes a list of <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">value)</span></code>
|
||||
tuples, where <code class="docutils literal notranslate"><span class="pre">name</span></code> is the name of the macro to define (a string) and
|
||||
<code class="docutils literal notranslate"><span class="pre">value</span></code> is its value: either a string or <code class="docutils literal notranslate"><span class="pre">None</span></code>. (Defining a macro <code class="docutils literal notranslate"><span class="pre">FOO</span></code>
|
||||
to <code class="docutils literal notranslate"><span class="pre">None</span></code> is the equivalent of a bare <code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">FOO</span></code> in your C source: with
|
||||
most compilers, this sets <code class="docutils literal notranslate"><span class="pre">FOO</span></code> to the string <code class="docutils literal notranslate"><span class="pre">1</span></code>.) <code class="docutils literal notranslate"><span class="pre">undef_macros</span></code> is
|
||||
just a list of macros to undefine.</p>
|
||||
<p>For example:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">define_macros</span><span class="o">=</span><span class="p">[(</span><span class="s1">'NDEBUG'</span><span class="p">,</span> <span class="s1">'1'</span><span class="p">),</span>
|
||||
<span class="p">(</span><span class="s1">'HAVE_STRFTIME'</span><span class="p">,</span> <span class="kc">None</span><span class="p">)],</span>
|
||||
<span class="n">undef_macros</span><span class="o">=</span><span class="p">[</span><span class="s1">'HAVE_FOO'</span><span class="p">,</span> <span class="s1">'HAVE_BAR'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>is the equivalent of having this at the top of every C source file:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1">#define NDEBUG 1</span>
|
||||
<span class="c1">#define HAVE_STRFTIME</span>
|
||||
<span class="c1">#undef HAVE_FOO</span>
|
||||
<span class="c1">#undef HAVE_BAR</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="library-options">
|
||||
<h3>2.3.4. Library options<a class="headerlink" href="#library-options" title="Permalink to this headline">¶</a></h3>
|
||||
<p>You can also specify the libraries to link against when building your extension,
|
||||
and the directories to search for those libraries. The <code class="docutils literal notranslate"><span class="pre">libraries</span></code> option is
|
||||
a list of libraries to link against, <code class="docutils literal notranslate"><span class="pre">library_dirs</span></code> is a list of directories
|
||||
to search for libraries at link-time, and <code class="docutils literal notranslate"><span class="pre">runtime_library_dirs</span></code> is a list of
|
||||
directories to search for shared (dynamically loaded) libraries at run-time.</p>
|
||||
<p>For example, if you need to link against libraries known to be in the standard
|
||||
library search path on target systems</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">libraries</span><span class="o">=</span><span class="p">[</span><span class="s1">'gdbm'</span><span class="p">,</span> <span class="s1">'readline'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you need to link with libraries in a non-standard location, you’ll have to
|
||||
include the location in <code class="docutils literal notranslate"><span class="pre">library_dirs</span></code>:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">library_dirs</span><span class="o">=</span><span class="p">[</span><span class="s1">'/usr/X11R6/lib'</span><span class="p">],</span>
|
||||
<span class="n">libraries</span><span class="o">=</span><span class="p">[</span><span class="s1">'X11'</span><span class="p">,</span> <span class="s1">'Xt'</span><span class="p">])</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>(Again, this sort of non-portable construct should be avoided if you intend to
|
||||
distribute your code.)</p>
|
||||
</div>
|
||||
<div class="section" id="other-options">
|
||||
<h3>2.3.5. Other options<a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h3>
|
||||
<p>There are still some other options which can be used to handle special cases.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">optional</span></code> option is a boolean; if it is true,
|
||||
a build failure in the extension will not abort the build process, but
|
||||
instead simply not install the failing extension.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">extra_objects</span></code> option is a list of object files to be passed to the
|
||||
linker. These files must not have extensions, as the default extension for the
|
||||
compiler is used.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">extra_compile_args</span></code> and <code class="docutils literal notranslate"><span class="pre">extra_link_args</span></code> can be used to
|
||||
specify additional command line options for the respective compiler and linker
|
||||
command lines.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">export_symbols</span></code> is only useful on Windows. It can contain a list of
|
||||
symbols (functions or variables) to be exported. This option is not needed when
|
||||
building compiled extensions: Distutils will automatically add <code class="docutils literal notranslate"><span class="pre">initmodule</span></code>
|
||||
to the list of exported symbols.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">depends</span></code> option is a list of files that the extension depends on
|
||||
(for example header files). The build command will call the compiler on the
|
||||
sources to rebuild extension if any on this files has been modified since the
|
||||
previous build.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="relationships-between-distributions-and-packages">
|
||||
<h2>2.4. Relationships between Distributions and Packages<a class="headerlink" href="#relationships-between-distributions-and-packages" title="Permalink to this headline">¶</a></h2>
|
||||
<p>A distribution may relate to packages in three specific ways:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>It can require packages or modules.</p></li>
|
||||
<li><p>It can provide packages or modules.</p></li>
|
||||
<li><p>It can obsolete packages or modules.</p></li>
|
||||
</ol>
|
||||
<p>These relationships can be specified using keyword arguments to the
|
||||
<a class="reference internal" href="apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.core.setup()</span></code></a> function.</p>
|
||||
<p>Dependencies on other Python modules and packages can be specified by supplying
|
||||
the <em>requires</em> keyword argument to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. The value must be a list of
|
||||
strings. Each string specifies a package that is required, and optionally what
|
||||
versions are sufficient.</p>
|
||||
<p>To specify that any version of a module or package is required, the string
|
||||
should consist entirely of the module or package name. Examples include
|
||||
<code class="docutils literal notranslate"><span class="pre">'mymodule'</span></code> and <code class="docutils literal notranslate"><span class="pre">'xml.parsers.expat'</span></code>.</p>
|
||||
<p>If specific versions are required, a sequence of qualifiers can be supplied in
|
||||
parentheses. Each qualifier may consist of a comparison operator and a version
|
||||
number. The accepted comparison operators are:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span> <span class="o">></span> <span class="o">==</span>
|
||||
<span class="o"><=</span> <span class="o">>=</span> <span class="o">!=</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>These can be combined by using multiple qualifiers separated by commas (and
|
||||
optional whitespace). In this case, all of the qualifiers must be matched; a
|
||||
logical AND is used to combine the evaluations.</p>
|
||||
<p>Let’s look at a bunch of examples:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 35%" />
|
||||
<col style="width: 65%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Requires Expression</p></th>
|
||||
<th class="head"><p>Explanation</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">==1.0</span></code></p></td>
|
||||
<td><p>Only version <code class="docutils literal notranslate"><span class="pre">1.0</span></code> is compatible</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">>1.0,</span> <span class="pre">!=1.5.1,</span> <span class="pre"><2.0</span></code></p></td>
|
||||
<td><p>Any version after <code class="docutils literal notranslate"><span class="pre">1.0</span></code> and before <code class="docutils literal notranslate"><span class="pre">2.0</span></code>
|
||||
is compatible, except <code class="docutils literal notranslate"><span class="pre">1.5.1</span></code></p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Now that we can specify dependencies, we also need to be able to specify what we
|
||||
provide that other distributions can require. This is done using the <em>provides</em>
|
||||
keyword argument to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. The value for this keyword is a list of
|
||||
strings, each of which names a Python module or package, and optionally
|
||||
identifies the version. If the version is not specified, it is assumed to match
|
||||
that of the distribution.</p>
|
||||
<p>Some examples:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 31%" />
|
||||
<col style="width: 69%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Provides Expression</p></th>
|
||||
<th class="head"><p>Explanation</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">mypkg</span></code></p></td>
|
||||
<td><p>Provide <code class="docutils literal notranslate"><span class="pre">mypkg</span></code>, using the distribution
|
||||
version</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">mypkg</span> <span class="pre">(1.1)</span></code></p></td>
|
||||
<td><p>Provide <code class="docutils literal notranslate"><span class="pre">mypkg</span></code> version 1.1, regardless of
|
||||
the distribution version</p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>A package can declare that it obsoletes other packages using the <em>obsoletes</em>
|
||||
keyword argument. The value for this is similar to that of the <em>requires</em>
|
||||
keyword: a list of strings giving module or package specifiers. Each specifier
|
||||
consists of a module or package name optionally followed by one or more version
|
||||
qualifiers. Version qualifiers are given in parentheses after the module or
|
||||
package name.</p>
|
||||
<p>The versions identified by the qualifiers are those that are obsoleted by the
|
||||
distribution being described. If no qualifiers are given, all versions of the
|
||||
named module or package are understood to be obsoleted.</p>
|
||||
</div>
|
||||
<div class="section" id="installing-scripts">
|
||||
<span id="distutils-installing-scripts"></span><h2>2.5. Installing Scripts<a class="headerlink" href="#installing-scripts" title="Permalink to this headline">¶</a></h2>
|
||||
<p>So far we have been dealing with pure and non-pure Python modules, which are
|
||||
usually not run by themselves but imported by scripts.</p>
|
||||
<p>Scripts are files containing Python source code, intended to be started from the
|
||||
command line. Scripts don’t require Distutils to do anything very complicated.
|
||||
The only clever feature is that if the first line of the script starts with
|
||||
<code class="docutils literal notranslate"><span class="pre">#!</span></code> and contains the word “python”, the Distutils will adjust the first line
|
||||
to refer to the current interpreter location. By default, it is replaced with
|
||||
the current interpreter location. The <code class="xref std std-option docutils literal notranslate"><span class="pre">--executable</span></code> (or <code class="xref std std-option docutils literal notranslate"><span class="pre">-e</span></code>)
|
||||
option will allow the interpreter path to be explicitly overridden.</p>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">scripts</span></code> option simply is a list of files to be handled in this
|
||||
way. From the PyXML setup script:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">scripts</span><span class="o">=</span><span class="p">[</span><span class="s1">'scripts/xmlproc_parse'</span><span class="p">,</span> <span class="s1">'scripts/xmlproc_val'</span><span class="p">]</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.1: </span>All the scripts will also be added to the <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code> file if no template is
|
||||
provided. See <a class="reference internal" href="sourcedist.html#manifest"><span class="std std-ref">Specifying the files to distribute</span></a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="installing-package-data">
|
||||
<span id="distutils-installing-package-data"></span><h2>2.6. Installing Package Data<a class="headerlink" href="#installing-package-data" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Often, additional files need to be installed into a package. These files are
|
||||
often data that’s closely related to the package’s implementation, or text files
|
||||
containing documentation that might be of interest to programmers using the
|
||||
package. These files are called <em class="dfn">package data</em>.</p>
|
||||
<p>Package data can be added to packages using the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> keyword
|
||||
argument to the <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> function. The value must be a mapping from
|
||||
package name to a list of relative path names that should be copied into the
|
||||
package. The paths are interpreted as relative to the directory containing the
|
||||
package (information from the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> mapping is used if appropriate);
|
||||
that is, the files are expected to be part of the package in the source
|
||||
directories. They may contain glob patterns as well.</p>
|
||||
<p>The path names may contain directory portions; any necessary directories will be
|
||||
created in the installation.</p>
|
||||
<p>For example, if a package should contain a subdirectory with several data files,
|
||||
the files can be arranged like this in the source tree:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">src</span><span class="o">/</span>
|
||||
<span class="n">mypkg</span><span class="o">/</span>
|
||||
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">module</span><span class="o">.</span><span class="n">py</span>
|
||||
<span class="n">data</span><span class="o">/</span>
|
||||
<span class="n">tables</span><span class="o">.</span><span class="n">dat</span>
|
||||
<span class="n">spoons</span><span class="o">.</span><span class="n">dat</span>
|
||||
<span class="n">forks</span><span class="o">.</span><span class="n">dat</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The corresponding call to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> might be:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'mypkg'</span><span class="p">],</span>
|
||||
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">'mypkg'</span><span class="p">:</span> <span class="s1">'src/mypkg'</span><span class="p">},</span>
|
||||
<span class="n">package_data</span><span class="o">=</span><span class="p">{</span><span class="s1">'mypkg'</span><span class="p">:</span> <span class="p">[</span><span class="s1">'data/*.dat'</span><span class="p">]},</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.1: </span>All the files that match <code class="docutils literal notranslate"><span class="pre">package_data</span></code> will be added to the <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code>
|
||||
file if no template is provided. See <a class="reference internal" href="sourcedist.html#manifest"><span class="std std-ref">Specifying the files to distribute</span></a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="installing-additional-files">
|
||||
<span id="distutils-additional-files"></span><h2>2.7. Installing Additional Files<a class="headerlink" href="#installing-additional-files" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">data_files</span></code> option can be used to specify additional files needed
|
||||
by the module distribution: configuration files, message catalogs, data files,
|
||||
anything which doesn’t fit in the previous categories.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">data_files</span></code> specifies a sequence of (<em>directory</em>, <em>files</em>) pairs in the
|
||||
following way:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">data_files</span><span class="o">=</span><span class="p">[(</span><span class="s1">'bitmaps'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'bm/b1.gif'</span><span class="p">,</span> <span class="s1">'bm/b2.gif'</span><span class="p">]),</span>
|
||||
<span class="p">(</span><span class="s1">'config'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'cfg/data.cfg'</span><span class="p">])],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Each (<em>directory</em>, <em>files</em>) pair in the sequence specifies the installation
|
||||
directory and the files to install there.</p>
|
||||
<p>Each file name in <em>files</em> is interpreted relative to the <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>
|
||||
script at the top of the package source distribution. Note that you can
|
||||
specify the directory where the data files will be installed, but you cannot
|
||||
rename the data files themselves.</p>
|
||||
<p>The <em>directory</em> should be a relative path. It is interpreted relative to the
|
||||
installation prefix (Python’s <code class="docutils literal notranslate"><span class="pre">sys.prefix</span></code> for system installations;
|
||||
<code class="docutils literal notranslate"><span class="pre">site.USER_BASE</span></code> for user installations). Distutils allows <em>directory</em> to be
|
||||
an absolute installation path, but this is discouraged since it is
|
||||
incompatible with the wheel packaging format. No directory information from
|
||||
<em>files</em> is used to determine the final location of the installed file; only
|
||||
the name of the file is used.</p>
|
||||
<p>You can specify the <code class="docutils literal notranslate"><span class="pre">data_files</span></code> options as a simple sequence of files
|
||||
without specifying a target directory, but this is not recommended, and the
|
||||
<strong class="command">install</strong> command will print a warning in this case. To install data
|
||||
files directly in the target directory, an empty string should be given as the
|
||||
directory.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.1: </span>All the files that match <code class="docutils literal notranslate"><span class="pre">data_files</span></code> will be added to the <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code>
|
||||
file if no template is provided. See <a class="reference internal" href="sourcedist.html#manifest"><span class="std std-ref">Specifying the files to distribute</span></a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="additional-meta-data">
|
||||
<span id="meta-data"></span><h2>2.8. Additional meta-data<a class="headerlink" href="#additional-meta-data" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The setup script may include additional meta-data beyond the name and version.
|
||||
This information includes:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 30%" />
|
||||
<col style="width: 36%" />
|
||||
<col style="width: 23%" />
|
||||
<col style="width: 11%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Meta-Data</p></th>
|
||||
<th class="head"><p>Description</p></th>
|
||||
<th class="head"><p>Value</p></th>
|
||||
<th class="head"><p>Notes</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">name</span></code></p></td>
|
||||
<td><p>name of the package</p></td>
|
||||
<td><p>short string</p></td>
|
||||
<td><p>(1)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">version</span></code></p></td>
|
||||
<td><p>version of this release</p></td>
|
||||
<td><p>short string</p></td>
|
||||
<td><p>(1)(2)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">author</span></code></p></td>
|
||||
<td><p>package author’s name</p></td>
|
||||
<td><p>short string</p></td>
|
||||
<td><p>(3)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">author_email</span></code></p></td>
|
||||
<td><p>email address of the
|
||||
package author</p></td>
|
||||
<td><p>email address</p></td>
|
||||
<td><p>(3)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">maintainer</span></code></p></td>
|
||||
<td><p>package maintainer’s name</p></td>
|
||||
<td><p>short string</p></td>
|
||||
<td><p>(3)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">maintainer_email</span></code></p></td>
|
||||
<td><p>email address of the
|
||||
package maintainer</p></td>
|
||||
<td><p>email address</p></td>
|
||||
<td><p>(3)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">url</span></code></p></td>
|
||||
<td><p>home page for the package</p></td>
|
||||
<td><p>URL</p></td>
|
||||
<td><p>(1)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">description</span></code></p></td>
|
||||
<td><p>short, summary
|
||||
description of the
|
||||
package</p></td>
|
||||
<td><p>short string</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">long_description</span></code></p></td>
|
||||
<td><p>longer description of the
|
||||
package</p></td>
|
||||
<td><p>long string</p></td>
|
||||
<td><p>(4)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">download_url</span></code></p></td>
|
||||
<td><p>location where the
|
||||
package may be downloaded</p></td>
|
||||
<td><p>URL</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">classifiers</span></code></p></td>
|
||||
<td><p>a list of classifiers</p></td>
|
||||
<td><p>list of strings</p></td>
|
||||
<td><p>(6)(7)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">platforms</span></code></p></td>
|
||||
<td><p>a list of platforms</p></td>
|
||||
<td><p>list of strings</p></td>
|
||||
<td><p>(6)(8)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">keywords</span></code></p></td>
|
||||
<td><p>a list of keywords</p></td>
|
||||
<td><p>list of strings</p></td>
|
||||
<td><p>(6)(8)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">license</span></code></p></td>
|
||||
<td><p>license for the package</p></td>
|
||||
<td><p>short string</p></td>
|
||||
<td><p>(5)</p></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Notes:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>These fields are required.</p></li>
|
||||
<li><p>It is recommended that versions take the form <em>major.minor[.patch[.sub]]</em>.</p></li>
|
||||
<li><p>Either the author or the maintainer must be identified. If maintainer is
|
||||
provided, distutils lists it as the author in <code class="file docutils literal notranslate"><span class="pre">PKG-INFO</span></code>.</p></li>
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">long_description</span></code> field is used by PyPI when you publish a package,
|
||||
to build its project page.</p></li>
|
||||
<li><p>The <code class="docutils literal notranslate"><span class="pre">license</span></code> field is a text indicating the license covering the
|
||||
package where the license is not a selection from the “License” Trove
|
||||
classifiers. See the <code class="docutils literal notranslate"><span class="pre">Classifier</span></code> field. Notice that
|
||||
there’s a <code class="docutils literal notranslate"><span class="pre">licence</span></code> distribution option which is deprecated but still
|
||||
acts as an alias for <code class="docutils literal notranslate"><span class="pre">license</span></code>.</p></li>
|
||||
<li><p>This field must be a list.</p></li>
|
||||
<li><p>The valid classifiers are listed on
|
||||
<a class="reference external" href="https://pypi.org/classifiers">PyPI</a>.</p></li>
|
||||
<li><p>To preserve backward compatibility, this field also accepts a string. If
|
||||
you pass a comma-separated string <code class="docutils literal notranslate"><span class="pre">'foo,</span> <span class="pre">bar'</span></code>, it will be converted to
|
||||
<code class="docutils literal notranslate"><span class="pre">['foo',</span> <span class="pre">'bar']</span></code>, Otherwise, it will be converted to a list of one
|
||||
string.</p></li>
|
||||
</ol>
|
||||
<dl class="simple">
|
||||
<dt>‘short string’</dt><dd><p>A single line of text, not more than 200 characters.</p>
|
||||
</dd>
|
||||
<dt>‘long string’</dt><dd><p>Multiple lines of plain text in reStructuredText format (see
|
||||
<a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a>).</p>
|
||||
</dd>
|
||||
<dt>‘list of strings’</dt><dd><p>See below.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<p>Encoding the version information is an art in itself. Python packages generally
|
||||
adhere to the version format <em>major.minor[.patch][sub]</em>. The major number is 0
|
||||
for initial, experimental releases of software. It is incremented for releases
|
||||
that represent major milestones in a package. The minor number is incremented
|
||||
when important new features are added to the package. The patch number
|
||||
increments when bug-fix releases are made. Additional trailing version
|
||||
information is sometimes used to indicate sub-releases. These are
|
||||
“a1,a2,…,aN” (for alpha releases, where functionality and API may change),
|
||||
“b1,b2,…,bN” (for beta releases, which only fix bugs) and “pr1,pr2,…,prN”
|
||||
(for final pre-release release testing). Some examples:</p>
|
||||
<dl class="simple">
|
||||
<dt>0.1.0</dt><dd><p>the first, experimental release of a package</p>
|
||||
</dd>
|
||||
<dt>1.0.1a2</dt><dd><p>the second alpha release of the first patch version of 1.0</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">classifiers</span></code> must be specified in a list:</p>
|
||||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
|
||||
<span class="n">classifiers</span><span class="o">=</span><span class="p">[</span>
|
||||
<span class="s1">'Development Status :: 4 - Beta'</span><span class="p">,</span>
|
||||
<span class="s1">'Environment :: Console'</span><span class="p">,</span>
|
||||
<span class="s1">'Environment :: Web Environment'</span><span class="p">,</span>
|
||||
<span class="s1">'Intended Audience :: End Users/Desktop'</span><span class="p">,</span>
|
||||
<span class="s1">'Intended Audience :: Developers'</span><span class="p">,</span>
|
||||
<span class="s1">'Intended Audience :: System Administrators'</span><span class="p">,</span>
|
||||
<span class="s1">'License :: OSI Approved :: Python Software Foundation License'</span><span class="p">,</span>
|
||||
<span class="s1">'Operating System :: MacOS :: MacOS X'</span><span class="p">,</span>
|
||||
<span class="s1">'Operating System :: Microsoft :: Windows'</span><span class="p">,</span>
|
||||
<span class="s1">'Operating System :: POSIX'</span><span class="p">,</span>
|
||||
<span class="s1">'Programming Language :: Python'</span><span class="p">,</span>
|
||||
<span class="s1">'Topic :: Communications :: Email'</span><span class="p">,</span>
|
||||
<span class="s1">'Topic :: Office/Business'</span><span class="p">,</span>
|
||||
<span class="s1">'Topic :: Software Development :: Bug Tracking'</span><span class="p">,</span>
|
||||
<span class="p">],</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.7: </span><a class="reference internal" href="apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-class docutils literal notranslate"><span class="pre">setup</span></code></a> now warns when <code class="docutils literal notranslate"><span class="pre">classifiers</span></code>, <code class="docutils literal notranslate"><span class="pre">keywords</span></code>
|
||||
or <code class="docutils literal notranslate"><span class="pre">platforms</span></code> fields are not specified as a list or a string.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="debugging-the-setup-script">
|
||||
<span id="debug-setup-script"></span><h2>2.9. Debugging the setup script<a class="headerlink" href="#debugging-the-setup-script" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Sometimes things go wrong, and the setup script doesn’t do what the developer
|
||||
wants.</p>
|
||||
<p>Distutils catches any exceptions when running the setup script, and print a
|
||||
simple error message before the script is terminated. The motivation for this
|
||||
behaviour is to not confuse administrators who don’t know much about Python and
|
||||
are trying to install a package. If they get a big long traceback from deep
|
||||
inside the guts of Distutils, they may think the package or the Python
|
||||
installation is broken because they don’t read all the way down to the bottom
|
||||
and see that it’s a permission problem.</p>
|
||||
<p>On the other hand, this doesn’t help the developer to find the cause of the
|
||||
failure. For this purpose, the <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">DISTUTILS_DEBUG</span></code> environment variable can be set
|
||||
to anything except an empty string, and distutils will now print detailed
|
||||
information about what it is doing, dump the full traceback when an exception
|
||||
occurs, and print the whole command line when an external program (like a C
|
||||
compiler) fails.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">2. Writing the Setup Script</a><ul>
|
||||
<li><a class="reference internal" href="#listing-whole-packages">2.1. Listing whole packages</a></li>
|
||||
<li><a class="reference internal" href="#listing-individual-modules">2.2. Listing individual modules</a></li>
|
||||
<li><a class="reference internal" href="#describing-extension-modules">2.3. Describing extension modules</a><ul>
|
||||
<li><a class="reference internal" href="#extension-names-and-packages">2.3.1. Extension names and packages</a></li>
|
||||
<li><a class="reference internal" href="#extension-source-files">2.3.2. Extension source files</a></li>
|
||||
<li><a class="reference internal" href="#preprocessor-options">2.3.3. Preprocessor options</a></li>
|
||||
<li><a class="reference internal" href="#library-options">2.3.4. Library options</a></li>
|
||||
<li><a class="reference internal" href="#other-options">2.3.5. Other options</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#relationships-between-distributions-and-packages">2.4. Relationships between Distributions and Packages</a></li>
|
||||
<li><a class="reference internal" href="#installing-scripts">2.5. Installing Scripts</a></li>
|
||||
<li><a class="reference internal" href="#installing-package-data">2.6. Installing Package Data</a></li>
|
||||
<li><a class="reference internal" href="#installing-additional-files">2.7. Installing Additional Files</a></li>
|
||||
<li><a class="reference internal" href="#additional-meta-data">2.8. Additional meta-data</a></li>
|
||||
<li><a class="reference internal" href="#debugging-the-setup-script">2.9. Debugging the setup script</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h4>Previous topic</h4>
|
||||
<p class="topless"><a href="introduction.html"
|
||||
title="previous chapter">1. An Introduction to Distutils</a></p>
|
||||
<h4>Next topic</h4>
|
||||
<p class="topless"><a href="configfile.html"
|
||||
title="next chapter">3. Writing the Setup Configuration File</a></p>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/setupscript.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="configfile.html" title="3. Writing the Setup Configuration File"
|
||||
>next</a> |</li>
|
||||
<li class="right" >
|
||||
<a href="introduction.html" title="1. An Introduction to Distutils"
|
||||
>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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
403
python-3.7.4-docs-html/distutils/sourcedist.html
Normal file
403
python-3.7.4-docs-html/distutils/sourcedist.html
Normal file
@@ -0,0 +1,403 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>4. Creating a Source Distribution — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="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" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/sourcedist.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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="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="https://www.python.org/">Python</a> »</li>
|
||||
<li>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">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="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<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 internal" href="introduction.html#distutils-simple-example"><span class="std std-ref">A Simple Example</span></a>, you use the <strong class="command">sdist</strong> command
|
||||
to create a source distribution. In the simplest case,</p>
|
||||
<div class="highlight-python3 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">sdist</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>(assuming you haven’t specified any <strong class="command">sdist</strong> options in the setup script
|
||||
or config file), <strong class="command">sdist</strong> creates the archive of the default format for
|
||||
the current platform. The default format is a gzip’ed tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.gz</span></code>) on Unix, and ZIP file on Windows.</p>
|
||||
<p>You can specify as many formats as you like using the <code class="xref std std-option docutils literal notranslate"><span class="pre">--formats</span></code>
|
||||
option, for example:</p>
|
||||
<div class="highlight-python3 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">sdist</span> <span class="o">--</span><span class="n">formats</span><span class="o">=</span><span class="n">gztar</span><span class="p">,</span><span class="nb">zip</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>to create a gzipped tarball and a zip file. The available formats are:</p>
|
||||
<table class="docutils align-center">
|
||||
<colgroup>
|
||||
<col style="width: 24%" />
|
||||
<col style="width: 56%" />
|
||||
<col style="width: 20%" />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr class="row-odd"><th class="head"><p>Format</p></th>
|
||||
<th class="head"><p>Description</p></th>
|
||||
<th class="head"><p>Notes</p></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">zip</span></code></p></td>
|
||||
<td><p>zip file (<code class="file docutils literal notranslate"><span class="pre">.zip</span></code>)</p></td>
|
||||
<td><p>(1),(3)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">gztar</span></code></p></td>
|
||||
<td><p>gzip’ed tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.gz</span></code>)</p></td>
|
||||
<td><p>(2)</p></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">bztar</span></code></p></td>
|
||||
<td><p>bzip2’ed tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.bz2</span></code>)</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">xztar</span></code></p></td>
|
||||
<td><p>xz’ed tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.xz</span></code>)</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">ztar</span></code></p></td>
|
||||
<td><p>compressed tar file
|
||||
(<code class="file docutils literal notranslate"><span class="pre">.tar.Z</span></code>)</p></td>
|
||||
<td><p>(4)</p></td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">tar</span></code></p></td>
|
||||
<td><p>tar file (<code class="file docutils literal notranslate"><span class="pre">.tar</span></code>)</p></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for the <code class="docutils literal notranslate"><span class="pre">xztar</span></code> format.</p>
|
||||
</div>
|
||||
<p>Notes:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>default on Windows</p></li>
|
||||
<li><p>default on Unix</p></li>
|
||||
<li><p>requires either external <strong class="program">zip</strong> utility or <a class="reference internal" href="../library/zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> module (part
|
||||
of the standard Python library since Python 1.6)</p></li>
|
||||
<li><p>requires the <strong class="program">compress</strong> program. Notice that this format is now
|
||||
pending for deprecation and will be removed in the future versions of Python.</p></li>
|
||||
</ol>
|
||||
<p>When using any <code class="docutils literal notranslate"><span class="pre">tar</span></code> format (<code class="docutils literal notranslate"><span class="pre">gztar</span></code>, <code class="docutils literal notranslate"><span class="pre">bztar</span></code>, <code class="docutils literal notranslate"><span class="pre">xztar</span></code>, <code class="docutils literal notranslate"><span class="pre">ztar</span></code> or
|
||||
<code class="docutils literal notranslate"><span class="pre">tar</span></code>), under Unix you can specify the <code class="docutils literal notranslate"><span class="pre">owner</span></code> and <code class="docutils literal notranslate"><span class="pre">group</span></code> names
|
||||
that will be set for each member of the archive.</p>
|
||||
<p>For example, if you want all files of the archive to be owned by root:</p>
|
||||
<div class="highlight-python3 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">sdist</span> <span class="o">--</span><span class="n">owner</span><span class="o">=</span><span class="n">root</span> <span class="o">--</span><span class="n">group</span><span class="o">=</span><span class="n">root</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<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 class="command">sdist</strong> command puts a minimal default set into the
|
||||
source distribution:</p>
|
||||
<ul class="simple">
|
||||
<li><p>all Python source files implied by the <code class="docutils literal notranslate"><span class="pre">py_modules</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">packages</span></code> options</p></li>
|
||||
<li><p>all C source files mentioned in the <code class="docutils literal notranslate"><span class="pre">ext_modules</span></code> or
|
||||
<code class="docutils literal notranslate"><span class="pre">libraries</span></code> options</p>
|
||||
</li>
|
||||
<li><p>scripts identified by the <code class="docutils literal notranslate"><span class="pre">scripts</span></code> option
|
||||
See <a class="reference internal" href="setupscript.html#distutils-installing-scripts"><span class="std std-ref">Installing Scripts</span></a>.</p></li>
|
||||
<li><p>anything that looks like a test script: <code class="file docutils literal notranslate"><span class="pre">test/test*.py</span></code> (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)</p></li>
|
||||
<li><p>Any of the standard README files (<code class="file docutils literal notranslate"><span class="pre">README</span></code>, <code class="file docutils literal notranslate"><span class="pre">README.txt</span></code>,
|
||||
or <code class="file docutils literal notranslate"><span class="pre">README.rst</span></code>), <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> (or whatever you called your setup
|
||||
script), and <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>.</p></li>
|
||||
<li><p>all files that matches the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> metadata.
|
||||
See <a class="reference internal" href="setupscript.html#distutils-installing-package-data"><span class="std std-ref">Installing Package Data</span></a>.</p></li>
|
||||
<li><p>all files that matches the <code class="docutils literal notranslate"><span class="pre">data_files</span></code> metadata.
|
||||
See <a class="reference internal" href="setupscript.html#distutils-additional-files"><span class="std std-ref">Installing Additional Files</span></a>.</p></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 <code class="file docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> by default. The manifest template is just a list of
|
||||
instructions for how to generate your manifest file, <code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code>, which is
|
||||
the exact list of files to include in your source distribution. The
|
||||
<strong class="command">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
|
||||
<code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code>, you must specify everything: the default set of files
|
||||
described above does not apply in this case.</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.1: </span>An existing generated <code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code> will be regenerated without
|
||||
<strong class="command">sdist</strong> comparing its modification time to the one of
|
||||
<code class="file docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> or <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.1.3: </span><code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code> files start with a comment indicating they are generated.
|
||||
Files without this comment are not overwritten or removed.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.2.2: </span><strong class="command">sdist</strong> will read a <code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code> file if no <code class="file docutils literal notranslate"><span class="pre">MANIFEST.in</span></code>
|
||||
exists, like it used to do.</p>
|
||||
</div>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 3.7: </span><code class="file docutils literal notranslate"><span class="pre">README.rst</span></code> is now included in the list of distutils standard READMEs.</p>
|
||||
</div>
|
||||
<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-none notranslate"><div class="highlight"><pre><span></span>include *.txt
|
||||
recursive-include examples *.txt *.py
|
||||
prune examples/sample?/build
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The meanings should be fairly clear: include all files in the distribution root
|
||||
matching <code class="file docutils literal notranslate"><span class="pre">*.txt</span></code>, all files anywhere under the <code class="file docutils literal notranslate"><span class="pre">examples</span></code> directory
|
||||
matching <code class="file docutils literal notranslate"><span class="pre">*.txt</span></code> or <code class="file docutils literal notranslate"><span class="pre">*.py</span></code>, and exclude all directories matching
|
||||
<code class="file docutils literal notranslate"><span class="pre">examples/sample?/build</span></code>. 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
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">--no-defaults</span></code> option to disable the standard set entirely.) There are
|
||||
several other commands available in the manifest template mini-language; see
|
||||
section <a class="reference internal" href="commandref.html#sdist-cmd"><span class="std std-ref">Creating a source distribution: the sdist command</span></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><p>all files in the Distutils “build” tree (default <code class="file docutils literal notranslate"><span class="pre">build/</span></code>)</p></li>
|
||||
<li><p>all files in directories named <code class="file docutils literal notranslate"><span class="pre">RCS</span></code>, <code class="file docutils literal notranslate"><span class="pre">CVS</span></code>, <code class="file docutils literal notranslate"><span class="pre">.svn</span></code>,
|
||||
<code class="file docutils literal notranslate"><span class="pre">.hg</span></code>, <code class="file docutils literal notranslate"><span class="pre">.git</span></code>, <code class="file docutils literal notranslate"><span class="pre">.bzr</span></code> or <code class="file docutils literal notranslate"><span class="pre">_darcs</span></code></p></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
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">--no-defaults</span></code> option, and you can disable the standard exclude set
|
||||
with <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-prune</span></code>.</p>
|
||||
<p>Following the Distutils’ own manifest template, let’s trace how the
|
||||
<strong class="command">sdist</strong> command builds the list of files to include in the Distutils
|
||||
source distribution:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>include all Python source files in the <code class="file docutils literal notranslate"><span class="pre">distutils</span></code> and
|
||||
<code class="file docutils literal notranslate"><span class="pre">distutils/command</span></code> subdirectories (because packages corresponding to
|
||||
those two directories were mentioned in the <code class="docutils literal notranslate"><span class="pre">packages</span></code> option in the
|
||||
setup script—see section <a class="reference internal" href="setupscript.html#setup-script"><span class="std std-ref">Writing the Setup Script</span></a>)</p></li>
|
||||
<li><p>include <code class="file docutils literal notranslate"><span class="pre">README.txt</span></code>, <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, and <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> (standard
|
||||
files)</p></li>
|
||||
<li><p>include <code class="file docutils literal notranslate"><span class="pre">test/test*.py</span></code> (standard files)</p></li>
|
||||
<li><p>include <code class="file docutils literal notranslate"><span class="pre">*.txt</span></code> in the distribution root (this will find
|
||||
<code class="file docutils literal notranslate"><span class="pre">README.txt</span></code> a second time, but such redundancies are weeded out later)</p></li>
|
||||
<li><p>include anything matching <code class="file docutils literal notranslate"><span class="pre">*.txt</span></code> or <code class="file docutils literal notranslate"><span class="pre">*.py</span></code> in the sub-tree
|
||||
under <code class="file docutils literal notranslate"><span class="pre">examples</span></code>,</p></li>
|
||||
<li><p>exclude all files in the sub-trees starting at directories matching
|
||||
<code class="file docutils literal notranslate"><span class="pre">examples/sample?/build</span></code>—this may exclude files included by the
|
||||
previous two steps, so it’s important that the <code class="docutils literal notranslate"><span class="pre">prune</span></code> command in the manifest
|
||||
template comes after the <code class="docutils literal notranslate"><span class="pre">recursive-include</span></code> command</p></li>
|
||||
<li><p>exclude the entire <code class="file docutils literal notranslate"><span class="pre">build</span></code> tree, and any <code class="file docutils literal notranslate"><span class="pre">RCS</span></code>, <code class="file docutils literal notranslate"><span class="pre">CVS</span></code>,
|
||||
<code class="file docutils literal notranslate"><span class="pre">.svn</span></code>, <code class="file docutils literal notranslate"><span class="pre">.hg</span></code>, <code class="file docutils literal notranslate"><span class="pre">.git</span></code>, <code class="file docutils literal notranslate"><span class="pre">.bzr</span></code> and <code class="file docutils literal notranslate"><span class="pre">_darcs</span></code>
|
||||
directories</p></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 class="command">sdist</strong> command is as follows:</p>
|
||||
<ul class="simple">
|
||||
<li><p>if the manifest file (<code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code> by default) exists and the first line
|
||||
does not have a comment indicating it is generated from <code class="file docutils literal notranslate"><span class="pre">MANIFEST.in</span></code>,
|
||||
then it is used as is, unaltered</p></li>
|
||||
<li><p>if the manifest file doesn’t exist or has been previously automatically
|
||||
generated, read <code class="file docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> and create the manifest</p></li>
|
||||
<li><p>if neither <code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code> nor <code class="file docutils literal notranslate"><span class="pre">MANIFEST.in</span></code> exist, create a manifest
|
||||
with just the default file set</p></li>
|
||||
<li><p>use the list of files now in <code class="file docutils literal notranslate"><span class="pre">MANIFEST</span></code> (either just generated or read
|
||||
in) to create the source distribution archive(s)</p></li>
|
||||
</ul>
|
||||
<p>There are a couple of options that modify this behaviour. First, use the
|
||||
<code class="xref std std-option docutils literal notranslate"><span class="pre">--no-defaults</span></code> and <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-prune</span></code> 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-python3 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">sdist</span> <span class="o">--</span><span class="n">manifest</span><span class="o">-</span><span class="n">only</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p><code class="xref std std-option docutils literal notranslate"><span class="pre">-o</span></code> is a shortcut for <code class="xref std std-option docutils literal notranslate"><span class="pre">--manifest-only</span></code>.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">4. Creating a Source Distribution</a><ul>
|
||||
<li><a class="reference internal" href="#specifying-the-files-to-distribute">4.1. Specifying the files to distribute</a></li>
|
||||
<li><a class="reference internal" 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>
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/sourcedist.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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="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="https://www.python.org/">Python</a> »</li>
|
||||
<li>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
161
python-3.7.4-docs-html/distutils/uploading.html
Normal file
161
python-3.7.4-docs-html/distutils/uploading.html
Normal file
@@ -0,0 +1,161 @@
|
||||
|
||||
<!DOCTYPE html>
|
||||
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Uploading Packages to the Package Index — Python 3.7.4 documentation</title>
|
||||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||||
|
||||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
||||
|
||||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||||
|
||||
<link rel="search" type="application/opensearchdescription+xml"
|
||||
title="Search within Python 3.7.4 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="shortcut icon" type="image/png" href="../_static/py.png" />
|
||||
<link rel="canonical" href="https://docs.python.org/3/distutils/uploading.html" />
|
||||
|
||||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||||
|
||||
|
||||
|
||||
<style>
|
||||
@media only screen {
|
||||
table.full-width-table {
|
||||
width: 100%;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head><body>
|
||||
|
||||
<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><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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="document">
|
||||
<div class="documentwrapper">
|
||||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="uploading-packages-to-the-package-index">
|
||||
<h1>Uploading Packages to the Package Index<a class="headerlink" href="#uploading-packages-to-the-package-index" title="Permalink to this headline">¶</a></h1>
|
||||
<p>References to up to date PyPI documentation can be found at
|
||||
<a class="reference internal" href="../distributing/index.html#publishing-python-packages"><span class="std std-ref">Reading the Python Packaging User Guide</span></a>.</p>
|
||||
</div>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||||
<div class="sphinxsidebarwrapper">
|
||||
<div role="note" aria-label="source link">
|
||||
<h3>This Page</h3>
|
||||
<ul class="this-page-menu">
|
||||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||||
<li>
|
||||
<a href="https://github.com/python/cpython/blob/3.7/Doc/distutils/uploading.rst"
|
||||
rel="nofollow">Show Source
|
||||
</a>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</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><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>
|
||||
<span class="language_switcher_placeholder">en</span>
|
||||
<span class="version_switcher_placeholder">3.7.4</span>
|
||||
<a href="../index.html">Documentation </a> »
|
||||
</li>
|
||||
|
||||
<li class="right">
|
||||
|
||||
|
||||
<div class="inline-search" style="display: none" role="search">
|
||||
<form class="inline-search" action="../search.html" method="get">
|
||||
<input placeholder="Quick search" type="text" name="q" />
|
||||
<input type="submit" value="Go" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||||
|
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer">
|
||||
© <a href="../copyright.html">Copyright</a> 2001-2019, 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 Jul 13, 2019.
|
||||
<a href="../bugs.html">Found a bug</a>?
|
||||
<br />
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user