The ‘build' and ‘run’ commands

build

Use build to populate the bazel-out tree. This is most commonly used to answer the question, “Does the code compile”. For example,

bazel build //path/to/package:*

There are many flags to control building. Here are a few useful ones:

• --nobuild means to perform a “dry-run” of the build. Use this to reduce noise when Bazel errors in a way that indicates it cannot load or analyze the BUILD files or rulesets.
• --config=<name> lets you select a predefined configuration from the .bazelrc file
• --jobs=<n> can be used to reduce Bazel concurrency so it uses fewer resources on your computer.
• --keep_going / -k will continue building even after some targets fail.
• -sandbox_debug skips the automatic deletion of temporary “sandbox” folders Bazel creates, so you can inspect them manually to debug failures.
• --build_tag_filters lets you skip building certain targets that would otherwise match the target pattern. Note that bazel query <expression> | xargs bazel build is a more powerful way to customize which targets to build.
• --action_env=<key[=value]> allows you to propagate environment variables to be seen by actions, however, the rule implementation must opt-in to this, see use_default_shell_env

run

Running programs in Bazel is just a syntax sugar.

It really means "build this program, then spawn the resulting executable". Bazel's naming convention is that any *_binary target should be executable, so you can bazel run it. Some other targets may be executable as well, so refer to the documentation.

If you want to do some next steps with the resulting artifact, like load it into a container daemon or push it to a cloud provider, the best approach is to let Bazel run whatever that next step is.

bazel run //path/to:target.push

The run command is syntax sugar for “build this one target that produces an executable output, then immediately spawn that executable”. The executable could be a small script that you write.

Many rulesets provide convenient runnable targets, such as oci_push, for uploading to a container registry.

Unlike build or test, the run command allows non-hermetic side effects. This can be useful, for example, when writing build outputs back to the source tree.

Programs under bazel run will see extra environment variables:

• BUILD_WORKING_DIRECTORY is the absolute path to the working directory where bazel run was invoked
• BUILD_WORKSPACE_DIRECTORY is the absolute path to the Bazel repository root.

To run arbitrary tools, read the https://blog.aspect.build/run-tools-installed-by-bazel post.

Locating Outputs

Sometimes, your workflow requires you to build the artifact and then locate the output file. The terminal output of bazel build will print paths to the resulting artifacts beneath the bazel-out tree.

There are a couple of other ways to find outputs in bazel-out which are better for scripting:

• bazel cquery --output=files //path/to:target
• bazel outputs //path/to:target ( Aspect CLI only)

Next Lesson