Bazel Cheatsheet

Bazel Commands

bazel build

# Single target.
$ bazel build //go/util:util

# All targets under a directory and any subdirectoriews.
$ bazel build //go/...

# All targets in the repository.
$ bazel build //...

Build output can be found in bazel-bin folder.

bazel test

# Test a single
$ bazel test //pkg/util:util_test
$ bazel test //pkg/...
$ bazel test //...
$ bazel test $(bazel query //path/to/folder/...)

# Pass test flags:
# Equivalent to "go test ./pkg/util -v".
$ bazel test //pkg/util:util_test --test_arg=-test.v

# Equivalent to "go test ./pkg/util -run=TestFoo"
$ bazel test //pkg/util:util_test --test_arg=-test.run=TestFoo

#
$ bazel test //pkg/util:util_test --test_output=all

Useful flags:

• --nocache_test_results: disable caching
• --runs_per_test=10: debugging flaky tests
• --test_timeout=20: set timeout

bazel run

Use command bazel run to run binary Bazel targets, such as go_binary, sh_binary, etc.

# Without command-line parameters.
$ bazel run //scripts/run_emulators:run_emulators

# With command-line parameters.
$ bazel run //scripts/run_emulators:run_emulators -- start

bazel query

If //path/to/foo does not directly depend on //bar:baz, use bazel query to find independent dependencies:

$ bazel query "allpaths(//path/to/foo, //bar:baz)" --notool_deps --output graph | dot -Tpng > deps.png

bazel clean

$ bazel clean --expunge

More about bazel

# show bazel version
$ bazel version

# show runtime info about the bazel server
$ bazel info

# show internal state of the Bazel server.
$ bazel dump <option>

# help
$ bazel help

Rules

• Native rules: rules that don't need a load() statement, e.g. cc_library or java_library
• Go rules: https://github.com/bazelbuild/rules_go
• To pull Maven artifacts, use rules_jvm_external
• Container (OCI) rules: https://github.com/bazel-contrib/rules_oci replaces rules_docker

Config written in Starlark, a dialect of Python https://github.com/bazelbuild/starlark/

External Dependencies

https://docs.bazel.build/versions/main/bzlmod.html

It will be more like other dependency management systems (maven, npm, cargo, etc)

• Bazel Modules
• Bazel Central Repository (BCR)

Trouble Shooting

Error: ... undeclared inclusion(s) in rule ...

This can happen after installing or upgrading developer tools (xcode). Try

$ bazel clean --expunge

Error: Source forest creation failed

ERROR: Source forest creation failed

Solution:

$ sudo rm -rf ~/.cache/bazel

bazel build generates files out of no where.

Maybe you just switched git branch? Clean up the cache.

$ bazel clean --expunge

Config

in ~/.bazelrc:

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

Usage:

$ bazel build --config=memcheck

Build time variables

# Specify a binary that Bazel runs before each build. The program can report information about the status of the workspace, such as the current source control revision.
$ bazel build --workspace_status_command=/path/to/binary

The program should print zero or more key/value pairs to standard output, one entry on each line.

Bazel then writes the key-value pairs into two files:

• bazel-out/stable-status.txt contains all keys and values where the key's name starts with STABLE_
• bazel-out/volatile-status.txt contains the rest of the keys and their values

If the contents of bazel-out/stable-status.txt change, Bazel invalidates the actions that depend on them. In other words, if a stable key's value changes, Bazel will rerun stamped actions.

Just the volatile status changing alone will not invalidate the action.

e.g. to enable stamping by default, add in .bazelrc:

build --stamp
build --workspace_status_command build/print-workspace-status.sh

where build/print-workspace-status.sh is something like:

cat <<EOF
STABLE_DOCKER_REGISTRY docker.io
STABLE_BUILD_SCM_REVISION ${GIT_VERSION-}
...
EOF

Then all {STABLE_DOCKER_REGISTRY} in bzl files will be expanded.

FAQ

Who's using Bazel?

• Android is moving to Bazel.
• Google internal projects use Blaze, external projects use Bazel.

What is Bazelisk?

Bazelisk is a wrapper for Bazel that downloads and runs the version of Bazel specified in //.bazelversion.

Similar to nvm for NodeJS.

https://github.com/bazelbuild/bazelisk

What is RBE?

Remote Build Execution (RBE) allows faster build and test execution times by distributing build and test actions across multiple machines.

What is Gazelle?

Use Gazelle to automatically generate BUILD.bazel files for most of our Go and TypeScript code.

https://github.com/bazelbuild/bazel-gazelle

What is Buildifier?

Buildifier is a linter and formatter for BUILD.bazel files and other Bazel files

$ bazel run //:buildifier