bazel rules: explain genrule PATH behavior
...which differs surprisingly between Bazel and Blaze.
For 2020 Doc Fixit.
Fixes https://github.com/bazelbuild/bazel/issues/1142
PiperOrigin-RevId: 313778720
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java
index cdda8a1..af16637 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/genrule/BazelGenRuleRule.java
@@ -132,10 +132,25 @@
<h4>Genrule Environment</h4>
<p>
- The genrule command is executed in a Bash shell, configured to fail when a command or a pipeline
- fails (<code>set -e -o pipefail</code>). Genrules should not access the network (except to create
- connections between processes running within the same genrule on the same machine), though this is
- not currently enforced.
+ The genrule command is executed by a Bash shell that is configured to fail when a command
+ or a pipeline fails, using <code>set -e -o pipefail</code>.
+</p>
+<p>
+ The build tool executes the Bash command in a sanitized process environment that
+ defines only core variables such as <code>PATH</code>, <code>PWD</code>,
+ <code>TMPDIR</code>, and a few others.
+
+ To ensure that builds are reproducible, most variables defined in the user's shell
+ environment are not passed though to the genrule's command. However, Bazel (but not
+ Blaze) passes through the value of the user's <code>PATH</code> environment variable.
+
+ Any change to the value of <code>PATH</code> will cause Bazel to re-execute the command
+ on the next build.
+ <!-- See https://github.com/bazelbuild/bazel/issues/1142 -->
+</p>
+<p>
+ A genrule command should not access the network except to connect processes that are
+ children of the command itself, though this is not currently enforced.
</p>
<p>
The build system automatically deletes any existing output files, but creates any necessary parent
