Bazel has a TON of options - over 1500 of them! [1] It has so many obscure options that even experts like myself are often surprised to learn about a new one.
Many of the options have the wrong default value for new repositories. This means new users re-experience some bug only to find that they just never "enabled the bugfix".
There's now an easy way for users to avoid learning about so many flags and get more sensible values by default: presets.
What is a preset?
A preset is just a named .bazelrc
file with a collection of flags set, and a bunch of comments explaining the behavior change and links to documentation or issues filed.
An example preset entry looks like
# Allow exclusive tests to run in the sandbox. Fixes a bug where Bazel doesn't enable sandboxing for
# tests with `tags=["exclusive"]`.
# Docs: https://bazel.build/reference/command-line-reference#flag--incompatible_exclusive_test_sandboxed
test --incompatible_exclusive_test_sandboxed
We group them into preset files. The flag above appears in correctness.bazelrc
.
Using presets
If you don't have a dependency on bazel-lib yet, add it. This module provides a ton of carefully curated starlark libraries, rules, and other utilities that are helpful across languages. Install instructions appear on each release: https://github.com/aspect-build/bazel-lib/releases
Next, copy the presets into your repository. The easiest way to do this is with our macro:
load("@aspect_bazel_lib//lib:bazelrc_presets.bzl", "write_aspect_bazelrc_presets")
write_aspect_bazelrc_presets(name = "update_aspect_bazelrc_presets")
This creates a test target checking that the copies are up-to-date, so as you upgrade bazel-lib, it will print a bazel run
command to update your copy. Since the presets can't be guaranteed to work with every Bazel setup, it's important for you to code review the changes. This is why the presets get copied to your source repo.
Finally, update the /.bazelrc
file in your repo to import the presets you use. Add an import
statement like
import %workspace%/.aspect/bazelrc/correctness.bazelrc
Complete documentation and the contents of the preset files are all on https://docs.aspect.build/guides/bazelrc.
Improving the presets
The presets live in an Apache 2 licensed open-source repo: https://github.com/aspect-build/bazel-lib/tree/main/.aspect/bazelrc where the community can suggest more improvements. Bazel is always adding flags, so we expect this to grow over time.
Why not fix the wrong defaults?
We have been working on this! The rules authors SIG has put up bug bounties asking for community help to flip some Bazel flags: https://github.com/bazel-contrib/SIG-rules-authors/issues?q=is%3Aissue+is%3Aopen+label%3Abounty-1000USD
However, so far only one volunteer has stepped up to work on flipping one of them.
[1] bazel% git checkout 6.0.0; find . -name '\*.java' -type f -exec fgrep "@Option(" {} ; | wc -l
-> 1537