4.7.5 Platform-based Flags

A surprising number of "real" Starlark transitions do almost nothing interesting. They flip --platforms to a target device, set one or two label-typed build settings that travel with that device, and stop. Once the conspect already covers 4.7.1 Build Settings for Rule Authors and 4.7.2 Starlark Transitions, the natural follow-up question is: if the only thing the transition does is bundle some flags with a platform, can the platform itself just carry the flags?¹ Platform-based flags are Bazel's answer — a flags = [...] attribute on the platform() rule that applies the listed flag values whenever Bazel uses that platform as a target or execution platform.²

The flags Attribute on platform()

A platform rule normally collects constraint_value labels that describe a machine. With platform-based flags, the same target also lists command-line flag values that come along whenever this platform is selected:³

platform(
    name = "custom",
    constraint_values = [...],
    flags = [
        "--custom_malloc=//label",
        "--other_flag",
        "--//example/starlark:flag=23",
    ],
)

The strings inside flags are parsed exactly the way they would be on the command line or in a .bazelrc line, so the same syntax covers native flags (--custom_malloc=...), repeatable native flags, and Starlark build settings (--//pkg:flag=value). Relative labels are not supported. Everything addressed by the flag must be a fully qualified label.²

The attribute is intentionally restricted in two ways. First, it is not configurable — you cannot wrap it in a select(). The list of flags is a static property of the platform target.² Second, you cannot put --platforms itself in the list, because that would set up a circular evaluation where selecting a platform changes which platform is selected.² The same exclusion applies, in spirit, to other platform-like flags.

When Bazel Selects the Platform

The flags do not fire merely because a target depends on a platform definition. They fire when Bazel uses the platform — either as the target platform via a top-level --platforms=//:custom on the command line or .bazelrc, via a transition deeper in the graph that flips --platforms to the platform's label, or as an execution platform selected for actions.^3,2 Bazel applies the platform's flags with the highest precedence: they overwrite earlier values from the command line, .bazelrc, or transitions, so any rule that reads those settings sees the platform-bound values automatically.²

There are two important interaction rules around this:

• Platform flags win over earlier settings. Treat the platform as the owner of the bundled values. If a user, rc file, or parent transition set the same flag differently, the selected platform's value wins.²
• Platform-based flags suppress platform mappings. If the selected platform has a non-empty flags attribute, Bazel skips the legacy platform-mappings file (the bridge introduced for migration described in 3.3.5 --platforms Flag). This avoids the confusion of two mechanisms quietly competing over the same flag values.²

The intent is the same as platform mappings — bundle related flags with a platform — but with the bundling expressed on the platform target itself rather than in an external mapping file.¹

Inheritance: Platforms That Extend Platforms

Platforms can declare parents = [...], and platform-based flags follow inheritance. A child platform can re-declare a flag to override its parent's value, or add new flags that the parent does not set:⁴

platform(
    name = "parent",
    constraint_values = [...],
    flags = ["--flag=1"],
)

platform(
    name = "custom",
    parents = [":parent"],
    flags = ["--flag=2"],
)

Building under --platforms=//:custom sets --flag=2. Building under --platforms=//:parent sets --flag=1. Inheritance is what makes platform-based flags scale to large device matrices: a base platform can carry the cross-cutting defaults for a family of devices, and per-device platforms only need to spell out what differs.

You can reproduce the inheritance behavior with the platform-based-flags snippet. Its parent platform sets a Starlark bool build setting to false. Its child platform overrides the same flag to true. A tiny genrule copies host.txt or device.txt according to the resulting configuration.

What This Replaces: Custom Transitions That Only Switch Platforms

The pattern this attribute is designed to retire is the "wrapper rule with a transition that only changes platforms and one or two settings" pattern. An embedded project such as Pigweed is the clearest example.¹ The Era 2 form is a custom Starlark rule that wraps a vanilla cc_binary and uses a transition to switch the platform plus a label_flag-typed FreeRTOS config:

def _m4_transition_impl(settings, attr):
    return {
        "//command_line_option:platforms":
            "//actuator/firmware/targets/m4:platform",
        "@freertos//:freertos_config":
            "//actuator/firmware/targets/m4:freertos_config",
    }

That is a real transition (allowlisted, with declared inputs and outputs, attached to a custom wrapper rule), but its body does nothing the platform itself could not say declaratively. The Era 3 form moves the same information onto the platform:¹

# //targets/rp2/BUILD.bazel
platform(
    name = "rp2040",
    flags = [
        "--@freertos//:freertos_config=//targets/rp2040:freertos_cfg",
    ],
)

Now bazel build --platforms=//targets/rp2:rp2040 //app:firmware builds the very same vanilla cc_binary with the right FreeRTOS config, no wrapper rule and no Starlark transition required. The platform definition has absorbed the bundling that the transition function used to perform.

Building For "This Other Platform" From One Top-Level Build

Platform-based flags answer the configuration half of the wrapper-rule pattern, but a separate question often comes up alongside it: "I want a single top-level build that produces artifacts for several platforms — how do I attach an artifact to a non-default platform without writing a custom transition rule?" Platform-based flags pair naturally with the generic platform_data rule from rules_platform, which simply transitions a single dependency edge to a chosen platform:¹

# //apps/blinky/BUILD.bazel
platform_data(
    name = "rp2040_blinky.elf",
    target = ":rp2040_blinky",  # a vanilla cc_binary
    platform = "//targets/rp2:rp2040",
)

platform_data is a thin, generic transition rule — the kind of wrapper teams used to handcraft for each new device family — packaged once in rules_platform so it does not need to be reinvented per project. Combined with platform-based flags, the pair takes care of the two common needs together: switch the platform, and let the platform pull in its own associated flag values.¹

The relationship between the two pieces is worth stating plainly: platform-based flags are a Bazel core feature. platform_data is a Starlark rule from rules_platform that lives outside Bazel itself. You can adopt platform-based flags without platform_data and vice versa — they just compose well for the embedded "build for this device" use case.

Where Custom Transitions Are Still The Right Tool

It is tempting to read this section and conclude that platform-based flags obsolete Starlark transitions. They do not. They obsolete one specific pattern within transitions — the one whose only job is to bundle flags with a --platforms change. Several adjacent patterns still belong in 4.7.2 Starlark Transitions or 4.7.3 Split Transitions:

• Configuration changes that don't move the platform. Switching --compilation_mode=opt for one subtree, or enabling instrumentation flags for a test subtree, has nothing to do with picking a different machine. A transition function is still the only way to express "this dep tree builds with these settings, regardless of the target platform."
• Logic that depends on rule attrs. Platform-based flags are static — the list lives on the platform() target. A transition function can read attr.* fields and compute different flag values per consumer, which a platform definition cannot.
• Multi-arch fan-out. Producing a universal binary or multi-arch container artifact is a 4.7.3 Split Transitions job: you need several configurations under one parent edge, not a single platform swap.
• Values that must be configurable. Anything you would naturally want to wrap in a select() at the platform layer is out of reach, because the flags attribute is non-configurable.

Reading this article alongside 4.7.4 Transition Boundaries & Gotchas also clarifies a non-obvious win of the platform-based form. A transition rule applied at a wrapper edge will, by default, propagate to all of its dependencies' attrs unless the rule author explicitly constrains it — which is one of the cited gotchas of transition spread. Moving the bundling onto the platform target shifts the configuration change to the top-level --platforms flag (or to a single platform_data edge) and avoids creating a custom transition whose boundaries must be maintained.

Boundary Conditions and Sharp Edges

Two limitations are worth knowing before you adopt this pattern:

• Repeated flags overwrite, not append. Repeatable flags such as --copt, --features, and any Starlark build setting declared with config.string_list(repeatable = True) do not append from platform.flags — setting them on a platform replaces the value rather than extending it.² The same defect applies to platform mappings. Both are tracked together as a known Starlark options-parser issue. If your platform tries to add an extra --copt on top of a user-supplied list, the user's value will silently disappear.
• Errors surface late. Bazel does not pre-validate the strings in flags when the platform target is loaded. An unknown or malformed flag is reported only when the platform is actually used as a target or execution platform.² In practice that means a typo in a rarely-selected platform can hide until a CI job picks that platform up.

These are the kind of details that justify the item's extra focus: the pattern is genuinely simpler than custom transitions for the cases it covers, but it is also younger, has documented edges, and is not the right answer for every configurable build.

Status In The Wider Bazel Story

Platform-based flags are part of the platforms-and-toolchains track of work, alongside aspects propagating to target toolchains, and the direction is driven by the embedded use case.⁵ That framing matters: this is not a niche escape hatch, it is the direction the platform model is moving, with embedded and cross-build users as the most visible drivers.

The honest assessment from the conspect — "a promising simplification, not yet the default answer for every configurable build" — still holds. The ecosystem guidance for platform-based flags is thinner than for classic transitions, and a lot of existing Starlark rules and tutorials predate the feature. But for the specific shape of "build for this device, with these device-bundled flags," reaching for platform.flags and platform_data before reaching for transition() is now the recommended path.