Automated rollback of commit 6584feaab993b2396adcec1415723ec30c8a4dc8.
*** Reason for rollback ***
It cause merge conflicts for blaze release CL.
*** Original change description ***
Since toolchain-resolution.md is intended for Bazel developers, move it into the source tree.
Fixes #18424.
PiperOrigin-RevId: 534431351
Change-Id: Ifbc8aa42e4ac8fcac0913032e9c47db153f814c6
diff --git a/site/en/_book.yaml b/site/en/_book.yaml
index f9528a3..bc55891 100644
--- a/site/en/_book.yaml
+++ b/site/en/_book.yaml
@@ -150,6 +150,8 @@
path: /configure/attributes
- title: Integrating with C++ rules
path: /configure/integrate-cpp
+ - title: Implementing toolchain resolution
+ path: /configure/toolchain-resolution
- title: Code coverage with Bazel
path: /configure/coverage
- heading: Optimizing Bazel
diff --git a/site/en/configure/toolchain-resolution.md b/site/en/configure/toolchain-resolution.md
new file mode 100644
index 0000000..2713c21
--- /dev/null
+++ b/site/en/configure/toolchain-resolution.md
@@ -0,0 +1,56 @@
+Project: /_project.yaml
+Book: /_book.yaml
+
+# Toolchain Resolution Implementation Details
+
+{% include "_buttons.html" %}
+
+**Note:** This section is intended for Bazel developers, and is not needed by
+rule authors.
+
+Several SkyFunction classes implement the [toolchain resolution](/extending/toolchains) process:
+
+1. [`RegisteredToolchainsFunction`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/RegisteredToolchainsFunction.java) and
+ [`RegisteredExecutionPlatformsFunction`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/RegisteredExecutionPlatformsFunction.java)
+ find available toolchains and execution platforms, based on the current
+ configuration and WORKSPACE file.
+
+1. [`SingleToolchainResolutionFunction`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/SingleToolchainResolutionFunction.java)
+ resolves a single toolchain type for every execution platform. That is, for
+ every execution platform it finds the best registered toolchain to use based
+ on the following criteria:
+
+ 1. Make sure the toolchain and target platform are compatible, by checking
+ the `target_compatible_with` attribute.
+ 1. Make sure the toolchain and execution platform are compatible, by
+ checking the `exec_compatible_with` attribute.
+ 1. If multiple toolchains are left, choose the highest-priority one (the
+ one that was registered first).
+
+1. [`ToolchainResolutionFunction`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/ToolchainResolutionFunction.java) calls
+ `SingleToolchainResolutionFunction` for each requested toolchain type, and
+ then determines the best execution platform to use.
+
+ 1. First, remove any execution platform that does not have a valid
+ toolchain for each requested toolchain type.
+ 2. If multiple execution platforms are left, choose the highest-priority
+ one (the one that was registered first).
+ 1. If the execution platform is already set by the toolchain
+ transition, it will be selected first as described below.
+
+As discussed in [Toolchains and Configurations](/extending/toolchains#toolchains_and_configurations),
+the dependency from a target to a toolchain uses a special configuration that
+forces the execution platform to be the same for both. Despite the name
+"toolchain transition", this is not implemented as a configuration
+transition, but instead as a special subclass of
+[`ConfiguredTargetKey`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/ConfiguredTargetKey.java), called
+[`ToolchainDependencyConfiguredTargetKey`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/skyframe/ConfiguredTargetKey.java;bpv=1;bpt=1;l=164?ss=bazel&q=ConfiguredTargetKey&gsn=ToolchainDependencyConfiguredTargetKey&gs=kythe%3A%2F%2Fgithub.com%2Fbazelbuild%2Fbazel%3Flang%3Djava%3Fpath%3Dcom.google.devtools.build.lib.skyframe.ConfiguredTargetKey.ToolchainDependencyConfiguredTargetKey%2336c7e68f8cd5ea0b5a21b3769e63e6b2d489b9ca8c6f79798839e7f40cf2a19e).
+In addition to the other data in `ConfiguredTargetKey`, this subclass also holds
+the label of the execution platform. When `ToolchainResolutionFunction` is
+considering which execution platform to use, if the forced execution platform
+from the `ToolchainDependencyConfiguredTargetKey` is valid, it will be used even
+if it is not the highest-priority.
+
+**Note:** If the forced execution platform is not valid (because there are no
+valid toolchains, or because of execution constraints from the rule or target),
+then the highest-priority valid execution platform will be used instead.
diff --git a/site/en/docs/_index.yaml b/site/en/docs/_index.yaml
index aaada84..2585586 100644
--- a/site/en/docs/_index.yaml
+++ b/site/en/docs/_index.yaml
@@ -111,6 +111,8 @@
path: /configure/attributes
- heading: Integrating with C++ rules
path: /configure/integrate-cpp
+ - heading: Implementing toolchain resolution
+ path: /configure/toolchain-resolution
- heading: Code coverage with Bazel
path: /configure/coverage
- heading: "Optimizing Bazel: Best practices"
diff --git a/src/main/java/com/google/devtools/build/lib/skyframe/toolchains/README.md b/src/main/java/com/google/devtools/build/lib/skyframe/toolchains/README.md
deleted file mode 100644
index 47f1f12..0000000
--- a/src/main/java/com/google/devtools/build/lib/skyframe/toolchains/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# Toolchain Resolution Implementation Details
-
-Several SkyFunction classes implement the [toolchain resolution] process:
-
-1. [`RegisteredToolchainsFunction`] and
- [`RegisteredExecutionPlatformsFunction`] find available toolchains and
- execution platforms, based on the current configuration and WORKSPACE file.
-
-1. [`SingleToolchainResolutionFunction`] resolves a single toolchain type for
- every execution platform. That is, for every execution platform it finds the
- best registered toolchain to use based on the following criteria:
-
- 1. Make sure the toolchain and target platform are compatible, by checking
- the `target_compatible_with` attribute.
- 1. Make sure the toolchain and execution platform are compatible, by
- checking the `exec_compatible_with` attribute.
- 1. If multiple toolchains are left, choose the highest-priority one (the
- one that was registered first).
-
-1. [`ToolchainResolutionFunction`] calls `SingleToolchainResolutionFunction`
- for each requested toolchain type, and then determines the best execution
- platform to use.
-
- 1. First, remove any execution platform that does not have a valid
- toolchain for each requested toolchain type.
- 2. If multiple execution platforms are left, choose the highest-priority
- one (the one that was registered first).
- 1. If the execution platform is already set by the toolchain
- transition, it will be selected first as described below.
-
-As discussed in [Toolchains and Configurations][toolchains_and_configurations],
-the dependency from a target to a toolchain uses a special configuration that
-forces the execution platform to be the same for both. Despite the name
-"toolchain transition", this is not implemented as a configuration transition,
-but instead as a special subclass of [`ConfiguredTargetKey`], called
-[`ToolchainDependencyConfiguredTargetKey`]. In addition to the other data in
-`ConfiguredTargetKey`, this subclass also holds the label of the execution
-platform. When `ToolchainResolutionFunction` is considering which execution
-platform to use, if the forced execution platform from the
-`ToolchainDependencyConfiguredTargetKey` is valid, it will be used even if it is
-not the highest-priority.
-
-**Note:** If the forced execution platform is not valid (because there are no
-valid toolchains, or because of execution constraints from the rule or target),
-then the highest-priority valid execution platform will be used instead.
-
-**TODO:** Update this to discuss execution groups.
-
-[toolchain resolution]: https://bazel.build/extending/toolchains
-[toolchains_and_configurations]: https://bazel.build/extending/toolchains#toolchains_and_configurations
-[`ConfiguredTargetKey`]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/ConfiguredTargetKey.java
-[`RegisteredExecutionPlatformsFunction`]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/toolchains/RegisteredExecutionPlatformsFunction.java
-[`RegisteredToolchainsFunction`]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/toolchains/RegisteredToolchainsFunction.java
-[`SingleToolchainResolutionFunction`]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/toolchains/SingleToolchainResolutionFunction.java;
-[`ToolchainDependencyConfiguredTargetKey`]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/ConfiguredTargetKey.java?q=symbol%3A%5Cbcom.google.devtools.build.lib.skyframe.ConfiguredTargetKey.ToolchainDependencyConfiguredTargetKey%5Cb%20case%3Ayes
-[`ToolchainResolutionFunction`]: https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/skyframe/toolchains/ToolchainResolutionFunction.java
-
