From 35c1c44bc5f75a327f5d879373a9683af2072a1a Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 21 Apr 2021 09:09:18 +0200
Subject: Document use of depdb-env for manually tracking changes to
 environment

---
 doc/manual.cli | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index af9699e..3ee3016 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -5741,6 +5741,24 @@ if ($foo != [null])
   cxx.poptions += \"-DUSE_FOO=$foo\"
 \
 
+Additionally, if invoking a program in an ad hoc recipe that either does not
+provide the metadata or does not report the environment as part of it, then we
+additionally should track the changes to the relevant environment variables
+manually using the \c{depdb env} builtin. For example:
+
+\
+import! foo = foo%exe{foo} # Uses FOO and BAR environment variables.
+
+config.environment FOO BAR
+
+file{output}: file{input} $foo
+{{
+  diag foo $>
+  depdb env FOO BAR
+  $foo $path($<[0]) >$path($>)
+}}
+\
+
 \N|Normally, we would want to report variables that affect the build result
 rather than build byproducts (for example, diagnostics). This is, for example,
 the reason why locale-related environment variables are not saved by default.
-- 
cgit v1.1