diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 36 | ||||
| -rw-r--r-- | doc/guix.texi | 29 |
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 |