Runs a binary as a build action. This rule does not require Bash (unlike native.genrule()).
This fork of bazel-skylib's run_binary adds directory output support and better makevar expansions.
## run_binary
run_binary(name, tool, srcs, args, env, outs, out_dirs, mnemonic, progress_message,
execution_requirements, use_default_shell_env, stamp, kwargs)
Runs a binary as a build action.
This rule does not require Bash (unlike `native.genrule`).
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| name | The target name | none |
| tool | The tool to run in the action.
Must be the label of a *_binary rule of a rule that generates an executable file, or of a file that can be executed as a subprocess (e.g. an .exe or .bat file on Windows or a binary with executable permission on Linux). This label is available for `$(location)` expansion in `args` and `env`. | none |
| srcs | Additional inputs of the action.
These labels are available for `$(location)` expansion in `args` and `env`. | `[]` |
| args | Command line arguments of the binary.
Subject to `$(location)` and make variable expansions via [expand_location](./expand_make_vars#expand_locations) and [expand_make_vars](./expand_make_vars). | `[]` |
| env | Environment variables of the action.
Subject to `$(location)` and make variable expansions via [expand_location](./expand_make_vars#expand_locations) and [expand_make_vars](./expand_make_vars). | `{}` |
| outs | Output files generated by the action.
These labels are available for `$(location)` expansion in `args` and `env`.
Output files cannot be nested within output directories in out_dirs. | `[]` |
| out_dirs | Output directories generated by the action.
These labels are _not_ available for `$(location)` expansion in `args` and `env` since they are not pre-declared labels created via `attr.output_list()`. Output directories are declared instead by `ctx.actions.declare_directory`.
Output directories cannot be nested within other output directories in out_dirs. | `[]` |
| 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.
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 |