scope and on_leave_scope attributes.
Overview
When you set a flag on the command line or modify it in a configuration transition, every transitive dependency inherits that flag value unless another transition changes it. Unrestricted flag propagation causes two build performance problems:- Out-of-project configuration forks (
ST-<hash>): When a project defines a flag intended only for its own targets (for example,//my_project/flags:enable_feature_x) and modifies it in a rule or attribute transition, that flag remains in the configuration when dependencies cross into shared libraries outside the project. Because the configuration hash includes all non-default Starlark options, Bazel re-analyzes and rebuilds shared dependencies in a separateST-<hash>output directory, reducing remote cache hit rates and increasing memory and CPU usage. - Unnecessary exec tool rebuilds: When a target-specific flag propagates
across an
exectransition to build tools (such as compilers, code generators, or linters), changing the flag forks theexecconfiguration and forces Bazel to rebuild those tools.
scope, Bazel automatically
resets or removes the flag so downstream targets share a single canonical
configuration.
Supported scopes at a glance
Declare a scoped flag
Predefined flag rules
You can setscope directly on Bazel’s built-in and Skylib build setting rules:
- Skylib build settings (
common_settings.bzl):bool_flag,string_flag,int_flag,string_list_flag,repeatable_string_flag, and their*_settingcounterparts includescope(defaulting to"target"). They do not exposeon_leave_scope. - Native
label_flagandlabel_setting: Support bothscopeandon_leave_scope(for"target"-scoped flags).
Custom build setting rules
If you write a custom Starlarkrule(build_setting = ...) instead of using a
predefined flag type, add "scope": attr.string(...) (and optionally
"on_leave_scope" with the same attribute type as build_setting) to your
rule’s attrs dictionary:
If your custom rule sets a rule-level default other than
"target" (such as
default = "universal" or default = "project"), pass scope explicitly on
each target in BUILD if your Bazel version does not yet propagate rule-level
scope defaults for command-line flags.Scope types in detail
Project scope
Settingscope = "project" restricts a flag’s non-baseline value to targets
belonging to the project that owns the flag.
Define the project boundary with PROJECT.scl
When a flag hasscope = "project", Bazel looks for a PROJECT.scl file in the
same package as the flag’s BUILD file (or the nearest parent package) and
reads the default project directories from the project definition:
Target dependencies
When a Starlark transition modifies ascope = "project" flag away from its
top-level baseline value, Bazel checks whether the target’s canonical label
starts with any path listed in the project’s default directories:
- In-scope target (for example,
//my_project/app:mainor//my_project/libs/foo:bar): The target keeps the flag’s transitioned value. - Out-of-scope target (for example,
//common/logging:loggeror an external repository target):- If
//my_project/flags:flavoris not explicitly set in the top-level baseline configuration, Bazel removes//my_project/flags:flavorfrom the target’s configuration, reverting it tobuild_setting_default. - If
//my_project/flags:flavoris explicitly set in the top-level baseline configuration (for example, on the command line or viaPROJECT.sclconfigs), Bazel resets//my_project/flags:flavorfrom the transitioned value back to its top-level baseline value. - If all transitioned flags on the target reset to the baseline
configuration, the out-of-scope target returns to the unforked baseline
configuration with no
ST-<hash>suffix.
- If
If no
PROJECT.scl exists or active_directories is empty, Bazel treats all
targets as out of scope and resets any transitioned value to the top-level
baseline value (even for targets in the flag’s own package).Exec transitions
Unlikescope = "target", a project-scoped flag does not automatically reset
on an exec transition. Instead, Bazel preserves its value across the exec
transition and evaluates the project boundary check against the exec tool
target’s own label:
- In-project
exectool (for example,//my_project/app:mainhas anexecdependency on a code generator//my_project/libs/codegen:geninside the project’s directories)://my_project/libs/codegen:genretains the custom value of//my_project/flags:flavor. - Out-of-project
exectool (for example,//my_project/app:mainhas anexecdependency on an external compiler or code generator outside the project’s directories): Bazel resets//my_project/flags:flavoron that tool to its baseline or default value, avoiding unnecessary host tool rebuilds.
Target scope and on_leave_scope
scope = "target" is the default scope for all flags defined with Skylib’s
common_settings.bzl (and for all Starlark flags when
--incompatible_exclude_starlark_flags_from_exec_config=true):
- The flag propagates across all target-configured dependencies
(
cfg = "target"). - When crossing an
exectransition (cfg = "exec"), Bazel excludes the flag from theexecconfiguration so that host tools seebuild_setting_default.
Customize the exec reset value with on_leave_scope
on_leave_scope applies only to scope = "target" flags (and is ignored by
"project" and other scopes). If an exec tool requires a fixed non-default
value when a customized target-scoped flag crosses an exec transition, set
on_leave_scope on a label_flag, label_setting, or custom build_setting
rule:
//my_project/flags:sanitization_mode to a non-default value (for
example, --//my_project/flags:sanitization_mode=strict):
- Target-configured rules read
"strict". - Exec-configured rules read
"minimal_host"(fromon_leave_scope).
on_leave_scope and scope = "exec:--<host_flag>":
- Use
on_leave_scopewhen you have a single flag andexectools should always receive a fixed constant defined inBUILD(not overridable on the command line). - Use
scope = "exec:--<host_flag>"(see Cross-flag exec mapping) when users or.bazelrcconfigs need to override target andexecvalues independently on the command line, or when using Skylib’scommon_settings.bzlrules (which do not exposeon_leave_scope).
Universal scope
A flag withscope = "universal" propagates its value everywhere in the build
graph, including across exec transitions and into external packages. Only an
explicit Starlark configuration transition that writes to the flag can change
its value.
Cross-flag exec mapping
Some workflows pair a target flag with a separate host/exec flag so you can
configure target and exec behavior independently on the command line (unlike
on_leave_scope, which hardcodes a single static literal in BUILD). Setting
scope = "exec:--<another_flag_label>" instructs Bazel to assign the
target-configuration value of --<another_flag_label> to this flag whenever
transitioning to an exec configuration.
--flag_alias for the host flag in .bazelrc (or on the command
line) so Bazel’s option parser resolves the candidate flag:
- Target-configured rules reading
//my_project/flags:launcherreceive"custom_target". - Exec-configured rules reading
//my_project/flags:launcherreceive"custom_host"(or"default_host_launcher"if--//my_project/flags:host_launcheris omitted), without creating anST-<hash>fork on theexecconfiguration when neither flag is customized.
Verify flag scopes
You can inspect how Bazel scopes flags across in-project targets, out-of-project targets, andexec targets using bazel cquery and bazel config:
-
Query the configured dependency graph of your target:
-
Inspect the configuration of an in-scope target versus an out-of-scope
target using each target’s configuration hash prefix:
(Omits
//my_project/flags:flavorif it was set via transition and dropped outsideactive_directories, or shows the baseline value.)