Document SpawnAction.Builder.useDefaultShellEnv()

RELNOTES: none
PiperOrigin-RevId: 163966473

1 files changed, 29 insertions, 2 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/analysis/actions/SpawnAction.java b/src/main/java/com/google/devtools/build/lib/analysis/actions/SpawnAction.java
index 5807881607..3b703af8d6 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/actions/SpawnAction.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/actions/SpawnAction.java
@@ -829,8 +829,35 @@ public class SpawnAction extends AbstractAction implements ExecutionInfoSpecifie
     }
 
     /**
-     * Sets the environment to the configurations default shell environment,
-     * see {@link BuildConfiguration#getLocalShellEnvironment}.
+     * Sets the environment to the configuration's default shell environment.
+     *
+     * <p><b>All actions should set this if possible and avoid using {@link #setEnvironment}.</b>
+     *
+     * <p>When this property is set, the action will use a minimal, standardized environment map.
+     *
+     * <p>The list of envvars available to the action (the keys in this map) comes from two places:
+     * from the configuration fragments ({@link BuildConfiguration.Fragment#setupActionEnvironment})
+     * and from the command line or rc-files via {@code --action_env} flags.
+     *
+     * <p>The values for these variables may come from one of three places: from the configuration
+     * fragment, or from the {@code --action_env} flag (when the flag specifies a name-value pair,
+     * e.g. {@code --action_env=FOO=bar}), or from the client environment (when the flag only
+     * specifies a name, e.g. {@code --action_env=HOME}).
+     *
+     * <p>The client environment is specified by the {@code --client_env} flags. The Bazel client
+     * passes these flags to the Bazel server upon each build (e.g.
+     * {@code --client_env=HOME=/home/johndoe}), so the server can keep track of environmental
+     * changes between builds, and always use the up-to-date environment (as opposed to calling
+     * {@code System.getenv}, which it should never do, though as of 2017-08-02 it still does in a
+     * few places).
+     *
+     * <p>The {@code --action_env} has priority over configuration-fragment-dictated envvar values,
+     * i.e. if the configuration fragment tries to add FOO=bar to the environment, and there's also
+     * {@link --action_env=FOO=baz} or {@link --action_env=FOO}, then FOO will be available to the
+     * action and its value will be "baz", or whatever the corresponding {@code --client_env} flag
+     * specified, respectively.
+     *
+     * @see {@link BuildConfiguration#getLocalShellEnvironment}
      */
     public Builder useDefaultShellEnvironment() {
       this.environment = null;