[bug#47709] [PATCH 0/2] Augment build phases and build system doc

[bug#47709] [PATCH 0/2] Augment build phases and build system doc

[Ludovic Courtès]

Hi there!

Since we’re approaching string freeze, here are changes I’d like to
push before people start translating again.

The first one move build phase documentation in one place.  The
second one documents some of the import keyword parameters of
‘gnu-build-system’ and related build systems.

Thoughts?

Ludo’.

Ludovic Courtès (2):
  doc: Move list of build phases to "Build Phases".
  doc: Document 'gnu-build-system' keyword parameters.

 doc/guix.texi | 186 ++++++++++++++++++++++++++++++++++----------------
 1 file changed, 127 insertions(+), 59 deletions(-)

-- 
2.31.1

[bug#47709] [PATCH 1/2] doc: Move list of build phases to "Build Phases".

[Ludovic Courtès]

Before this change, the 'gnu-build-system' phases were listed in the
"Build Systems" section, and then summarized in the "Build Phases"
section.  This moves everything to "Build Phases".

* doc/guix.texi (Build Systems): Move phase table to...
(Build Phases): ... here.  Rearrange surrounding text.
---
 doc/guix.texi | 108 +++++++++++++++++++++++---------------------------
 1 file changed, 49 insertions(+), 59 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 218ff35ce9..c8d3422189 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7297,55 +7297,7 @@ standards, GNU Coding Standards}).
 In a nutshell, packages using it are configured, built, and installed with
 the usual @code{./configure && make && make check && make install}
 command sequence.  In practice, a few additional steps are often needed.
-All these steps are split up in separate @dfn{phases},
-notably@footnote{Please see the @code{(guix build gnu-build-system)}
-modules for more details about the build phases.}:
-
-@table @code
-@item unpack
-Unpack the source tarball, and change the current directory to the
-extracted source tree.  If the source is actually a directory, copy it
-to the build tree, and enter that directory.
-
-@item patch-source-shebangs
-Patch shebangs encountered in source files so they refer to the right
-store file names.  For instance, this changes @code{#!/bin/sh} to
-@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
-
-@item configure
-Run the @file{configure} script with a number of default options, such
-as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
-by the @code{#:configure-flags} argument.
-
-@item build
-Run @code{make} with the list of flags specified with
-@code{#:make-flags}.  If the @code{#:parallel-build?} argument is true
-(the default), build with @code{make -j}.
-
-@item check
-Run @code{make check}, or some other target specified with
-@code{#:test-target}, unless @code{#:tests? #f} is passed.  If the
-@code{#:parallel-tests?} argument is true (the default), run @code{make
-check -j}.
-
-@item install
-Run @code{make install} with the flags listed in @code{#:make-flags}.
-
-@item patch-shebangs
-Patch shebangs on the installed executable files.
-
-@item strip
-Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
-is false), copying them to the @code{debug} output when available
-(@pxref{Installing Debugging Files}).
-@end table
-
-@vindex %standard-phases
-The build-side module @code{(guix build gnu-build-system)} defines
-@code{%standard-phases} as the default list of build phases.
-@code{%standard-phases} is a list of symbol/procedure pairs, where the
-procedure implements the actual phase.
-
+All these steps are split up in separate @dfn{phases}.
 @xref{Build Phases}, for more info on build phases and ways to customize
 them.
 
@@ -8249,16 +8201,53 @@ exception is the ``bare-bones'' @code{trivial-build-system}
 (@pxref{Build Systems}).
 
 As discussed in the previous section, those build systems provide a
-standard list of phases.  For @code{gnu-build-system}, the standard
-phases include an @code{unpack} phase to unpack the source code tarball,
-a @command{configure} phase to run @code{./configure}, a @code{build}
-phase to run @command{make}, and (among others) an @code{install} phase
-to run @command{make install}; @pxref{Build Systems}, for a more
-detailed view of these phases.  Likewise, @code{cmake-build-system}
-inherits these phases, but its @code{configure} phase runs
-@command{cmake} instead of @command{./configure}.  Other build systems,
-such as @code{python-build-system}, have a wholly different list of
-standard phases.  All this code runs on the @dfn{build side}: it is
+standard list of phases.  For @code{gnu-build-system}, the main build
+phases are the following:
+
+@table @code
+@item unpack
+Unpack the source tarball, and change the current directory to the
+extracted source tree.  If the source is actually a directory, copy it
+to the build tree, and enter that directory.
+
+@item patch-source-shebangs
+Patch shebangs encountered in source files so they refer to the right
+store file names.  For instance, this changes @code{#!/bin/sh} to
+@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
+
+@item configure
+Run the @file{configure} script with a number of default options, such
+as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
+by the @code{#:configure-flags} argument.
+
+@item build
+Run @code{make} with the list of flags specified with
+@code{#:make-flags}.  If the @code{#:parallel-build?} argument is true
+(the default), build with @code{make -j}.
+
+@item check
+Run @code{make check}, or some other target specified with
+@code{#:test-target}, unless @code{#:tests? #f} is passed.  If the
+@code{#:parallel-tests?} argument is true (the default), run @code{make
+check -j}.
+
+@item install
+Run @code{make install} with the flags listed in @code{#:make-flags}.
+
+@item patch-shebangs
+Patch shebangs on the installed executable files.
+
+@item strip
+Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
+is false), copying them to the @code{debug} output when available
+(@pxref{Installing Debugging Files}).
+@end table
+
+Other build systems have similar phases, with some variations.  For
+example, @code{cmake-build-system} has same-named phases but its
+@code{configure} phases runs @code{cmake} instead of @code{./configure}.
+Others, such as @code{python-build-system}, have a wholly different list
+of standard phases.  All this code runs on the @dfn{build side}: it is
 evaluated when you actually build the package, in a dedicated build
 process spawned by the build daemon (@pxref{Invoking guix-daemon}).
 
@@ -8269,6 +8258,7 @@ is a procedure that accepts an arbitrary number of arguments.  By
 convention, those procedures receive information about the build in the
 form of @dfn{keyword parameters}, which they can use or ignore.
 
+@vindex %standard-phases
 For example, here is how @code{(guix build gnu-build-system)} defines
 @code{%standard-phases}, the variable holding its alist of build
 phases@footnote{We present a simplified view of those build phases, but
-- 
2.31.1

[bug#47709] [PATCH 2/2] doc: Document 'gnu-build-system' keyword parameters.

[Ludovic Courtès]

* doc/guix.texi (Build Systems): Document keyword parameters of
'gnu-build-system'.
---
 doc/guix.texi | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index c8d3422189..12245003d4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7307,6 +7307,84 @@ Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
 build-system gnu)} module for a complete list).  We call these the
 @dfn{implicit inputs} of a package, because package definitions do not
 have to mention them.
+
+This build system supports a number of keyword arguments, which can be
+passed @i{via} the @code{arguments} field of a package.  Here are some
+of the main parameters:
+
+@table @code
+@item #:phases
+This argument specifies build-side code that evaluates to an alist of
+build phases.  @xref{Build Phases}, for more information.
+
+@item #:configure-flags
+This is a list of flags (strings) passed to the @command{configure}
+script.  @xref{Defining Packages}, for an example.
+
+@item #:make-flags
+This list of strings contains flags passed as arguments to
+@command{make} invocations in the @code{build}, @code{check}, and
+@code{install} phases.
+
+@item #:out-of-source?
+This Boolean, @code{#f} by default, indicates whether to run builds in a
+build directory separate from the source tree.
+
+When it is true, the @code{configure} phase creates a separate build
+directory, changes to that directory, and runs the @code{configure}
+script from there.  This is useful for packages that require it, such as
+@code{glibc}.
+
+@item #:tests?
+This Boolean, @code{#t} by default, indicates whether the @code{check}
+phase should run the package's test suite.
+
+@item #:test-target
+This string, @code{"check"} by default, gives the name of the makefile
+target used by the @code{check} phase.
+
+@item #:parallel-build?
+@itemx #:parallel-tests?
+These Boolean values specify whether to build, respectively run the test
+suite, in parallel, with the @code{-j} flag of @command{make}.  When
+they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
+the number specified as the @option{--cores} option of
+@command{guix-daemon} or that of the @command{guix} client command
+(@pxref{Common Build Options, @option{--cores}}).
+
+@cindex RUNPATH, validation
+@item #:validate-runpath?
+This Boolean, @code{#t} by default, determines whether to ``validate''
+the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
+as executables) previously installed by the @code{install} phase.
+
+This validation step consists in making sure that all the shared
+libraries needed by an ELF binaries, which are listed as
+@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
+@code{DT_RUNPATH} entry of that binary.  In other words, it ensures that
+running or using those binaries will not result in a ``file not found''
+error at run time.  @xref{Options, @option{-rpath},, ld, The GNU
+Linker}, for more information on @code{RUNPATH}.
+
+@item #:substitutable?
+This Boolean, @code{#t} by default, tells whether the package outputs
+should be substitutable---i.e., whether users should be able to obtain
+substitutes for them instead of building locally (@pxref{Substitutes}).
+
+@item #:allowed-references
+@itemx #:disallowed-references
+When true, these arguments must be a list of dependencies that must not
+appear among the references of the build results.  If, upon build
+completion, some of these references are retained, the build process
+fails.
+
+This is useful to ensure that a package does not erroneously keep a
+reference to some of it build-time inputs, in cases where doing so
+would, for example, unnecessarily increase its size (@pxref{Invoking
+guix size}).
+@end table
+
+Most other build systems support these keyword arguments.
 @end defvr
 
 Other @code{<build-system>} objects are defined to support other
-- 
2.31.1

[bug#47709] [PATCH 2/2] doc: Document 'gnu-build-system' keyword parameters.

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 4443 bytes --]

Some small remarks:

On Sun, 2021-04-11 at 15:46 +0200, Ludovic Courtès wrote:
> 
> [...]
> @@ -7307,6 +7307,84 @@ Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
>  build-system gnu)} module for a complete list).  We call these the
>  @dfn{implicit inputs} of a package, because package definitions do not
>  have to mention them.
> +
> +This build system supports a number of keyword arguments, which can be
> +passed @i{via}

Why the italics?  I've heard some people italicise "via" because it's a foreign
word (from Latin), but I'm not convinced.  I don't see anyone italicising
"broccoli", even though it is Italian (going by
https://en.wiktionary.org/wiki/broccoli).

>  the @code{arguments} field of a package.  Here are some
> +of the main parameters:
> +
> +@table @code
> +@item #:phases
> +This argument specifies build-side code that evaluates to an alist of
> +build phases.  @xref{Build Phases}, for more information.
> +
> +@item #:configure-flags
> +This is a list of flags (strings) passed to the @command{configure}
> +script.  @xref{Defining Packages}, for an example.
> +
> +@item #:make-flags
> +This list of strings contains flags passed as arguments to
> +@command{make} invocations in the @code{build}, @code{check}, and
> +@code{install} phases.
> +
> +@item #:out-of-source?
> +This Boolean,
‘Boolean’ is miscapitalised.

>  @code{#f} by default, indicates whether to run builds in a
> +build directory separate from the source tree.
> +
> +When it is true, the @code{configure} phase creates a separate build
> +directory, changes to that directory, and runs the @code{configure}
> +script from there.  This is useful for packages that require it, such as
> +@code{glibc}.
> +
> +@item #:tests?
> +This Boolean, @code{#t} by default, indicates whether the @code{check}
> +phase should run the package's test suite.

Likewise (miscapitalised).
> +@item #:test-target
> +This string, @code{"check"} by default, gives the name of the makefile
> +target used by the @code{check} phase.
> +
> +@item #:parallel-build?
> +@itemx #:parallel-tests?
> +These Boolean values specify whether to build, respectively run the test
Likewise (miscapitalised).
> +suite, in parallel, with the @code{-j} flag of @command{make}.  When
> +they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
> +the number specified as the @option{--cores} option of
> +@command{guix-daemon} or that of the @command{guix} client command
> +(@pxref{Common Build Options, @option{--cores}}).
> +
> +@cindex RUNPATH, validation
> +@item #:validate-runpath?
> +This Boolean, @code{#t} by default, determines whether to ``validate''
Likewise (miscapitalised).

> +the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
> +as executables) previously installed by the @code{install} phase.
> +
> +This validation step consists in making sure that all the shared
> +libraries needed by an ELF binaries, which are listed as
> +@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
> +@code{DT_RUNPATH} entry of that binary.  In other words, it ensures that
> +running or using those binaries will not result in a ``file not found''
> +error at run time.  @xref{Options, @option{-rpath},, ld, The GNU
> +Linker}, for more information on @code{RUNPATH}.
> +
> +@item #:substitutable?
> +This Boolean, @code{#t} by default, tells whether the package outputs

Likewise (miscapitalised).

> +should be substitutable---i.e., whether users should be able to obtain
> +substitutes for them instead of building locally (@pxref{Substitutes}).
> +
> +@item #:allowed-references
> +@itemx #:disallowed-references
> +When true, these arguments must be a list of dependencies that must not
> +appear among the references of the build results.  If, upon build
> +completion, some of these references are retained, the build process
> +fails.
> +
> +This is useful to ensure that a package does not erroneously keep a
> +reference to some of it build-time inputs, in cases where doing so
> +would, for example, unnecessarily increase its size (@pxref{Invoking
> +guix size}).
> +@end table
> +
> +Most other build systems support these keyword arguments.
>  @end defvr
>  
>  Other @code{<build-system>} objects are defined to support other

No other remarks. LGTM

Greetings,
Maxime.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

[bug#47709] [PATCH 2/2] doc: Document 'gnu-build-system' keyword parameters.

[Ludovic Courtès]

Hi,

Maxime Devos <maximedevos@telenet.be> skribis:

> On Sun, 2021-04-11 at 15:46 +0200, Ludovic Courtès wrote:
>> 
>> [...]
>> @@ -7307,6 +7307,84 @@ Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
>>  build-system gnu)} module for a complete list).  We call these the
>>  @dfn{implicit inputs} of a package, because package definitions do not
>>  have to mention them.
>> +
>> +This build system supports a number of keyword arguments, which can be
>> +passed @i{via}
>
> Why the italics?  I've heard some people italicise "via" because it's a foreign
> word (from Latin), but I'm not convinced.

Italicizing foreign words is a typographical convention.

> I don't see anyone italicising "broccoli", even though it is Italian
> (going by https://en.wiktionary.org/wiki/broccoli).

True.  :-)

>> +@item #:out-of-source?
>> +This Boolean,
> ‘Boolean’ is miscapitalised.

I don’t think so: it derives from a family name, and my understanding is
that the convention is to capitalize such words; the lower-case variant
“boolean” is definitely widespread, though.

Thanks for taking a look!

Ludo’.

bug#47709: [PATCH 0/2] Augment build phases and build system doc

[Ludovic Courtès]

Hi!

I went ahead and pushed as d14f21389c7faeb8a763ebbcf1b8aa1ba4deade9.

Ludo’.

[bug#47709] [PATCH 0/2] Augment build phases and build system doc

[Ludovic Courtès]

Hi!

I went ahead and pushed as d14f21389c7faeb8a763ebbcf1b8aa1ba4deade9.

Ludo’.