Update Guide to 4c11901

Signed-off-by: Michał Górny <mgorny@gentoo.org>

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>