docs: add use_default_shell_env to docstring of run_binary (#778)
diff --git a/docs/run_binary.md b/docs/run_binary.md index 97e2585..185f5a4 100644 --- a/docs/run_binary.md +++ b/docs/run_binary.md
@@ -11,7 +11,7 @@ <pre> run_binary(<a href="#run_binary-name">name</a>, <a href="#run_binary-tool">tool</a>, <a href="#run_binary-srcs">srcs</a>, <a href="#run_binary-args">args</a>, <a href="#run_binary-env">env</a>, <a href="#run_binary-outs">outs</a>, <a href="#run_binary-out_dirs">out_dirs</a>, <a href="#run_binary-mnemonic">mnemonic</a>, <a href="#run_binary-progress_message">progress_message</a>, - <a href="#run_binary-execution_requirements">execution_requirements</a>, <a href="#run_binary-stamp">stamp</a>, <a href="#run_binary-kwargs">kwargs</a>) + <a href="#run_binary-execution_requirements">execution_requirements</a>, <a href="#run_binary-use_default_shell_env">use_default_shell_env</a>, <a href="#run_binary-stamp">stamp</a>, <a href="#run_binary-kwargs">kwargs</a>) </pre> Runs a binary as a build action. @@ -34,6 +34,7 @@ | <a id="run_binary-mnemonic"></a>mnemonic | A one-word description of the action, for example, CppCompile or GoLink. | <code>"RunBinary"</code> | | <a id="run_binary-progress_message"></a>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. | <code>None</code> | | <a id="run_binary-execution_requirements"></a>execution_requirements | Information for scheduling the action.<br><br>For example,<br><br><pre><code> execution_requirements = { "no-cache": "1", }, </code></pre><br><br>See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys. | <code>None</code> | +| <a id="run_binary-use_default_shell_env"></a>use_default_shell_env | Passed to the underlying ctx.actions.run.<br><br>See https://bazel.build/rules/lib/builtins/actions#run for more details. | <code>False</code> | | <a id="run_binary-stamp"></a>stamp | Whether to include build status files as inputs to the tool. Possible values:<br><br>- <code>stamp = 0</code> (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 <code>--stamp</code> builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typed <code>stamp</code> attribute.) - <code>stamp = 1</code>: 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. - <code>stamp = -1</code>: 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.<br><br>When stamping is enabled, an additional two environment variables will be set for the action: - <code>BAZEL_STABLE_STATUS_FILE</code> - <code>BAZEL_VOLATILE_STATUS_FILE</code><br><br>These files can be read and parsed by the action, for example to pass some values to a linker. | <code>0</code> | | <a id="run_binary-kwargs"></a>kwargs | Additional arguments | none |
diff --git a/lib/private/run_binary.bzl b/lib/private/run_binary.bzl index 1538897..61fd4ab 100644 --- a/lib/private/run_binary.bzl +++ b/lib/private/run_binary.bzl
@@ -115,6 +115,7 @@ 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 @@ 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 @@ mnemonic = mnemonic, progress_message = progress_message, execution_requirements = execution_requirements, + use_default_shell_env = use_default_shell_env, stamp = stamp, **kwargs )