GNU bug report logs -
#47709
[PATCH 0/2] Augment build phases and build system doc
Previous Next
Reported by: Ludovic Courtès <ludo <at> gnu.org>
Date: Sun, 11 Apr 2021 13:39:01 UTC
Severity: normal
Tags: patch
Done: Ludovic Courtès <ludo <at> gnu.org>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 47709 in the body.
You can then email your comments to 47709 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
guix-patches <at> gnu.org
:
bug#47709
; Package
guix-patches
.
(Sun, 11 Apr 2021 13:39:01 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Ludovic Courtès <ludo <at> gnu.org>
:
New bug report received and forwarded. Copy sent to
guix-patches <at> gnu.org
.
(Sun, 11 Apr 2021 13:39:02 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
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
Information forwarded
to
guix-patches <at> gnu.org
:
bug#47709
; Package
guix-patches
.
(Sun, 11 Apr 2021 13:47:01 GMT)
Full text and
rfc822 format available.
Message #8 received at 47709 <at> debbugs.gnu.org (full text, mbox):
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 <at> 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 <at> footnote{We present a simplified view of those build phases, but
--
2.31.1
Information forwarded
to
guix-patches <at> gnu.org
:
bug#47709
; Package
guix-patches
.
(Sun, 11 Apr 2021 13:47:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 47709 <at> debbugs.gnu.org (full text, mbox):
* 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 <at> 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
Information forwarded
to
guix-patches <at> gnu.org
:
bug#47709
; Package
guix-patches
.
(Sun, 11 Apr 2021 15:00:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 47709 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
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 <at> 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.
[signature.asc (application/pgp-signature, inline)]
Information forwarded
to
guix-patches <at> gnu.org
:
bug#47709
; Package
guix-patches
.
(Mon, 12 Apr 2021 12:18:01 GMT)
Full text and
rfc822 format available.
Message #17 received at 47709 <at> debbugs.gnu.org (full text, mbox):
Hi,
Maxime Devos <maximedevos <at> 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’.
Reply sent
to
Ludovic Courtès <ludo <at> gnu.org>
:
You have taken responsibility.
(Mon, 12 Apr 2021 16:46:01 GMT)
Full text and
rfc822 format available.
Notification sent
to
Ludovic Courtès <ludo <at> gnu.org>
:
bug acknowledged by developer.
(Mon, 12 Apr 2021 16:46:01 GMT)
Full text and
rfc822 format available.
Message #22 received at 47709-done <at> debbugs.gnu.org (full text, mbox):
Hi!
I went ahead and pushed as d14f21389c7faeb8a763ebbcf1b8aa1ba4deade9.
Ludo’.
Information forwarded
to
guix-patches <at> gnu.org
:
bug#47709
; Package
guix-patches
.
(Mon, 12 Apr 2021 16:46:02 GMT)
Full text and
rfc822 format available.
Message #25 received at 47709-done <at> debbugs.gnu.org (full text, mbox):
Hi!
I went ahead and pushed as d14f21389c7faeb8a763ebbcf1b8aa1ba4deade9.
Ludo’.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Tue, 11 May 2021 11:24:05 GMT)
Full text and
rfc822 format available.
This bug report was last modified 2 years and 349 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.