Update toolchains.md to use footnote-style links, in order to clean up formatting.
PiperOrigin-RevId: 423884574
diff --git a/site/docs/toolchains.md b/site/docs/toolchains.md
index f26539d..8339e9e 100644
--- a/site/docs/toolchains.md
+++ b/site/docs/toolchains.md
@@ -8,13 +8,10 @@
This page describes the toolchain framework, which is a way for rule authors to
decouple their rule logic from platform-based selection of tools. It is
-recommended to read the
-[rules](skylark/rules.html)
-and
-[platforms](platforms.html)
-pages before continuing. This page covers why toolchains are needed, how to
-define and use them, and how Bazel selects an appropriate toolchain based on
-platform constraints.
+recommended to read the [rules][Rules] and [platforms][Platforms] pages before
+continuing. This page covers why toolchains are needed, how to define and use
+them, and how Bazel selects an appropriate toolchain based on platform
+constraints.
## Motivation
@@ -89,7 +86,7 @@
```
You can improve on this solution by using `select` to choose the `compiler`
-[based on the platform](configurable-attributes.html):
+[based on the platform][Configurable attributes]:
```python
config_setting(
@@ -116,11 +113,11 @@
)
```
-But this is tedious and a bit much to ask of every single `bar_binary` user.
-If this style is not used consistently throughout the workspace, it leads to
-builds that work fine on a single platform but fail when extended to
-multi-platform scenarios. It also does not address the problem of adding support
-for new platforms and compilers without modifying existing rules or targets.
+But this is tedious and a bit much to ask of every single `bar_binary` user. If
+this style is not used consistently throughout the workspace, it leads to builds
+that work fine on a single platform but fail when extended to multi-platform
+scenarios. It also does not address the problem of adding support for new
+platforms and compilers without modifying existing rules or targets.
The toolchain framework solves this problem by adding an extra level of
indirection. Essentially, you declare that your rule has an abstract dependency
@@ -177,11 +174,10 @@
```
`ctx.toolchains["//bar_tools:toolchain_type"]` returns the
-[`ToolchainInfo` provider](skylark/lib/platform_common.html#ToolchainInfo)
-of whatever target Bazel resolved the toolchain dependency to. The fields of the
-`ToolchainInfo` object are set by the underlying tool's rule; in the next
-section, this rule is defined such that there is a `barcinfo` field that wraps
-a `BarcInfo` object.
+[`ToolchainInfo` provider][ToolchainInfo] of whatever target Bazel resolved the
+toolchain dependency to. The fields of the `ToolchainInfo` object are set by the
+underlying tool's rule; in the next section, this rule is defined such that
+there is a `barcinfo` field that wraps a `BarcInfo` object.
Bazel's procedure for resolving toolchains to targets is described
[below](#toolchain-resolution). Only the resolved toolchain target is actually
@@ -211,19 +207,19 @@
To define some toolchains for a given toolchain type, you need three things:
-1. A language-specific rule representing the kind of tool or tool suite. By
- convention this rule's name is suffixed with "\_toolchain".
+1. A language-specific rule representing the kind of tool or tool suite. By
+ convention this rule's name is suffixed with "\_toolchain".
-2. Several targets of this rule type, representing versions of the tool or tool
- suite for different platforms.
+2. Several targets of this rule type, representing versions of the tool or tool
+ suite for different platforms.
-3. For each such target, an associated target of the generic
- [`toolchain`](be/platform.html#toolchain)
- rule, to provide metadata used by the toolchain framework. This `toolchain`
- target also refers to the `toolchain_type` associated with this toolchain.
- This means that a given `_toolchain` rule could be associated with any
- `toolchain_type`, and that only in a `toolchain` instance that uses
- this `_toolchain` rule that the rule is associated with a `toolchain_type`.
+3. For each such target, an associated target of the generic
+ [`toolchain`][Toolchain rule] rule, to provide metadata used by the
+ toolchain framework. This `toolchain` target also refers to the
+ `toolchain_type` associated with this toolchain. This means that a given
+ `_toolchain` rule could be associated with any `toolchain_type`, and that
+ only in a `toolchain` instance that uses this `_toolchain` rule that the
+ rule is associated with a `toolchain_type`.
For our running example, here's a definition for a `bar_toolchain` rule. Our
example has only a compiler, but other tools such as a linker could also be
@@ -322,8 +318,7 @@
toolchain targets, and `toolchain` definition targets can't all be in separate
packages.
-See the [`go_toolchain`](https://github.com/bazelbuild/rules_go/blob/master/go/private/go_toolchain.bzl)
-for a real-world example.
+See the [`go_toolchain`][Go toolchain] for a real-world example.
## Registering and building with toolchains
@@ -373,55 +368,51 @@
## Toolchain resolution
-**Note:**
-[Some Bazel rules](platforms-intro.html#status)
-do not yet support toolchain resolution.
+**Note:** [Some Bazel rules][Rules status] do not yet support toolchain
+resolution.
For each target that uses toolchains, Bazel's toolchain resolution procedure
-determines the target's concrete toolchain dependencies. The procedure takes as input a
-set of required toolchain types, the target platform, the list of available
-execution platforms, and the list of available toolchains. Its outputs are a
-selected toolchain for each toolchain type as well as a selected execution
+determines the target's concrete toolchain dependencies. The procedure takes as
+input a set of required toolchain types, the target platform, the list of
+available execution platforms, and the list of available toolchains. Its outputs
+are a selected toolchain for each toolchain type as well as a selected execution
platform for the current target.
The available execution platforms and toolchains are gathered from the
`WORKSPACE` file via
-[`register_execution_platforms`](skylark/lib/globals.html#register_execution_platforms)
-and
-[`register_toolchains`](skylark/lib/globals.html#register_toolchains).
-Additional execution platforms and toolchains may also be specified on the
-command line via
-[`--extra_execution_platforms`](command-line-reference.html#flag--extra_execution_platforms)
-and
-[`--extra_toolchains`](command-line-reference.html#flag--extra_toolchains).
-The host platform is automatically included as an available execution platform.
-Available platforms and toolchains are tracked as ordered lists for determinism,
-with preference given to earlier items in the list.
+[`register_execution_platforms`][Workspace function register_execution_platforms]
+and [`register_toolchains`][Workspace function register_toolchains]. Additional
+execution platforms and toolchains may also be specified on the command line via
+[`--extra_execution_platforms`][Flag extra_execution_platforms] and
+[`--extra_toolchains`][Flag extra_toolchains]. The host platform is
+automatically included as an available execution platform. Available platforms
+and toolchains are tracked as ordered lists for determinism, with preference
+given to earlier items in the list.
The resolution steps are as follows.
-1. A `target_compatible_with` or `exec_compatible_with` clause *matches* a
- platform iff, for each `constraint_value` in its list, the platform also has
- that `constraint_value` (either explicitly or as a default).
+1. A `target_compatible_with` or `exec_compatible_with` clause *matches* a
+ platform iff, for each `constraint_value` in its list, the platform also has
+ that `constraint_value` (either explicitly or as a default).
- If the platform has `constraint_value`s from `constraint_setting`s not
- referenced by the clause, these do not affect matching.
+ If the platform has `constraint_value`s from `constraint_setting`s not
+ referenced by the clause, these do not affect matching.
-1. If the target being built specifies the
- [`exec_compatible_with` attribute](be/common-definitions.html#common.exec_compatible_with)
- (or its rule definition specifies the
- [`exec_compatible_with` argument](skylark/lib/globals.html#rule.exec_compatible_with)),
- the list of available execution platforms is filtered to remove
- any that do not match the execution constraints.
+1. If the target being built specifies the
+ [`exec_compatible_with` attribute][Common exec_compatible_with attribute]
+ (or its rule definition specifies the
+ [`exec_compatible_with` argument][Rule exec_compatible_with argument]) the
+ list of available execution platforms is filtered to remove any that do not
+ match the execution constraints.
-1. For each available execution platform, you associate each toolchain type with
- the first available toolchain, if any, that is compatible with this execution
- platform and the target platform.
+1. For each available execution platform, you associate each toolchain type
+ with the first available toolchain, if any, that is compatible with this
+ execution platform and the target platform.
-1. Any execution platform that failed to find a compatible toolchain for one of
- its toolchain types is ruled out. Of the remaining platforms, the first one
- becomes the current target's execution platform, and its associated
- toolchains become dependencies of the target.
+1. Any execution platform that failed to find a compatible toolchain for one of
+ its toolchain types is ruled out. Of the remaining platforms, the first one
+ becomes the current target's execution platform, and its associated
+ toolchains become dependencies of the target.
The chosen execution platform is used to run all actions that the target
generates.
@@ -434,9 +425,9 @@
If you are adding toolchain support to an existing rule, use the
`--toolchain_resolution_debug=regex` flag. During toolchain resolution, the flag
-provides verbose output for toolchain types that match the regex variable. You
-can use `.*` to output all information. Bazel will output names of toolchains it
-checks and skips during the resolution process.
+provides verbose output for toolchain types or target names that match the regex
+variable. You can use `.*` to output all information. Bazel will output names of
+toolchains it checks and skips during the resolution process.
If you'd like to see which [`cquery`][cquery] dependencies are from toolchain
resolution, use `cquery`'s [`--transitions`][cquery-transitions] flag:
@@ -461,7 +452,18 @@
[toolchain dependency]#@local_config_cc//:cc-compiler-k8#HostTransition -> b6df211
```
-<!-- being-block:external
+[Common exec_compatible_with attribute]: be/common-definitions.html#common.exec_compatible_with
+[Configurable attributes]: configurable-attributes.html
[cquery]: cquery.html
[cquery-transitions]: cquery.html#transitions
-
+[Flag extra_execution_platforms]: command-line-reference.html#flag--extra_execution_platforms
+[Flag extra_toolchains]: command-line-reference.html#flag--extra_toolchains
+[Go toolchain]: https://github.com/bazelbuild/rules_go/blob/master/go/private/go_toolchain.bzl
+[Platforms]: platforms.html
+[Rule exec_compatible_with argument]: skylark/lib/globals.html#rule.exec_compatible_with
+[Rules]: skylark/rules.html
+[Rules status]: platforms-intro.html#status
+[ToolchainInfo]: skylark/lib/platform_common.html#ToolchainInfo
+[Toolchain rule]: be/platform.html#toolchain
+[Workspace function register_execution_platforms]: skylark/lib/globals.html#register_execution_platforms
+[Workspace function register_toolchains]: skylark/lib/globals.html#register_toolchains
