From 15e79d93ad61e719ab63a8f775b9093219d85771 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Thu, 4 Dec 2025 15:00:23 +0100 Subject: [PATCH] =?UTF-8?q?doc:=20Use=20a=20gexp=20in=20=E2=80=9CDefining?= =?UTF-8?q?=20Packages=E2=80=9D.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Defining Packages): Update ‘arguments’ field in example to use ‘list’ and a gexp. Remove description of quote/unquote; document gexps instead. Change-Id: I2ed1f5796d76e8c389227aed58fd31aa76edbb9a Signed-off-by: Gabriel Wicki --- doc/guix.texi | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 8292b251e28a22a55c410e141484d833d01cfc3a..b88e35ce965d388d2329bbc20d8da296e4b126fb 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7888,7 +7888,8 @@ package looks like this: (base32 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) (build-system gnu-build-system) - (arguments '(#:configure-flags '("--enable-silent-rules"))) + (arguments + (list #:configure-flags #~(list "--enable-silent-rules"))) (inputs (list gawk)) (synopsis "Hello, GNU world: An example GNU package") (description "Guess what GNU Hello prints!") @@ -7899,7 +7900,7 @@ package looks like this: @noindent Without being a Scheme expert, the reader may have guessed the meaning of the various fields here. This expression binds the variable -@code{hello} to a @code{} object, which is essentially a record +@code{hello} to a @code{} record (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}). This package object can be inspected using procedures found in the @code{(guix packages)} module; for instance, @code{(package-name hello)} @@ -7957,32 +7958,30 @@ The @code{arguments} field specifies options for the build system @code{gnu-build-system} as a request run @file{configure} with the @option{--enable-silent-rules} flag. -@cindex quote -@cindex quoting -@findex ' -@findex quote -@cindex backquote (quasiquote) -@findex ` -@findex quasiquote -@cindex comma (unquote) -@findex , -@findex unquote -What about these quote (@code{'}) characters? They are Scheme syntax to -introduce a literal list; @code{'} is synonymous with @code{quote}. -Sometimes you'll also see @code{`} (a backquote, synonymous with -@code{quasiquote}) and @code{,} (a comma, synonymous with @code{unquote}). -@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual}, -for details. Here the value of the @code{arguments} field is a list of -arguments passed to the build system down the road, as with @code{apply} +The value of the @code{arguments} field is a list of arguments passed to +the build system and that end up being applied, as with @code{apply} (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). +@cindex keyword arguments, for build systems The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword} (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and @code{#:configure-flags} is a keyword used to pass a keyword argument to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile Reference Manual}). +@findex #~ +@findex gexp +@cindex staging, for build system arguments +@cindex code staging, in package definitions +What about these hash-tilde (@code{#~}) characters? This is +Guix-specific syntax introducing a so-called @dfn{G-expression} +(@pxref{G-Expressions}), which denotes code that is @dfn{staged} for +eventual evaluation: this staged code is only evaluated if and when +attempting to build the package, by the build daemon. In this example, +the staged code is the @code{(list @dots{})} expression, which builds a +list of one element, the configure flag. + @item The @code{inputs} field specifies inputs to the build process---i.e., build-time or run-time dependencies of the package. Here, we add