summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2023-11-12 22:47:43 +0100
committerLudovic Courtès <ludo@gnu.org>2023-12-22 00:31:40 +0100
commitd9190abbd20f15ea5b55abdd51e1376f05055850 (patch)
tree295c14c1542f402a581df51b7489441ef1d1b2eb /doc
parent4771960e5d559d2f3911fd24fd648fa5e97bdf39 (diff)
gexp: Add compiler for <gexp-input>.
* guix/gexp.scm (gexp-input-compiler): New procedure. * tests/gexp.scm ("gexp references non-existent output") ("gexp-input, as first-class input"): New tests. * doc/guix.texi (G-Expressions): Document it. Reviewed-by: Maxim Cournoyer <maxim.cournoyer@gmail.com> Change-Id: I95b58d6e4d77a54364026b4324fbb00125a9402e
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi38
1 files changed, 38 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index b742a3d5b2..a760d627eb 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12197,6 +12197,11 @@ This is like the form above, but referring explicitly to the
@var{output} of @var{obj}---this is useful when @var{obj} produces
multiple outputs (@pxref{Packages with Multiple Outputs}).
+Sometimes a gexp unconditionally refers to the @code{"out"} output, but
+the user of that gexp would still like to insert a reference to another
+output. The @code{gexp-input} procedure aims to address that.
+@xref{gexp-input}.
+
@item #+@var{obj}
@itemx #+@var{obj}:output
@itemx (ungexp-native @var{obj})
@@ -12590,6 +12595,39 @@ The example above returns an object that corresponds to the i686 build
of Coreutils, regardless of the current value of @code{%current-system}.
@end defmac
+@anchor{gexp-input}
+@deffn {Procedure} gexp-input @var{obj} [@var{output}] [#:native? #f]
+Return a @dfn{gexp input} record for the given @var{output} of file-like
+object @var{obj}, with @code{#:native?} determining whether this is a
+native reference (as with @code{ungexp-native}) or not.
+
+This procedure is helpful when you want to pass a reference to a
+specific output of an object to some procedure that may not know about
+that output. For example, assume you have this procedure, which takes
+one file-like object:
+
+@lisp
+(define (make-symlink target)
+ (computed-file "the-symlink"
+ #~(symlink #$target #$output)))
+@end lisp
+
+Here @code{make-symlink} can only ever refer to the default output of
+@var{target}---the @code{"out"} output (@pxref{Packages with Multiple
+Outputs}). To have it refer to, say, the @code{"lib"} output of the
+@code{hwloc} package, you can call it like so:
+
+@lisp
+(make-symlink (gexp-input hwloc "lib"))
+@end lisp
+
+You can also compose it like any other file-like object:
+
+@lisp
+(make-symlink
+ (file-append (gexp-input hwloc "lib") "/lib/libhwloc.so"))
+@end lisp
+@end deffn
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are