Skip to main content
Version: 2.0.x

run_binary

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.

Macros and Functions

run_binary

Runs a binary as a build action.

This rule does not require Bash (unlike native.genrule).

Example usage (generated):

load("@aspect_bazel_lib//lib:run_binary.bzl", "run_binary")

run_binary(
# The target name
name = "",
# The tool to run in the action
tool = None,
)

name

Required.

The target name

tool

Required.

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.

srcs

Optional. Default: []

Additional inputs of the action.

These labels are available for $(location) expansion in args and env.

args

Optional. Default: []

Command line arguments of the binary.

Subject to $(location) and make variable expansions via expand_location and expand_make_vars.

env

Optional. Default: {}

Environment variables of the action.

Subject to $(location) and make variable expansions via expand_location and expand_make_vars.

outs

Optional. Default: []

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

Optional. Default: []

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

Optional. Default: "RunBinary"

A one-word description of the action, for example, CppCompile or GoLink.

progress_message

Optional. Default: None

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.

execution_requirements

Optional. Default: None

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.

stamp

Optional. Default: 0

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 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 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.

kwargs

Optional.

Additional arguments