Document that aspects can use toolchains
And remove obsolete Experimental warning.
Fixes #8558.
Closes #11357.
PiperOrigin-RevId: 310953936
diff --git a/site/docs/toolchains.md b/site/docs/toolchains.md
index f0da0ac..24e0023 100644
--- a/site/docs/toolchains.md
+++ b/site/docs/toolchains.md
@@ -188,6 +188,25 @@
made a dependency of the `bar_binary` target, not the whole space of candidate
toolchains.
+### Writing aspects that use toolchains
+
+Aspects have access to the same toolchain API as rules: you can define required
+toolchain types, access toolchains via the context, and use them to generate new
+actions using the toolchain.
+
+```py
+bar_aspect = aspect(
+ implementation = _bar_aspect_impl,
+ attrs = {},
+ toolchains = ['//bar_tools:toolchain_type'],
+)
+
+def _bar_aspect_impl(target, ctx):
+ toolchain = ctx.toolchains['//bar_tools:toolchain_type']
+ # Use the toolchain provider like in a rule.
+ return []
+```
+
## Defining toolchains
To define some toolchains for a given toolchain type, we need three things:
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleFunctionsApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleFunctionsApi.java
index 39ae162..477e754 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleFunctionsApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleFunctionsApi.java
@@ -256,8 +256,7 @@
generic1 = String.class,
defaultValue = "[]",
doc =
- "<i>(Experimental)</i><br/><br/>"
- + "If set, the set of toolchains this rule requires. Toolchains will be "
+ "If set, the set of toolchains this rule requires. Toolchains will be "
+ "found by checking the current platform, and provided to the rule "
+ "implementation via <code>ctx.toolchain</code>."),
@Param(
@@ -471,9 +470,8 @@
generic1 = String.class,
defaultValue = "[]",
doc =
- "<i>(Experimental)</i><br/><br/>"
- + "If set, the set of toolchains this rule requires. Toolchains will be "
- + "found by checking the current platform, and provided to the rule "
+ "If set, the set of toolchains this aspect requires. Toolchains will be "
+ + "found by checking the current platform, and provided to the aspect "
+ "implementation via <code>ctx.toolchain</code>."),
@Param(
name = "doc",
