From 65b02398b9bfd38d117ff21d0c45986f8dfb8ae8 Mon Sep 17 00:00:00 2001 From: Greg Magolan Date: Tue, 5 Mar 2024 10:22:43 -0800 Subject: [PATCH] docs: add use_default_shell_env to docstring of run_binary --- docs/run_binary.md | 3 ++- lib/private/run_binary.bzl | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/run_binary.md b/docs/run_binary.md index 97e258517..185f5a46f 100644 --- a/docs/run_binary.md +++ b/docs/run_binary.md @@ -11,7 +11,7 @@ This fork of bazel-skylib's run_binary adds directory output support and better 
 run_binary(name, tool, srcs, args, env, outs, out_dirs, mnemonic, progress_message,
-           execution_requirements, stamp, kwargs)
+           execution_requirements, use_default_shell_env, stamp, kwargs)
Runs a binary as a build action. @@ -34,6 +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 | | 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 1538897ef..61fd4ab64 100644 --- a/lib/private/run_binary.bzl +++ b/lib/private/run_binary.bzl @@ -115,6 +115,7 @@ def run_binary( mnemonic = "RunBinary", progress_message = None, execution_requirements = None, + use_default_shell_env = False, stamp = 0, **kwargs): """Runs a binary as a build action. @@ -180,6 +181,10 @@ def run_binary( See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. + use_default_shell_env: Passed to the underlying ctx.actions.run. + + See 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: - `stamp = 0` (default): Never include build status files as inputs to the tool. @@ -215,6 +220,7 @@ def run_binary( mnemonic = mnemonic, progress_message = progress_message, execution_requirements = execution_requirements, + use_default_shell_env = use_default_shell_env, stamp = stamp, **kwargs )