From 696d12ab8136bfc5bfb8dc6bd84648e43a859ce6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= <ludo@gnu.org>
Date: Thu, 19 Mar 2026 13:05:57 +0100
Subject: [PATCH] =?UTF-8?q?doc:=20Add=20=E2=80=98with-imported-modules?=
 =?UTF-8?q?=E2=80=99=20caveat.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/guix.texi (G-Expressions): Document caveat under
‘with-imported-modules’.

Change-Id: I9ee5452c7d776647961b282a0e6cefece165b00b
Signed-off-by: Ludovic Courtès <ludo@gnu.org>
---
 doc/guix.texi | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index f4279bfb79..fa05c37077 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12614,6 +12614,30 @@ path, and the last one is created from the given file-like object.
 This form has @emph{lexical} scope: it has an effect on the gexps
 directly defined in @var{body}@dots{}, but not on those defined, say, in
 procedures called from @var{body}@dots{}.
+
+@quotation Caveat
+It is important to distinguish between modules available in the build
+environment and modules in scope.  The @code{with-imported-modules} form
+pulls modules in the build environment of the gexp but it does
+@emph{not} import them.  To do so, you still need to use
+@code{use-modules} in the gexp:
+
+@lisp
+(with-imported-modules '((guix build utils))
+  #~(begin
+      (use-modules (guix build utils))
+      @dots{}))
+@end lisp
+
+@xref{Using Guile Modules,,, guile, GNU Guile Reference Manual}, for
+more information on @code{use-modules}.
+
+Likewise, to import a module provided by Guile---e.g., @code{(srfi
+srfi-1)}---add a @code{use-modules} form in your gexp.  Do @emph{not}
+add Guile-provided modules such as @code{(srfi srfi-1)} to a
+@code{with-imported-modules}; doing so would force a potentially
+incompatible version into your environment.
+@end quotation
 @end defmac
 
 @defmac with-extensions extensions body@dots{}