summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLars-Dominik Braun <lars@6xq.net>2022-04-23 11:36:55 +0200
committerMarius Bakke <marius@gnu.org>2022-10-27 19:43:06 +0200
commit400a7a4c80efbde1905ae98a298bbb5882d46a0d (patch)
tree151375e9dab1ace78459c2e1e852991e9bdb6acb /doc
parentb4e2effb30bdcbab00dbe1af3e2b9d4ad446897e (diff)
build-system: Add pyproject-build-system.
This is an experimental build system based on python-build-system that implements PEP 517-compliant builds. * doc/guix.texi (Build Systems): Add pyproject-build-system section. * doc/contributing.texi (Python Modules): Mention pyproject.toml and the PYTHON-TOOLCHAIN package, as well as differences to python-build-system. * guix/build-system/pyproject.scm, guix/build/pyproject-build-system.scm, gnu/packages/aux-files/python/sanity-check-next.py, gnu/packages/python-commencement.scm: New files. * Makefile.am (MODULES): Register the new build systems. * gnu/local.mk (GNU_SYSTEM_MODULES): Add python-commencement.scm. * gnu/packages/python.scm (python-sans-pip, python-sans-pip-wrapper): New variables. Co-authored-by: Marius Bakke <marius@gnu.org>
Diffstat (limited to 'doc')
-rw-r--r--doc/contributing.texi36
-rw-r--r--doc/guix.texi29
2 files changed, 57 insertions, 8 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 4b1eed1cb1..c3221d23e4 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -786,12 +786,29 @@ for instance, the module python-dateutil is packaged under the names
starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
described above.
+@quotation Note
+Currently there are two different build systems for Python packages in Guix:
+@var{python-build-system} and @var{pyproject-build-system}. For the
+longest time, Python packages were built from an informally specified
+@file{setup.py} file. That worked amazingly well, considering Python's
+success, but was difficult to build tooling around. As a result, a host
+of alternative build systems emerged and the community eventually settled on a
+@url{https://peps.python.org/pep-0517/, formal standard} for specifying build
+requirements. @var{pyproject-build-system} is Guix's implementation of this
+standard. It is considered ``experimental'' in that it does not yet support
+all the various PEP-517 @emph{build backends}, but you are encouraged to try
+it for new Python packages and report any problems. It will eventually be
+deprecated and merged into @var{python-build-system}.
+@end quotation
+
@subsubsection Specifying Dependencies
@cindex inputs, for Python packages
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 +819,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 +833,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 2f7ab61aec..3bfb89bc33 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -9313,7 +9313,36 @@ 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 based on @var{python-build-system}, and adds support for
+@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517}.
+It also supports a variety of build backends and test frameworks.
+
+The API is slightly different from @var{python-build-system}:
+@itemize
+@item
+@code{#:use-setuptools?} and @code{#:test-target} is removed.
+@item
+@code{#:build-backend} is added. It defaults to @code{#false} and will try
+to guess the appropriate backend based on @file{pyproject.toml}.
+@item
+@code{#:test-backend} is added. It defaults to @code{#false} and will guess
+an appropriate test backend based on what is available in package inputs.
+@item
+@code{#:test-flags} is added. The default is @code{#false}, and varies based
+on the detected @code{#:test-backend}.
+@end itemize
+
+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}). The API is subject to
+change, but any breaking changes in the Guix channel will be dealt with.
+Eventually this build system will be deprecated and merged back into
+@var{python-build-system}, probably some time in 2024.
@end defvr
@defvr {Scheme Variable} perl-build-system