From 628944b6f4267c4eeb5884074298b82c8d17548c Mon Sep 17 00:00:00 2001
From: Marius Bakke <marius@gnu.org>
Date: Tue, 18 Oct 2022 23:38:39 +0200
Subject: [PATCH] doc: Document pyproject-build-system.
* doc/guix.texi (Build Systems): Add pyproject-build-system section.
* doc/contributing.texi (Python Modules): Mention pyproject.toml and the
PYTHON-TOOLCHAIN package.
---
doc/contributing.texi | 21 +++++++++++++--------
doc/guix.texi | 14 ++++++++++++++
2 files changed, 27 insertions(+), 8 deletions(-)
@@ -791,7 +791,9 @@ described above.
Dependency information for Python packages is usually available in the
package source tree, with varying degrees of accuracy: in the
-@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
+@file{pyproject.toml} file, the @file{setup.py} file, in
+@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for
+test dependencies).
Your mission, when writing a recipe for a Python package, is to map
these dependencies to the appropriate type of ``input'' (@pxref{package
@@ -802,10 +804,12 @@ following check list to determine which dependency goes where.
@itemize
@item
-We currently package Python 2 with @code{setuptools} and @code{pip}
-installed like Python 3.4 has per default. Thus you don't need to
-specify either of these as an input. @command{guix lint} will warn you
-if you do.
+We currently package Python with @code{setuptools} and @code{pip}
+installed per default. This is about to change, and users are encouraged
+to use @code{python-toolchain} if they want a build environment for Python.
+
+@command{guix lint} will warn if @code{setuptools} or @code{pip} are
+added as native-inputs because they are generally not necessary.
@item
Python dependencies required at run time go into
@@ -814,9 +818,10 @@ Python dependencies required at run time go into
@file{requirements.txt} file.
@item
-Python packages required only at build time---e.g., those listed with
-the @code{setup_requires} keyword in @file{setup.py}---or only for
-testing---e.g., those in @code{tests_require}---go into
+Python packages required only at build time---e.g., those listed under
+@code{build-system.requires} in @file{pyproject.toml} or with the
+@code{setup_requires} keyword in @file{setup.py}---or dependencies only
+for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
@code{native-inputs}. The rationale is that (1) they do not need to be
propagated because they are not needed at run time, and (2) in a
cross-compilation context, it's the ``native'' input that we'd want.
@@ -9311,7 +9311,21 @@ instead of the default @code{"out"} output. This is useful for packages that
include a Python package as only a part of the software, and thus want to
combine the phases of @code{python-build-system} with another build system.
Python bindings are a common usecase.
+@end defvr
+
+@defvr {Scheme Variable} pyproject-build-system
+This is a variable exported by @code{guix build-system pyproject}. It
+is a reimplementation of @code{python-build-system} designed around
+@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517},
+and supports a variety of build backends and test frameworks.
+
+It is considered ``experimental'' in that the implementation details are
+not set in stone yet, however users are encouraged to try it for new
+Python projects (even those using @file{setup.py}) and there should not
+be any breaking changes.
+Eventually this build system will be deprecated and merged back into
+@code{python-build-system}, probably some time in 2024.
@end defvr
@defvr {Scheme Variable} perl-build-system
--
2.38.0