From 5e392c9141ffa4e864319fc5268ce96388085699 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Fri, 9 Apr 2021 09:50:50 +0200
Subject: Document hermetic build configuration support

---
 libbuild2/functions-builtin.cxx |  4 ++++
 libbuild2/functions-process.cxx | 10 ++++++++++
 libbuild2/parser.cxx            |  4 ++++
 3 files changed, 18 insertions(+)

(limited to 'libbuild2')

diff --git a/libbuild2/functions-builtin.cxx b/libbuild2/functions-builtin.cxx
index 4689ac2..2adff38 100644
--- a/libbuild2/functions-builtin.cxx
+++ b/libbuild2/functions-builtin.cxx
@@ -85,6 +85,10 @@ namespace build2
     // Return NULL if the environment variable is not set, untyped value
     // otherwise.
     //
+    // Note that if the build result can be affected by the variable being
+    // queried, then it should be reported with the config.environment
+    // directive.
+    //
     // Note that this function is not pure.
     //
     f.insert ("getenv", false) += [](names name)
diff --git a/libbuild2/functions-process.cxx b/libbuild2/functions-process.cxx
index 0870874..4be5149 100644
--- a/libbuild2/functions-process.cxx
+++ b/libbuild2/functions-process.cxx
@@ -414,6 +414,11 @@ namespace build2
     //
     // Run builtin or external program and return trimmed stdout.
     //
+    // Note that if the result of executing the program can be affected by
+    // environment variables and this result can in turn affect the build
+    // result, then such variables should be reported with the
+    // config.environment directive.
+    //
     // Note that this function is not pure.
     //
     f.insert (".run", false) += [](const scope* s, names args)
@@ -435,6 +440,11 @@ namespace build2
     // (as a whole) against <pat> and, if successful, returned, optionally
     // processed with <fmt>, as an element of a list.
     //
+    // Note that if the result of executing the program can be affected by
+    // environment variables and this result can in turn affect the build
+    // result, then such variables should be reported with the
+    // config.environment directive.
+    //
     // Note that this function is not pure.
     //
     {
diff --git a/libbuild2/parser.cxx b/libbuild2/parser.cxx
index 9022d5b..3b20a65 100644
--- a/libbuild2/parser.cxx
+++ b/libbuild2/parser.cxx
@@ -2139,6 +2139,10 @@ namespace build2
   {
     // run <name> [<arg>...]
     //
+    // Note that if the result of executing the program can be affected by
+    // environment variables and this result can in turn affect the build
+    // result, then such variables should be reported with the
+    // config.environment directive.
 
     // Parse the command line as names in the value mode to get variable
     // expansion, etc.
-- 
cgit v1.1