From 628944b6f4267c4eeb5884074298b82c8d17548c Mon Sep 17 00:00:00 2001 From: Marius Bakke 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(-) diff --git a/doc/contributing.texi b/doc/contributing.texi index 4b1eed1cb1..b9260267fa 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -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. diff --git a/doc/guix.texi b/doc/guix.texi index f0fb383005..145aa16afd 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -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