From: Maxime Devos <maximedevos@telenet.be>
To: "Ludovic Courtès" <ludo@gnu.org>, 47709@debbugs.gnu.org
Subject: [bug#47709] [PATCH 2/2] doc: Document 'gnu-build-system' keyword parameters.
Date: Sun, 11 Apr 2021 16:59:40 +0200 [thread overview]
Message-ID: <4d9dddc71c70c5449843989515f59ca71720f3f7.camel@telenet.be> (raw)
In-Reply-To: <20210411134606.26449-2-ludo@gnu.org>
[-- 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 --]
next prev parent reply other threads:[~2021-04-11 15:00 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-11 13:37 [bug#47709] [PATCH 0/2] Augment build phases and build system doc Ludovic Courtès
2021-04-11 13:46 ` [bug#47709] [PATCH 1/2] doc: Move list of build phases to "Build Phases" Ludovic Courtès
2021-04-11 13:46 ` [bug#47709] [PATCH 2/2] doc: Document 'gnu-build-system' keyword parameters Ludovic Courtès
2021-04-11 14:59 ` Maxime Devos [this message]
2021-04-12 12:17 ` Ludovic Courtès
2021-04-12 16:45 ` bug#47709: [PATCH 0/2] Augment build phases and build system doc Ludovic Courtès
2021-04-12 16:45 ` [bug#47709] " Ludovic Courtès
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4d9dddc71c70c5449843989515f59ca71720f3f7.camel@telenet.be \
--to=maximedevos@telenet.be \
--cc=47709@debbugs.gnu.org \
--cc=ludo@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/guix.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.