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.

https://registry.build/flag/bazel/ is a nice interface for browsing flags, or sending a permalink to your coworker pointing them to a flag.

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

Sometimes you might need to differentiate between flags passed to Bazel, and those passed to a program Bazel is running. Or, you might want to subtract a target from the pattern. Use a bare -- to delimit them, for example bazel run --stamp //my:target -- --some_argument or bazel build -- //app:all -//app:not-this-one

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. bazelrc-preset.bzl makes this very convenient!

The newly created project has several of these at the start of the file:

import %workspace%/tools/preset.bazelrc

# ... Project Specific flags override presets

# ... finally the user can override anything above
try-import %workspace%/user.bazelrc

Next Lesson