summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'guide/distutils.html')
-rw-r--r--guide/distutils.html66
1 files changed, 39 insertions, 27 deletions
diff --git a/guide/distutils.html b/guide/distutils.html
index e097cbc..ee6cade 100644
--- a/guide/distutils.html
+++ b/guide/distutils.html
@@ -126,7 +126,8 @@ files. This has some implications, notably:</p>
<ol class="arabic simple">
<li><p>If the package uses setuptools_scm or a similar package, the version
string needs to be provided explicitly,
-cf. <a class="reference internal" href="#setuptools-scm-flit-scm-hatch-vcs-and-snapshots">setuptools_scm (flit_scm, hatch-vcs) and snapshots</a>.</p></li>
+cf. <a class="reference internal" href="#setuptools-scm-flit-scm-hatch-vcs-pdm-backend-and-snapshots">setuptools_scm (flit_scm, hatch-vcs, pdm-backend)
+and snapshots</a>.</p></li>
<li><p>If the package uses Cython, the C files need to be generated
and an explicit <code class="docutils literal notranslate"><span class="pre">BDEPEND</span></code> on <code class="docutils literal notranslate"><span class="pre">dev-python/cython</span></code> needs to
be added. However, regenerating them is recommended anyway,
@@ -280,20 +281,24 @@ The eclass maintains a mapping of backend paths to the respective
<td><p>dev-python/pdm-pep517</p></td>
<td><p>pdm.pep517.api</p></td>
</tr>
-<tr class="row-odd"><td><p>poetry</p></td>
+<tr class="row-odd"><td><p>pdm-backend</p></td>
+<td><p>dev-python/pdm-backend</p></td>
+<td><p>pdm.backend</p></td>
+</tr>
+<tr class="row-even"><td><p>poetry</p></td>
<td><p>dev-python/poetry-core</p></td>
<td><p>poetry.core.masonry.api</p></td>
</tr>
-<tr class="row-even"><td><p>setuptools</p></td>
+<tr class="row-odd"><td><p>setuptools</p></td>
<td><p>dev-python/setuptools</p></td>
<td><p>setuptools.build_meta
setuptools.__legacy__.build_meta</p></td>
</tr>
-<tr class="row-odd"><td><p>sip</p></td>
+<tr class="row-even"><td><p>sip</p></td>
<td><p>dev-python/sip</p></td>
<td><p>sipbuild.api</p></td>
</tr>
-<tr class="row-even"><td><p>standalone</p></td>
+<tr class="row-odd"><td><p>standalone</p></td>
<td><p>(none)</p></td>
<td><p>(various, see below)</p></td>
</tr>
@@ -309,9 +314,9 @@ backend.</p>
the <code class="docutils literal notranslate"><span class="pre">setuptools</span></code> backend (this applies to pure distutils packages
as well). The eclass automatically uses the legacy setuptools backend
for them.</p>
-<span class="target" id="index-2"></span><span class="target" id="index-3"></span><span class="target" id="index-4"></span></section>
-<section id="setuptools-scm-flit-scm-hatch-vcs-and-snapshots">
-<span id="index-5"></span><h2>setuptools_scm (flit_scm, hatch-vcs) and snapshots<a class="headerlink" href="#setuptools-scm-flit-scm-hatch-vcs-and-snapshots" title="Permalink to this heading">¶</a></h2>
+<span class="target" id="index-2"></span><span class="target" id="index-3"></span><span class="target" id="index-4"></span><span class="target" id="index-5"></span></section>
+<section id="setuptools-scm-flit-scm-hatch-vcs-pdm-backend-and-snapshots">
+<span id="index-6"></span><h2>setuptools_scm (flit_scm, hatch-vcs, pdm-backend) and snapshots<a class="headerlink" href="#setuptools-scm-flit-scm-hatch-vcs-pdm-backend-and-snapshots" title="Permalink to this heading">¶</a></h2>
<p><a class="reference external" href="https://pypi.org/project/setuptools-scm/">setuptools_scm</a> is a package providing additional features for running
inside a VCS checkout, in particular the ability to determine version
from VCS tags. However, this works correctly only when the package
@@ -358,9 +363,16 @@ the package build, setuptools may install incomplete set of package
data files. Please take special care to verify that all files are
installed.</p>
</div>
+<p>The <a class="reference external" href="https://pypi.org/project/pdm-backend/">pdm-backend</a> package reinvents its own SCM version support,
+and unlike setuptools_scm, it uses <code class="docutils literal notranslate"><span class="pre">0.0.0</span></code> rather than throwing
+an error when the version cannot be determined. The override for this
+backend can be set using a similarly purposed environment variable:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span><span class="w"> </span><span class="nv">PDM_BUILD_SCM_VERSION</span><span class="o">=</span><span class="si">${</span><span class="nv">PV</span><span class="si">}</span>
+</pre></div>
+</div>
</section>
<section id="packages-installing-extensions-c-rust">
-<span id="index-6"></span><h2>Packages installing extensions (C, Rust…)<a class="headerlink" href="#packages-installing-extensions-c-rust" title="Permalink to this heading">¶</a></h2>
+<span id="index-7"></span><h2>Packages installing extensions (C, Rust…)<a class="headerlink" href="#packages-installing-extensions-c-rust" title="Permalink to this heading">¶</a></h2>
<p>Python extensions are compiled (C, Cython, Rust…) loadable modules.
They can generally be recognized by the presence of <code class="docutils literal notranslate"><span class="pre">.so</span></code> files
in site-packages directory.</p>
@@ -403,7 +415,7 @@ is missing:</p>
</div>
</section>
<section id="packages-using-cython">
-<span id="index-7"></span><h2>Packages using Cython<a class="headerlink" href="#packages-using-cython" title="Permalink to this heading">¶</a></h2>
+<span id="index-8"></span><h2>Packages using Cython<a class="headerlink" href="#packages-using-cython" title="Permalink to this heading">¶</a></h2>
<p><a class="reference external" href="https://cython.org/">Cython</a> is a static compiler that permits writing Python extensions
in a hybrid of C and Python. Cython files are compiled into C code
that is compatible with multiple Python interpreters. This makes it
@@ -502,8 +514,8 @@ run in the following order:</p>
defining <code class="docutils literal notranslate"><span class="pre">${BUILD_DIR}</span></code> to a dedicated build directory for each
implementation. However, if in-source builds are enabled, all phases
are run in these build directories.</p>
-<span class="target" id="index-8"></span><section id="python-prepare">
-<span id="index-9"></span><h3>python_prepare<a class="headerlink" href="#python-prepare" title="Permalink to this heading">¶</a></h3>
+<span class="target" id="index-9"></span><section id="python-prepare">
+<span id="index-10"></span><h3>python_prepare<a class="headerlink" href="#python-prepare" title="Permalink to this heading">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">python_prepare_all</span></code> is responsible for applying changes
to the package sources that are common to all Python implementations.
The default implementation performs the tasks of <code class="docutils literal notranslate"><span class="pre">default_src_prepare</span></code>
@@ -545,9 +557,9 @@ enables in-source builds.</p>
<span class="o">}</span>
</pre></div>
</div>
-<span class="target" id="index-10"></span></section>
+<span class="target" id="index-11"></span></section>
<section id="python-configure">
-<span id="index-11"></span><h3>python_configure<a class="headerlink" href="#python-configure" title="Permalink to this heading">¶</a></h3>
+<span id="index-12"></span><h3>python_configure<a class="headerlink" href="#python-configure" title="Permalink to this heading">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">python_configure</span></code> and <code class="docutils literal notranslate"><span class="pre">python_configure_all</span></code> have no default
functionality. The former is convenient for running additional
configuration steps if needed by the package, the latter for defining
@@ -565,9 +577,9 @@ global environment variables.</p>
<span class="o">}</span>
</pre></div>
</div>
-<span class="target" id="index-12"></span></section>
+<span class="target" id="index-13"></span></section>
<section id="python-compile">
-<span id="index-13"></span><h3>python_compile<a class="headerlink" href="#python-compile" title="Permalink to this heading">¶</a></h3>
+<span id="index-14"></span><h3>python_compile<a class="headerlink" href="#python-compile" title="Permalink to this heading">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">python_compile</span></code> normally builds the package. It is sometimes used
to pass additional arguments to the build step. For example, it can
be used to disable parallel extension builds in packages that are broken
@@ -586,9 +598,9 @@ the documentation (see <code class="docutils literal notranslate"><span class="p
<span class="o">}</span>
</pre></div>
</div>
-<span class="target" id="index-14"></span></section>
+<span class="target" id="index-15"></span></section>
<section id="python-test">
-<span id="index-15"></span><h3>python_test<a class="headerlink" href="#python-test" title="Permalink to this heading">¶</a></h3>
+<span id="index-16"></span><h3>python_test<a class="headerlink" href="#python-test" title="Permalink to this heading">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">python_test</span></code> is responsible for running tests. It has no default
implementation but you are strongly encouraged to provide one (either
directly or via <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code>). <code class="docutils literal notranslate"><span class="pre">python_test_all</span></code>
@@ -599,9 +611,9 @@ to Python.</p>
<span class="o">}</span>
</pre></div>
</div>
-<span class="target" id="index-16"></span></section>
+<span class="target" id="index-17"></span></section>
<section id="python-install">
-<span id="index-17"></span><h3>python_install<a class="headerlink" href="#python-install" title="Permalink to this heading">¶</a></h3>
+<span id="index-18"></span><h3>python_install<a class="headerlink" href="#python-install" title="Permalink to this heading">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">python_install</span></code> installs the package’s Python part. It is usually
redefined in order to pass additional <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> arguments
or to install additional Python modules.</p>
@@ -630,7 +642,7 @@ such as bash completions or examples.</p>
</section>
</section>
<section id="passing-arguments-to-setup-py">
-<span id="index-18"></span><h2>Passing arguments to setup.py<a class="headerlink" href="#passing-arguments-to-setup-py" title="Permalink to this heading">¶</a></h2>
+<span id="index-19"></span><h2>Passing arguments to setup.py<a class="headerlink" href="#passing-arguments-to-setup-py" title="Permalink to this heading">¶</a></h2>
<p>There are two main methods of accepting additional command-line options
in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> scripts: using global options and via command options.</p>
<p>Global options are usually implemented through manipulating <code class="docutils literal notranslate"><span class="pre">sys.path</span></code>
@@ -669,7 +681,7 @@ take boolean arguments. In this case, the ebuild can use:</p>
</div>
</section>
<section id="calling-custom-setup-py-commands">
-<span id="index-19"></span><h2>Calling custom setup.py commands<a class="headerlink" href="#calling-custom-setup-py-commands" title="Permalink to this heading">¶</a></h2>
+<span id="index-20"></span><h2>Calling custom setup.py commands<a class="headerlink" href="#calling-custom-setup-py-commands" title="Permalink to this heading">¶</a></h2>
<p>When working on packages using setuptools or modified distutils, you
sometimes need to manually invoke <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>. The eclass provides
a <code class="docutils literal notranslate"><span class="pre">esetup.py</span></code> helper that wraps it with additional checks, error
@@ -687,7 +699,7 @@ beforehand (much like <code class="docutils literal notranslate"><span class="pr
<p>The support for test suites is now covered in the <a class="reference internal" href="test.html"><span class="doc">Tests in Python packages</span></a> chapter.</p>
</section>
<section id="building-documentation-via-sphinx">
-<span id="index-20"></span><h2>Building documentation via Sphinx<a class="headerlink" href="#building-documentation-via-sphinx" title="Permalink to this heading">¶</a></h2>
+<span id="index-21"></span><h2>Building documentation via Sphinx<a class="headerlink" href="#building-documentation-via-sphinx" title="Permalink to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code> is commonly used to document Python packages.
It comes with a number of plugins and themes that make it convenient
to write and combine large text documents (such as this Guide!),
@@ -803,10 +815,10 @@ If additional packages need to be installed, the previous variant
must be used instead.</p>
<p>The eclass tries to automatically determine whether <code class="docutils literal notranslate"><span class="pre">--no-autodoc</span></code>
should be used, and issue a warning if it’s missing or incorrect.</p>
-<span class="target" id="index-21"></span></section>
+<span class="target" id="index-22"></span></section>
</section>
<section id="packages-with-optional-python-build-system-usage">
-<span id="index-22"></span><h2>Packages with optional Python build system usage<a class="headerlink" href="#packages-with-optional-python-build-system-usage" title="Permalink to this heading">¶</a></h2>
+<span id="index-23"></span><h2>Packages with optional Python build system usage<a class="headerlink" href="#packages-with-optional-python-build-system-usage" title="Permalink to this heading">¶</a></h2>
<p>The eclass has been written with the assumption that the vast majority
of its consumers will be using the Python build systems unconditionally.
For this reason, it sets the ebuild metadata variables (dependencies,
@@ -915,7 +927,7 @@ follows:</p>
</div>
</section>
<section id="packages-with-rust-extensions-using-cargo">
-<span id="index-23"></span><h2>Packages with Rust extensions (using Cargo)<a class="headerlink" href="#packages-with-rust-extensions-using-cargo" title="Permalink to this heading">¶</a></h2>
+<span id="index-24"></span><h2>Packages with Rust extensions (using Cargo)<a class="headerlink" href="#packages-with-rust-extensions-using-cargo" title="Permalink to this heading">¶</a></h2>
<p>Some Python build systems include support for writing extensions
in the Rust programming language. Two examples of these are setuptools
using <code class="docutils literal notranslate"><span class="pre">dev-python/setuptools_rust</span></code> plugin and Maturin. Normally,
@@ -1160,7 +1172,7 @@ python_install<span class="o">()</span><span class="w"> </span><span class="o">{
<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="#python-single-r1-variant">python-single-r1 variant</a></li>
<li class="toctree-l2"><a class="reference internal" href="#pep-517-build-systems">PEP 517 build systems</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#setuptools-scm-flit-scm-hatch-vcs-and-snapshots">setuptools_scm (flit_scm, hatch-vcs) and snapshots</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#setuptools-scm-flit-scm-hatch-vcs-pdm-backend-and-snapshots">setuptools_scm (flit_scm, hatch-vcs, pdm-backend) and snapshots</a></li>
<li class="toctree-l2"><a class="reference internal" href="#packages-installing-extensions-c-rust">Packages installing extensions (C, Rust…)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#packages-using-cython">Packages using Cython</a></li>
<li class="toctree-l2"><a class="reference internal" href="#parallel-build-race-conditions">Parallel build race conditions</a></li>