doc: Mention quoting and keywords.

Suggested by Vincent Legoll <vincent.legoll@gmail.com>.

* doc/guix.texi (Defining Packages): Remove quasiquote in 'arguments'
example.  Mention quoting and keywords, with references to Guile's
manual.
master
Ludovic Courtès 2016-07-22 14:39:29 +02:00
parent 782170c4f5
commit 654c0d97c9
No known key found for this signature in database
GPG Key ID: 090B11993D9AEBB5
1 changed files with 33 additions and 1 deletions

View File

@ -2387,7 +2387,7 @@ package looks like this:
(base32 (base32
"0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
(build-system gnu-build-system) (build-system gnu-build-system)
(arguments `(#:configure-flags '("--enable-silent-rules"))) (arguments '(#:configure-flags '("--enable-silent-rules")))
(inputs `(("gawk" ,gawk))) (inputs `(("gawk" ,gawk)))
(synopsis "Hello, GNU world: An example GNU package") (synopsis "Hello, GNU world: An example GNU package")
(description "Guess what GNU Hello prints!") (description "Guess what GNU Hello prints!")
@ -2452,12 +2452,44 @@ The @code{arguments} field specifies options for the build system
@var{gnu-build-system} as a request run @file{configure} with the @var{gnu-build-system} as a request run @file{configure} with the
@code{--enable-silent-rules} flag. @code{--enable-silent-rules} flag.
@cindex quote
@cindex quoting
@findex '
@findex quote
What about these quote (@code{'}) characters? They are Scheme syntax to
introduce a literal list; @code{'} is synonymous with @code{quote}.
@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}
(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
Manual}).
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}).
@item @item
The @code{inputs} field specifies inputs to the build process---i.e., The @code{inputs} field specifies inputs to the build process---i.e.,
build-time or run-time dependencies of the package. Here, we define an build-time or run-time dependencies of the package. Here, we define an
input called @code{"gawk"} whose value is that of the @var{gawk} input called @code{"gawk"} whose value is that of the @var{gawk}
variable; @var{gawk} is itself bound to a @code{<package>} object. variable; @var{gawk} is itself bound to a @code{<package>} object.
@cindex backquote (quasiquote)
@findex `
@findex quasiquote
@cindex comma (unquote)
@findex ,
@findex unquote
@findex ,@@
@findex unquote-splicing
Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
us to introduce a literal list in the @code{inputs} field, while
@code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
Reference Manual}).
Note that GCC, Coreutils, Bash, and other essential tools do not need to Note that GCC, Coreutils, Bash, and other essential tools do not need to
be specified as inputs here. Instead, @var{gnu-build-system} takes care be specified as inputs here. Instead, @var{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}). of ensuring that they are present (@pxref{Build Systems}).