Update documentation for key-based split transitions.
PiperOrigin-RevId: 386508244
diff --git a/site/docs/skylark/config.md b/site/docs/skylark/config.md
index f326c4a..1b66d35 100644
--- a/site/docs/skylark/config.md
+++ b/site/docs/skylark/config.md
@@ -477,10 +477,12 @@
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/multi_arch_binary)
-[Outgoing edge transition](#outgoing-edge-transitions) can map a single input
-configuration to two or more output configurations. These are defined in
-Starlark by returning a list of dictionaries in the transition implementation
-function.
+[Outgoing edge transitions](#outgoing-edge-transitions) can map a single input
+configuration to two or more output configurations. This is useful for defining
+rules that bundle multi-architecture code.
+
+1:2+ transitions are defined by returning a list of dictionaries in the
+transition implementation function.
```python
# example/transitions/transitions.bzl
@@ -498,6 +500,28 @@
)
```
+They can also set custom keys that the rule implementation function can use to
+read individual dependencies:
+
+```python
+# example/transitions/transitions.bzl
+def _impl(settings, attr):
+ _ignore = (settings, attr)
+ return {
+ "Apple deps": {"//command_line_option:cpu": "ppc"},
+ "Linux deps": {"//command_line_option:cpu": "x86"},
+ }
+
+multi_arch_transition = transition(
+ implementation = _impl,
+ inputs = [],
+ outputs = ["//command_line_option:cpu"]
+)
+```
+
+See [Accessing attributes with transitions](#accessing-attributes-with-transitions)
+for how to read these keys.
+
### Attaching transitions
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/attaching_transitions_to_rules)
@@ -652,10 +676,9 @@
[End to end example](https://github.com/bazelbuild/examples/tree/HEAD/rules/starlark_configurations/read_attr_in_transition)
When [attaching a transition to an outgoing edge](#outgoing-edge-transitions)
-(regardless of whether the transition is a 1:1 or 1:2+ transition) access to
-values of that attribute in the rule implementation changes. Access through
-`ctx.attr` is forced to be a list if it isn't already. The order of elements in
-this list is unspecified.
+(regardless of whether the transition is a [1:1](#defining) or
+[1:2+](#defining-12-transitions) transition) `ctx.attr` is forced to be a list
+if it isn't already. The order of elements in this list is unspecified.
```python
# example/transitions/rules.bzl
@@ -685,8 +708,39 @@
})
```
-Access to the value of a single branch of a 1:2+
-[has not been implemented yet](https://github.com/bazelbuild/bazel/issues/8633).
+If the transition is `1:2+` and sets custom keys, `ctx.split_attr` can be used
+to read individual deps for each key:
+
+```python
+# example/transitions/rules.bzl
+def _impl(settings, attr):
+ _ignore = (settings, attr)
+ return {
+ "Apple deps": {"//command_line_option:cpu": "ppc"},
+ "Linux deps": {"//command_line_option:cpu": "x86"},
+ }
+
+multi_arch_transition = transition(
+ implementation = _impl,
+ inputs = [],
+ outputs = ["//command_line_option:cpu"]
+)
+
+def _rule_impl(ctx):
+ apple_dep = ctx.split_attr.dep["Apple deps"]
+ linux_dep = ctx.split_attr.dep["Linux deps"]
+ # ctx.attr has a list of all deps for all keys. Order is not guaranteed.
+ all_deps = ctx.attr.dep
+
+multi_arch_rule = rule(
+ implementation = _rule_impl,
+ attrs = {
+ "dep": attr.label(cfg = multi_arch_transition)
+ })
+```
+
+See [here](https://github.com/bazelbuild/examples/tree/main/rules/starlark_configurations/multi_arch_binary)
+for a complete example.
## Integration with platforms and toolchains
Many native flags today, like `--cpu` and `--crosstool_top` are related to
