From 902e3b5535ca315aea2a8728a5e01d448219dbb3 Mon Sep 17 00:00:00 2001 From: Greg Magolan Date: Tue, 5 Mar 2024 10:30:14 -0800 Subject: [PATCH] docs: add warning about using use_default_shell_env --- docs/run_binary.md | 2 +- lib/private/run_binary.bzl | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/run_binary.md b/docs/run_binary.md index 185f5a46f..aa29ef9f9 100644 --- a/docs/run_binary.md +++ b/docs/run_binary.md @@ -34,7 +34,7 @@ This rule does not require Bash (unlike `native.genrule`). | mnemonic | A one-word description of the action, for example, CppCompile or GoLink. | "RunBinary" | | progress_message | Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label}, %{input}, or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient. | None | | execution_requirements | Information for scheduling the action.

For example,

 execution_requirements = {     "no-cache": "1", },


See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. | None | -| use_default_shell_env | Passed to the underlying ctx.actions.run.

See https://bazel.build/rules/lib/builtins/actions#run for more details. | False | +| use_default_shell_env | Passed to the underlying ctx.actions.run.

May introduce non-determinism when True; use with care! See e.g. https://github.com/bazelbuild/bazel/issues/4912

Refer to https://bazel.build/rules/lib/builtins/actions#run for more details. | False | | stamp | Whether to include build status files as inputs to the tool. Possible values:

- stamp = 0 (default): Never include build status files as inputs to the tool. This gives good build result caching. Most tools don't use the status files, so including them in --stamp builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typed stamp attribute.) - stamp = 1: Always include build status files as inputs to the tool, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - stamp = -1: Inclusion of build status files as inputs is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag. Stamped targets are not rebuilt unless their dependencies change.

When stamping is enabled, an additional two environment variables will be set for the action: - BAZEL_STABLE_STATUS_FILE - BAZEL_VOLATILE_STATUS_FILE

These files can be read and parsed by the action, for example to pass some values to a linker. | 0 | | kwargs | Additional arguments | none | diff --git a/lib/private/run_binary.bzl b/lib/private/run_binary.bzl index 61fd4ab64..b9f498948 100644 --- a/lib/private/run_binary.bzl +++ b/lib/private/run_binary.bzl @@ -183,7 +183,10 @@ def run_binary( use_default_shell_env: Passed to the underlying ctx.actions.run. - See https://bazel.build/rules/lib/builtins/actions#run for more details. + May introduce non-determinism when True; use with care! + See e.g. https://github.com/bazelbuild/bazel/issues/4912 + + Refer to https://bazel.build/rules/lib/builtins/actions#run for more details. stamp: Whether to include build status files as inputs to the tool. Possible values: