3.2.4 Command Line Flags

Once the .bazelrc layering from 3.2.1 .bazelrc Hierarchy decides where flags live, the next question is which flags matter most. Bazel ships hundreds of options, and even experienced users routinely discover ones they have not heard of¹. This article focuses on the flags a maintainer reaches for first — the ones that control compilation behavior, pass options to compilers, set user-defined variables, and affect cache keys — plus a workflow for exposing rc contributions and comparing explicit option lists without shorthand.

Expose rc contributions, then normalize explicit flags

Different developers, different machines, different .bazelrc layers. When a build behaves differently on CI than on a laptop, first run the original invocation with --announce_rc to see which rc files and named configs contributed options. Then use bazel canonicalize-flags on the explicit option lists you want to compare. It returns a normalized list with the same effect²:

$ bazel canonicalize-flags -- -c opt -k --define=ENV=prod
--compilation_mode=opt
--keep_going=1
--define=ENV=prod

Short flags expand to their long form (-c becomes --compilation_mode), boolean flags become explicit (-k becomes --keep_going=1), and equivalent input lists produce the same canonical output. That makes two explicitly captured command lines easy to compare without shorthand obscuring a difference.

There are two things canonicalize-flags does not do. It does not expand --config — a --config=ci flag passes through unchanged, because config expansion depends on which .bazelrc files are loaded². And it currently supports only build and test via --for_command. Options the chosen command does not understand cause an error². The canonicalize-flags snippet reproduces all three behaviors — short/boolean expansion, the unexpanded --config=ci, and the rejected unknown option — against a tiny workspace whose .bazelrc defines build:ci so the named config has somewhere real to point.

The practical workflow is two-part. Use --announce_rc from 3.2.1 .bazelrc Hierarchy to see which rc files and named configs contributed options, then pass the resulting explicit option lists to canonicalize-flags and diff their canonical forms. canonicalize-flags alone does not inspect the invocation's loaded rc files, defaults, or expanded --config contents. The larger maintainer-workspace example includes a canonicalize-flags --for_command=build command next to its real .bazelrc policy so article authors can verify the same behavior outside the tiny snippet.

--compilation_mode (-c)

The most visible flag. It controls optimization level, debug information, and assertion behavior across all C/C++ compilation actions²:

Bazel uses a different output directory for each compilation mode, so switching between -c fastbuild and -c opt does not force a full rebuild — only the targets that actually differ need recompilation². That output-directory separation is the same mechanism described in 2.4 Caching & Incrementality: each mode produces a distinct set of action keys, and those keys coexist in the cache.

--copt

Passes a flag directly to the C/C++ compiler. Repeatable — multiple --copt values accumulate on the compiler command line²:

bazel build --copt="-g0" --copt="-fpic" //foo

Changing --copt forces recompilation of all affected object files². Rule-level copts attributes are appended after --copt values, so a target can override or supplement the project-wide setting².

Related flags split the concern by language and link phase²:

The separation matters for correctness: a C++-specific flag in --copt will cause warnings or errors when compiling C sources. Placing it in --cxxopt avoids the problem.

--define and its replacement

--define sets user-defined key-value variables that config_setting rules can match in select() from 3.3.1 Configurable Attributes (select())³:

bazel build --define=ENV=prod //app:server

The mechanism works, but --define values are unstructured strings with no type checking and no tooling support³. The Starlark build settings system replaces --define with typed, label-addressed flags⁴:

bazel build --//config:environment=prod //app:server

A Starlark build setting is a regular rule with build_setting = config.string(flag = True) in its definition⁴. It appears in select() via config_setting's flag_values attribute⁴. The benefit is type safety: a build setting can validate its values, and its label makes the ownership and location explicit.

For shorter command lines, --flag_alias binds a long Starlark setting label to a short name^2,4:

# .bazelrc
build --flag_alias=env=//config:environment

bazel build --env=prod //app:server

New projects should use Starlark build settings from the start. Existing --define usage still works but should be migrated when practical⁴. Continue to 4.7 Build Settings & Transitions for the authoring side: defining rules, using ctx.build_setting_value, and writing transitions.

Cache impact of flags

Every flag that affects compilation becomes part of the action key. Change the flag, and Bazel treats the action as new — cache miss^2,5. This is correct behavior: a binary compiled with -c opt should not share cache entries with one compiled with -c dbg. But it means that ad hoc flag differences between developers or between CI and local builds silently destroy cache hit rates.

Option effect tags give a useful first-pass signal. Tags such as affects_outputs, changes_inputs, loading_and_analysis, loses_incremental_state, and terminal_output tell you whether a flag can change produced artifacts, alter inputs, invalidate warm server state, or merely change what the terminal prints². Treat those tags as triage: they help decide which flags deserve careful .bazelrc policy, but the actual blast radius still depends on the command, rules, platforms, and targets in the invocation.

The practical countermeasure is grouping related flags into named configs in .bazelrc:

build:release --compilation_mode=opt
build:release --copt=-flto
build:release --define=ENV=prod

Everyone running --config=release gets the same action keys. A developer who adds --copt=-fsanitize=address on the command line will get cache misses only for the actions that flag actually affects — and those misses are intentional.

When flag divergence between CI and local builds becomes a suspected cause of poor cache sharing, first expose rc contributions with --announce_rc. Then canonicalize and diff the explicit option lists. Project specifications and flag sets — a Bazel 9+ feature covered in 3.2.7 Project Specifications & Flag Sets — aim to formalize this further by letting experts define named flag sets so that regular users never manipulate individual flags⁶.

bazel build --per_file_copt='third_party/.*\.cc@-O0' //...