Skip to main content
This page explains how to restrict where user-defined Starlark build settings propagate in the dependency graph using the 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:
  1. 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 separate ST-<hash> output directory, reducing remote cache hit rates and increasing memory and CPU usage.
  2. Unnecessary exec tool rebuilds: When a target-specific flag propagates across an exec transition to build tools (such as compilers, code generators, or linters), changing the flag forks the exec configuration and forces Bazel to rebuild those tools.
When a dependency moves outside a flag’s declared 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 set scope 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 *_setting counterparts include scope (defaulting to "target"). They do not expose on_leave_scope.
  • Native label_flag and label_setting: Support both scope and on_leave_scope (for "target"-scoped flags).

Custom build setting rules

If you write a custom Starlark rule(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

Setting scope = "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 has scope = "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 a scope = "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:main or //my_project/libs/foo:bar): The target keeps the flag’s transitioned value.
  • Out-of-scope target (for example, //common/logging:logger or an external repository target):
    • If //my_project/flags:flavor is not explicitly set in the top-level baseline configuration, Bazel removes //my_project/flags:flavor from the target’s configuration, reverting it to build_setting_default.
    • If //my_project/flags:flavor is explicitly set in the top-level baseline configuration (for example, on the command line or via PROJECT.scl configs), Bazel resets //my_project/flags:flavor from 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 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

Unlike scope = "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 exec tool (for example, //my_project/app:main has an exec dependency on a code generator //my_project/libs/codegen:gen inside the project’s directories): //my_project/libs/codegen:gen retains the custom value of //my_project/flags:flavor.
  • Out-of-project exec tool (for example, //my_project/app:main has an exec dependency on an external compiler or code generator outside the project’s directories): Bazel resets //my_project/flags:flavor on 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 exec transition (cfg = "exec"), Bazel excludes the flag from the exec configuration so that host tools see build_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:
When you set //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" (from on_leave_scope).
Choose between on_leave_scope and scope = "exec:--<host_flag>":
  • Use on_leave_scope when you have a single flag and exec tools should always receive a fixed constant defined in BUILD (not overridable on the command line).
  • Use scope = "exec:--<host_flag>" (see Cross-flag exec mapping) when users or .bazelrc configs need to override target and exec values independently on the command line, or when using Skylib’s common_settings.bzl rules (which do not expose on_leave_scope).

Universal scope

A flag with scope = "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.
Use scope = "universal" sparingly. Every change to a universal flag invalidates the exec configuration and forces Bazel to rebuild all host/exec tools (such as compilers and protocol buffer plugins) in that subgraph.

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.
Register a --flag_alias for the host flag in .bazelrc (or on the command line) so Bazel’s option parser resolves the candidate flag:
Run a build passing both flags:
  • Target-configured rules reading //my_project/flags:launcher receive "custom_target".
  • Exec-configured rules reading //my_project/flags:launcher receive "custom_host" (or "default_host_launcher" if --//my_project/flags:host_launcher is omitted), without creating an ST-<hash> fork on the exec configuration when neither flag is customized.

Verify flag scopes

You can inspect how Bazel scopes flags across in-project targets, out-of-project targets, and exec targets using bazel cquery and bazel config:
  1. Query the configured dependency graph of your target:
  2. 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:flavor if it was set via transition and dropped outside active_directories, or shows the baseline value.)

Further reading