diff options
Diffstat (limited to 'doc/contributing.texi')
| -rw-r--r-- | doc/contributing.texi | 36 |
1 files changed, 28 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. |