gexp: Add 'delayed-object'.

* guix/gexp.scm (<delayed-object>): New record type.
(delayed-object): New macro.
(delayed-object-compiler): New gexp compiler.
* tests/gexp.scm ("delayed-object"): New test.
* doc/guix.texi (G-Expressions): Document it.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index ce67ea9c827..a3b17578a8f 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -148,6 +148,7 @@ Copyright @copyright{} 2025 Edouard Klein@*
 Copyright @copyright{} 2025 Rodion Goritskov@*
 Copyright @copyright{} 2025 dan@*
 Copyright @copyright{} 2025 Noé Lopez@*
+Copyright @copyright{} 2026 David Elsing@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -12982,6 +12983,15 @@ 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
 
+@defmac delayed object exp
+This macro delays the evaluation of @var{exp} until the returned object
+is lowered to a derivation or store item.
+
+Its intended use case is to prevent the use of a non-delayed top-level
+variable of another module, e.g. when using a gexp in the @code{source}
+field of a @var{package}.
+@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