blob: da4dafd2a51e3289aea29de81e2d3ae8772d7e30 [file]
---
title: 'Starlark flag scoping'
---
This page explains how to restrict where [user-defined Starlark build
settings](/extending/config#user-defined-build-settings) propagate in the
dependency graph using the `scope` and `on_leave_scope` attributes.
## Overview {#overview}
When you set a flag on the command line or modify it in a [configuration
transition](/extending/config#user-defined-transitions), 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 {#supported-scopes}
| Scope value | Target dependencies (in project) | Target dependencies (outside project) | Across `exec` transitions | Typical use case |
| :--- | :--- | :--- | :--- | :--- |
| **`"target"`** *(default in Skylib)* | Keeps value | Keeps value | Resets to `build_setting_default` (or to the static `on_leave_scope` value, if set) | Standard flags that affect target outputs across the build graph without forking `exec` tools. |
| **`"project"`** | Keeps value | Resets transitioned value to baseline configuration value (or removes it if unset in baseline) | Preserves value across the `exec` transition, then enforces project boundaries on the `exec` target's package | Project-specific flags that must not fork shared libraries or external `exec` tools. |
| **`"universal"`** | Keeps value | Keeps value | Keeps value | Flags that must affect both target builds and all `exec` tools (for example, repository-wide `--incompatible_*` or toolchain-wide toggles). |
| **`"exec:--//pkg:host_flag"`** | Keeps value | Keeps value | Inherits the target-configuration value of `--//pkg:host_flag` | Flags paired with a separate host-side flag so you can override target and `exec` values independently on the command line. |
## Declare a scoped flag {#declare-scoped-flag}
### Predefined flag rules {#predefined-flag-rules}
You can set `scope` directly on Bazel's built-in and Skylib build setting rules:
* **Skylib build settings** ([`common_settings.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/main/rules/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`](/extending/config#label-typed-build-settings)**:
Support both `scope` and `on_leave_scope` (for `"target"`-scoped flags).
```python
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "bool_flag", "string_flag")
string_flag(
name = "release_channel",
build_setting_default = "dev",
scope = "project",
values = ["dev", "alpha", "prod"],
visibility = ["//visibility:public"],
)
bool_flag(
name = "instrument_exec_tools",
build_setting_default = False,
scope = "universal",
)
label_flag(
name = "custom_malloc",
build_setting_default = "//base:default_malloc",
on_leave_scope = "//base:host_malloc",
scope = "target",
)
```
### Custom build setting rules {#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:
```python
# my_project/flags/build_defs.bzl
BuildSettingInfo = provider(fields = ["value"])
def _custom_flag_impl(ctx):
return BuildSettingInfo(value = ctx.build_setting_value)
custom_string_flag = rule(
implementation = _custom_flag_impl,
build_setting = config.string(flag = True),
attrs = {
"scope": attr.string(
default = "target",
doc = "Controls where this flag propagates ('target', 'project', 'universal', or 'exec:--<flag>').",
),
"on_leave_scope": attr.string(
doc = "Optional value to set when a 'target'-scoped flag crosses an exec transition.",
),
},
)
```
<Note>
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.
</Note>
## Scope types in detail {#scope-types}
### Project scope {#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 {#define-project-boundary}
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:
```python
# my_project/flags/PROJECT.scl
project = {
"active_directories": {
"default": [
"//my_project/app",
"//my_project/flags",
"//my_project/libs",
],
},
}
```
```python
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
string_flag(
name = "flavor",
build_setting_default = "default",
scope = "project",
visibility = ["//visibility:public"],
)
```
#### Target dependencies {#project-scope-target-deps}
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.
<Note>
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).
</Note>
#### Exec transitions {#project-scope-exec}
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 {#target-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}
`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:
```python
# my_project/flags/BUILD
load("//my_project/flags:build_defs.bzl", "custom_string_flag")
custom_string_flag(
name = "sanitization_mode",
build_setting_default = "full",
on_leave_scope = "minimal_host",
scope = "target",
)
```
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](#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 {#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.
```python
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")
bool_flag(
name = "incompatible_strict_validation",
build_setting_default = False,
scope = "universal",
)
```
<Warning>
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.
</Warning>
### Cross-flag exec mapping {#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.
```python
# my_project/flags/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
string_flag(
name = "launcher",
build_setting_default = "default_target_launcher",
scope = "exec:--//my_project/flags:host_launcher",
)
string_flag(
name = "host_launcher",
build_setting_default = "default_host_launcher",
scope = "target",
)
```
Register a `--flag_alias` for the host flag in `.bazelrc` (or on the command
line) so Bazel's option parser resolves the candidate flag:
```bash
# .bazelrc
build --flag_alias=host_launcher=//my_project/flags:host_launcher
```
Run a build passing both flags:
```bash
bazel build //my_project:app \
--//my_project/flags:launcher=custom_target \
--//my_project/flags:host_launcher=custom_host
```
* 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 {#verify-flag-scopes}
You can inspect how Bazel scopes flags across in-project targets, out-of-project
targets, and `exec` targets using [`bazel cquery`](/query/cquery) and `bazel
config`:
1. Query the configured dependency graph of your target:
```bash
bazel cquery 'deps(//my_project/app:main)'
```
```text
//my_project/app:main (a1b2c3d4...)
//my_project/libs:helper (a1b2c3d4...)
//common/logging:logger (e5f6g7h8...)
```
2. Inspect the configuration of an in-scope target versus an out-of-scope
target using each target's configuration hash prefix:
```bash
bazel config a1b2c3d4
```
```text
BuildConfigurationValue a1b2c3d4...
...
FragmentOptions user-defined {
//my_project/flags:flavor: custom
}
```
```bash
bazel config e5f6g7h8
```
*(Omits `//my_project/flags:flavor` if it was set via transition and
dropped outside `active_directories`, or shows the baseline value.)*
## Further reading {#further-reading}
* [Configurations](/extending/config)
* [Configurable build attributes](/docs/configurable-attributes)
* [Configured query (cquery)](/query/cquery)