Implement `transition.and_then` by fmeum · Pull Request #29542 · bazelbuild/bazel

fmeum · 2026-05-14T20:59:51Z

Description

Implements the proposal https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md.

Motivation

This change in particular allows non-toolchain dependencies of rules to inherit both the execution platform (via config.exec()) as well as the current target platform (via a custom transition that records //command_line_option:platforms), which is important for certain cross-compilation scenarios.

Build API Changes

Yes, as discussed and approved in https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md.

Checklist

I have added tests for the new use cases (if any).
I have updated the documentation (if applicable).

Release Notes

RELNOTES[NEW]: The and_then method on transitions can be used to compose transitions. Both Starlark transitions and native transitions (e.g. config.exec()) are supported.

fmeum · 2026-05-17T06:30:30Z

FYI @UebelAndre

katre

The Starlark transition composition implementation is great: it's a very nice approach that I hadn't considered.

I'm confused about the WASM compilation and CHANGELOG changes, are they from a different PR?

katre · 2026-05-18T13:43:49Z

      // defined in Starlark via, cfg = transition
      return new StarlarkRuleTransitionProvider(starlarkDefinedConfigTransition);
    }
+    if (cfg instanceof ComposedConfigurationTransitionApi composition) {


Can this be combined with the equivalent code from StarlarkAttrModule?

katre · 2026-05-18T13:49:00Z

+ * subsequent transition reads the build settings produced by the previous one. Nested compositions
+ * are flattened, so {@link #getElements} is always a flat chain of non-composed transitions.
+ */
+public final class ComposedConfigurationTransitionApi implements ConfigurationTransitionApi {


Given that this doesn't define a specific Starlark API:
a) Should this be in a different package (which makes it difficult to use from ConfigurationTransitionApi)?
b) Should this have a different name (just remove the Api)?

Renamed to ComposedConfigurationTransition (dropping Api) — agree it isn't a Starlark API surface in its own right, it's just the deferred holder backing transition.and_then. Kept it in starlarkbuildapi.config so ConfigurationTransitionApi's default and_then can still reference it; moving it under analysis.config would force every ConfigurationTransitionApi implementation to override and_then to escape the package layering.

katre · 2026-05-18T13:52:19Z

+    scratch.file(
+        "test/rules.bzl",
+        """
+        bad_transition = config.exec().and_then(config.exec())


Which line is reported as the error, line 262 or line 266? I want to be sure this is debugabble in more complex situations where transitions are defined in different Starlark files.

Good question. With the original code the error fired at the use site (the attr.label(cfg = bad_transition) line), which for cross-file definitions left the user to grep for bad_transition to find the actual .and_then call.

To make this debuggable I now capture thread.getCallerLocation() at and_then time and store it on the ComposedConfigurationTransition. The materializer includes that location in the error message, so users see both the cfg= use site (in the standard Starlark traceback) and the original composition site. For this test the error reads:

File ".../test/rules.bzl", line 5, column 31, in <toplevel> attrs = {"dep": attr.label(cfg = bad_transition)}, Error in label: invalid composed transition for `cfg`: can't compose two exec transitions (composed at /workspace/test/rules.bzl:1:40)

Test now asserts both substrings (attrs = {"dep": attr.label(cfg = bad_transition)}, and composed at /workspace/test/rules.bzl:1:).

Thanks, this looks much easier to debug.

Adds an `and_then(other)` method to the `transition` Starlark builtin that returns a new transition applying this one followed by `other`. The result is itself a transition and can be composed further. A composition may be used as a rule or attribute transition wherever its component transitions could be used. At most one of the composed factories may target the exec configuration (enforced by `ComposingTransitionFactory.of`, which now throws the new checked `IncompatibleTransitionsException` for invalid compositions; an `ofUnchecked` wrapper is provided for internal call sites where the inputs are structurally guaranteed compatible). When two of the composed transitions are 1:2+, the result has the cross product of their splits; the key for each combined split is the comma-separated concatenation of the component keys. Documents the new feature in `site/en/extending/config.md`. Also fixes `ComposingTransitionFactory.transitionType` to return the more specific of its children's types (previously always the first child's, which was incorrect for `ANY + RULE/ATTRIBUTE` compositions), and updates `DependencyResolutionHelpers.getExecutionPlatformLabel` to find the exec transition factory anywhere inside a composition via `visit`. Adds `StarlarkTransitionCompositionTest` covering all combinations of 1-2 Starlark transitions and 0-1 exec transitions (including S+E+S and split+split), plus the error cases E+E and exec-in-rule-cfg.

katre · 2026-05-21T20:54:04Z

+    scratch.file(
+        "test/rules.bzl",
+        """
+        bad_transition = config.exec().and_then(config.exec())


Thanks, this looks much easier to debug.

fmeum · 2026-05-21T21:09:14Z

@bazel-io fork 9.2.0

fmeum · 2026-05-21T21:09:19Z

@bazel-io fork 8.8.0

fmeum · 2026-05-22T18:54:58Z

@aranguyen Could you review this for approval?

gregestren

Nice to see this, @fmeum !

FYI @ajsinclair who's also interested in this.

gregestren · 2026-06-02T22:05:22Z

+
+A composed transition can be attached to a rule or attribute wherever its
+component transitions could be used (subject to the usual restriction that an
+[incoming edge transition](#incoming-edge-transitions) must be 1:1). At most one


I can't remember how the code enforces this restriction.

A Starlark transition can dynamically produce 1 or >1 outputs in its implementation function, so this property can't be checked statically. I don't think this PR changes that, but do you remember how we protect against an accidental 1:2 incoming transition? Is it only checked on evaluation?

There is

bazel/src/main/java/com/google/devtools/build/lib/analysis/producers/RuleTransitionApplier.java

Line 285 in 29ee03d

checkState(transitionResult.size() == 1, "Expected exactly one result: %s", transitionResult);

and

bazel/src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleTransitionProvider.java

Lines 249 to 254 in ef1626a

if (result.size() != 1) {

eventHandler.handle(

Event.error(

starlarkDefinedConfigTransition.getLocation(),

"Rule transition only allowed to return a single transitioned configuration."));

return buildOptions.clone();

fmeum · 2026-06-16T20:19:18Z

@gregestren This would be great to get into 9.2.0 so that folks can start playing with it, do you think that's possible?

ajsinclair · 2026-06-16T20:50:52Z

@gregestren This would be great to get into 9.2.0 so that folks can start playing with it, do you think that's possible?

For what it's worth I'll do some testing with it internal to Google once we have this submitted and released internally. Those changes might make their way out to rules_android depending on how we handle Bazel versioning requirements with that ruleset.

gregestren · 2026-06-17T15:39:14Z

@gregestren This would be great to get into 9.2.0 so that folks can start playing with it, do you think that's possible?

I pinged the import merge.

Implements the proposal https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. This change in particular allows non-toolchain dependencies of rules to inherit both the execution platform (via `config.exec()`) as well as the current target platform (via a custom transition that records `//command_line_option:platforms`), which is important for certain cross-compilation scenarios. Yes, as discussed and approved in https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. - [x] I have added tests for the new use cases (if any). - [x] I have updated the documentation (if applicable). RELNOTES[NEW]: The `and_then` method on `transition`s can be used to compose transitions. Both Starlark transitions and native transitions (e.g. `config.exec()`) are supported. Closes bazelbuild#29542. PiperOrigin-RevId: 934095515 Change-Id: I3f36ec0907c4af5bdf43e38323d166422b47051c (cherry picked from commit d089ae2)

Implements the proposal https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. This change in particular allows non-toolchain dependencies of rules to inherit both the execution platform (via `config.exec()`) as well as the current target platform (via a custom transition that records `//command_line_option:platforms`), which is important for certain cross-compilation scenarios. Yes, as discussed and approved in https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. - [x] I have added tests for the new use cases (if any). - [x] I have updated the documentation (if applicable). RELNOTES[NEW]: The `and_then` method on `transition`s can be used to compose transitions. Both Starlark transitions and native transitions (e.g. `config.exec()`) are supported. Closes bazelbuild#29542. PiperOrigin-RevId: 934095515 Change-Id: I3f36ec0907c4af5bdf43e38323d166422b47051c (cherry picked from commit d089ae2)  ### Description  ### Motivation  ### Build API Changes  No ### Checklist - [ ] I have added tests for the new use cases (if any). - [ ] I have updated the documentation (if applicable). ### Release Notes  RELNOTES: None

### Description Implements the proposal https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. ### Motivation This change in particular allows non-toolchain dependencies of rules to inherit both the execution platform (via `config.exec()`) as well as the current target platform (via a custom transition that records `//command_line_option:platforms`), which is important for certain cross-compilation scenarios. ### Build API Changes Yes, as discussed and approved in https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. ### Checklist - [x] I have added tests for the new use cases (if any). - [x] I have updated the documentation (if applicable). ### Release Notes RELNOTES[NEW]: The `and_then` method on `transition`s can be used to compose transitions. Both Starlark transitions and native transitions (e.g. `config.exec()`) are supported. Closes bazelbuild#29542. PiperOrigin-RevId: 934095515 Change-Id: I3f36ec0907c4af5bdf43e38323d166422b47051c (cherry picked from commit d089ae2)

### Description Implements the proposal https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. ### Motivation This change in particular allows non-toolchain dependencies of rules to inherit both the execution platform (via `config.exec()`) as well as the current target platform (via a custom transition that records `//command_line_option:platforms`), which is important for certain cross-compilation scenarios. ### Build API Changes Yes, as discussed and approved in https://github.com/bazelbuild/proposals/blob/main/designs/2024-04-16-transition-composition.md. ### Checklist - [x] I have added tests for the new use cases (if any). - [x] I have updated the documentation (if applicable). ### Release Notes RELNOTES[NEW]: The `and_then` method on `transition`s can be used to compose transitions. Both Starlark transitions and native transitions (e.g. `config.exec()`) are supported. Closes bazelbuild#29542. PiperOrigin-RevId: 934095515 Change-Id: I3f36ec0907c4af5bdf43e38323d166422b47051c (cherry picked from commit d089ae2) Closes bazelbuild#29620

fmeum force-pushed the compose-transitions branch 3 times, most recently from 5091465 to e33d3b9 Compare May 17, 2026 06:15

fmeum marked this pull request as ready for review May 17, 2026 06:30

fmeum requested review from a team, fweikert and gregestren as code owners May 17, 2026 06:30

fmeum requested a review from katre May 17, 2026 06:30

fmeum removed team-ExternalDeps External dependency handling, remote repositiories, WORKSPACE file. team-Loading-API BUILD file and macro processing: labels, package(), visibility, glob labels May 17, 2026

fmeum removed request for a team and fweikert May 17, 2026 06:31

katre suggested changes May 18, 2026

View reviewed changes

fmeum force-pushed the compose-transitions branch from e33d3b9 to bf62502 Compare May 21, 2026 20:34

fmeum force-pushed the compose-transitions branch from bf62502 to 29ee03d Compare May 21, 2026 20:49

katre approved these changes May 21, 2026

View reviewed changes

This was referenced May 21, 2026

[9.2.0] Implement transition.and_then #29619

Closed

[8.8.0] Implement transition.and_then #29620

Closed

github-actions Bot added the community-reviewed Reviewed by a trusted community contributor label May 21, 2026

fmeum requested a review from aranguyen May 22, 2026 18:54

katre requested a review from dabanki May 22, 2026 18:56

gregestren reviewed Jun 2, 2026

View reviewed changes

gregestren removed the team-Rules-API API for writing rules/aspects: providers, runfiles, actions, artifacts label Jun 2, 2026

fmeum requested a review from gregestren June 8, 2026 20:27

gregestren approved these changes Jun 12, 2026

View reviewed changes

gregestren added awaiting-PR-merge PR has been approved by a reviewer and is ready to be merge internally and removed awaiting-review PR is awaiting review from an assigned reviewer labels Jun 12, 2026

copybara-service Bot closed this in d089ae2 Jun 18, 2026

github-actions Bot removed the awaiting-PR-merge PR has been approved by a reviewer and is ready to be merge internally label Jun 18, 2026

fmeum mentioned this pull request Jun 18, 2026

[9.2.0] Implement transition.and_then #29888

Merged

4 tasks

iancha1992 mentioned this pull request Jun 18, 2026

[9.2.0] Implement transition.and_then (https://github.com/bazelbuild/bazel/… #29894

Closed

4 tasks

dzbarsky mentioned this pull request Jun 22, 2026

Cargo resolver-v2 host/target feature-world split hermeticbuild/rules_rs#157

Open

fmeum mentioned this pull request Jul 17, 2026

[8.8.0] Implement transition.and_then #30330

Merged

2 tasks

	if (result.size() != 1) {
	eventHandler.handle(
	Event.error(
	starlarkDefinedConfigTransition.getLocation(),
	"Rule transition only allowed to return a single transitioned configuration."));
	return buildOptions.clone();

Uh oh!

Conversation

fmeum commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Build API Changes

Checklist

Release Notes

Uh oh!

fmeum commented May 17, 2026

Uh oh!

katre left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmeum commented May 21, 2026

Uh oh!

fmeum commented May 21, 2026

Uh oh!

fmeum commented May 22, 2026

Uh oh!

gregestren left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmeum commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ajsinclair commented Jun 16, 2026

Uh oh!

gregestren commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fmeum commented May 14, 2026 •

edited

Loading

fmeum commented Jun 16, 2026 •

edited

Loading