Flags

Bazel has an extremely large number of command-line flags. Even experts are routinely surprised to learn of a new one they hadn't heard of. And many flags have the wrong default value.

Flags are passed to Bazel commands like any command-line program, with a double-hyphen such as bazel build --jobs=10 my_target.

Short form and negation

Some flags have a short, single-letter form used with a single hyphen. For example, bazel build -c opt is shorthand for bazel build --compilation_mode opt. Boolean flags have a negated form prefixed with no, such as --noexperimental_merged_skyframe_analysis_execution.

Storing preferences: rc files

Typically, flags are set in a Unix-style RC file so that you don't have to remember them. There are a few locations where these may appear, and later items in the list below take precedence over earlier ones:

1. Global “system” RC file, in /etc/bazel.bazelrc .
2. Shared with other developers in a .bazelrc file in the repository root.
3. Personal preferences are stored in the user’s home directory, $HOME/.bazelrc. These preferences apply to ALL Bazel repositories.
4. By convention, Bazel recommends personal preferences for a single repository in a user.bazelrc file in that repository, see https://bazel.build/configure/best-practices#bazelrc-file.

Each line begins with a command. common should typically be used. It is a placeholder for “any commands that support this flag”. Flags may be further grouped with tags which are selected by the special --config flag. Here’s an example:

# applies to 'bazel build' as well as 'bazel test' and 'bazel run'
build --some_build_flag=1

# applies only to 'bazel test'
test --some_test_flag=on

# applies to any command (use Bazel 6.4 or greater)
common --other_flag=yes

# Create named configs
# applies only when --config=ci is set
common:ci --this_flag=only-on-CI

In a real project, the flags get hard to organize, so we recommend that the .bazelrc file in your project just import from several rc files. Aspect provides “presets” which are collections of flags you want to enable. The newly created project has several of these at the start of the file:

# Import Aspect bazelrc presets
import %workspace%/.aspect/bazelrc/bazel8.bazelrc
import %workspace%/.aspect/bazelrc/convenience.bazelrc
import %workspace%/.aspect/bazelrc/correctness.bazelrc
import %workspace%/.aspect/bazelrc/debug.bazelrc
import %workspace%/.aspect/bazelrc/javascript.bazelrc   # If you selected JavaScript
import %workspace%/.aspect/bazelrc/performance.bazelrc
...
try-import %workspace%/.aspect/bazelrc/user.bazelrc

Next Lesson