Automated rollback of commit 0f352c3497.

*** Reason for rollback ***

Rollforward with fix for b/365154741

*** Original change description ***

Automated rollback of commit 0bc1ba56ef.

*** Reason for rollback ***

TAP failures in Bazel/Blaze, see b/365154741 and discussion at https://chat.google.com/room/AAAAXE3XKrY/_e3TpBFJvus

*** Original change description ***

Add user-facing documentation for cc_tool_map

BEGIN_PUBLIC

Add user-facing documentation for cc_tool_map

Adds user-facing documentation for the cc_tool_map toolchain rule, including an example and higher level analogies.

END_PUBLIC

***

***

PiperOrigin-RevId: 672000172
Change-Id: If7ad64e2378a2016d389a3718944aa04bc5e9759

MODULE.bazel

@@ -6,6 +6,7 @@ module(
 
 bazel_dep(name = "bazel_skylib", version = "1.7.1")
 bazel_dep(name = "platforms", version = "0.0.7")
+bazel_dep(name = "stardoc", version = "0.7.0")
 
 cc_configure = use_extension("@bazel_tools//tools/cpp:cc_configure.bzl", "cc_configure_extension")
 use_repo(cc_configure, "local_config_cc_toolchains")

cc/BUILD

@@ -97,7 +97,7 @@ bzl_library(
 bzl_library(
     name = "cc_toolchain_config_lib_bzl",
     srcs = ["cc_toolchain_config_lib.bzl"],
-    visibility = ["//visibility:private"],
+    visibility = ["//cc/toolchains:__subpackages__"],
 )
 
 cc_toolchain_alias(name = "current_cc_toolchain")

cc/toolchains/BUILD

@@ -14,6 +14,8 @@
 
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@bazel_skylib//rules:common_settings.bzl", "bool_flag")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
 
 bool_flag(
     name = "experimental_enable_rule_based_toolchains",
@@ -27,9 +29,11 @@ bzl_library(
     visibility = ["//visibility:public"],
     deps = [
         "//cc:action_names_bzl",
+        "//cc:cc_toolchain_config_lib_bzl",
         "//cc:find_cc_toolchain_bzl",
         "//cc/private/rules_impl:cc_flags_supplier_lib_bzl",
         "//cc/private/rules_impl:native_bzl",
+        "//cc/toolchains/impl:toolchain_impl_rules",
         "@bazel_skylib//rules/directory:glob",
     ],
 )
@@ -42,3 +46,16 @@ filegroup(
     ]),
     visibility = ["//visibility:public"],
 )
+
+stardoc(
+    name = "toolchain_api",
+    out = "generated_toolchain_api.md",
+    input = "//cc/toolchains/impl:documented_api.bzl",
+    deps = [":toolchain_rules"],
+)
+
+diff_test(
+    name = "toolchain_api_diff_test",
+    file1 = ":generated_toolchain_api.md",
+    file2 = ":toolchain_api.md",
+)

cc/toolchains/impl/BUILD

@@ -4,3 +4,16 @@
 
 # I wanted to call it private / internal, but then buildifier complains about
 # referencing it from the tests directory.
+
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+exports_files(
+    ["documented_api.bzl"],
+    visibility = ["//cc/toolchains:__subpackages__"],
+)
+
+bzl_library(
+    name = "toolchain_impl_rules",
+    srcs = glob(["*.bzl"]),
+    visibility = ["//cc/toolchains:__subpackages__"],
+)

cc/toolchains/impl/documented_api.bzl

@@ -0,0 +1,18 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""This is a list of rules/macros that should be exported as documentation."""
+
+load("//cc/toolchains:tool_map.bzl", _cc_tool_map = "cc_tool_map")
+
+cc_tool_map = _cc_tool_map

cc/toolchains/tool_map.bzl

@@ -51,7 +51,7 @@ _cc_tool_map = rule(
             mandatory = True,
             doc = """A list of action names to apply this action to.
 
-See @toolchain//actions:all for valid options.
+See //cc/toolchains/actions:BUILD for valid options.
 """,
         ),
         "tools": attr.label_list(
@@ -60,10 +60,7 @@ See @toolchain//actions:all for valid options.
             allow_files = True,
             doc = """The tool to use for the specified actions.
 
-A tool is usually a binary, but may be a `cc_tool`.
+The tool may be a `cc_tool` or other executable rule.
-
-If multiple tools are specified, the first tool that has `with_features` that
-satisfy the currently enabled feature set is used.
 """,
         ),
     },
@@ -71,12 +68,47 @@ satisfy the currently enabled feature set is used.
 )
 
 def cc_tool_map(name, tools, **kwargs):
-    """Configuration for which actions require which tools.
+    """A toolchain configuration rule that maps toolchain actions to tools.
+
+    A cc_tool_map aggregates all the tools that may be used for a given toolchain and maps them to
+    their corresponding actions. Conceptually, this is similar to the `CXX=/path/to/clang++`
+    environment variables that most build systems use to determine which tools to use for a given
+    action. To simplify usage, some actions have been grouped together (for example,
+    //cc/toolchains/actions:cpp_compile_actions) to
+    logically express "all the C++ compile actions".
+
+    In Bazel, there is a little more granularity to the mapping, so the mapping doesn't follow the
+    traditional `CXX`, `AR`, etc. naming scheme. For a comprehensive list of all the well-known
+    actions, see //cc/toolchains/actions:BUILD.
+
+    Example usage:
+    ```
+    load("//cc/toolchains:tool_map.bzl", "cc_tool_map")
+
+    cc_tool_map(
+        name = "all_tools",
+        tools = {
+            "//cc/toolchains/actions:assembly_actions": ":asm",
+            "//cc/toolchains/actions:c_compile": ":clang",
+            "//cc/toolchains/actions:cpp_compile_actions": ":clang++",
+            "//cc/toolchains/actions:link_actions": ":lld",
+            "//cc/toolchains/actions:objcopy_embed_data": ":llvm-objcopy",
+            "//cc/toolchains/actions:strip": ":llvm-strip",
+            "//cc/toolchains/actions:ar_actions": ":llvm-ar",
+        },
+    )
+    ```
+
+    Note:
+       Due to an implementation limitation, if you need to map the same tool to multiple actions,
+       you will need to create an intermediate alias for the tool for each set of actions. See
+       https://github.com/bazelbuild/rules_cc/issues/235 for more details.
 
     Args:
-        name: (str) The name of the target
+        name: (str) The name of the target.
-        tools: (Dict[Action target, Executable target])
+        tools: (Dict[target providing ActionTypeSetInfo, Executable target]) A mapping between `cc_action_type` targets
-        **kwargs: kwargs to be passed to the underlying rule.
+            and the `cc_tool` or executable target that implements that action.
+        **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
     """
     _cc_tool_map(
         name = name,

cc/toolchains/toolchain_api.md

@@ -0,0 +1,59 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+This is a list of rules/macros that should be exported as documentation.
+
+<a id="cc_tool_map"></a>
+
+## cc_tool_map
+
+<pre>
+cc_tool_map(<a href="#cc_tool_map-name">name</a>, <a href="#cc_tool_map-tools">tools</a>, <a href="#cc_tool_map-kwargs">kwargs</a>)
+</pre>
+
+A toolchain configuration rule that maps toolchain actions to tools.
+
+A cc_tool_map aggregates all the tools that may be used for a given toolchain and maps them to
+their corresponding actions. Conceptually, this is similar to the `CXX=/path/to/clang++`
+environment variables that most build systems use to determine which tools to use for a given
+action. To simplify usage, some actions have been grouped together (for example,
+//third_party/bazel_rules/rules_cc/cc/toolchains/actions:cpp_compile_actions) to
+logically express "all the C++ compile actions".
+
+In Bazel, there is a little more granularity to the mapping, so the mapping doesn't follow the
+traditional `CXX`, `AR`, etc. naming scheme. For a comprehensive list of all the well-known
+actions, see //third_party/bazel_rules/rules_cc/cc/toolchains/actions:BUILD.
+
+Example usage:
+```
+load("//third_party/bazel_rules/rules_cc/cc/toolchains:tool_map.bzl", "cc_tool_map")
+
+cc_tool_map(
+    name = "all_tools",
+    tools = {
+        "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:assembly_actions": ":asm",
+        "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:c_compile": ":clang",
+        "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:cpp_compile_actions": ":clang++",
+        "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:link_actions": ":lld",
+        "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:objcopy_embed_data": ":llvm-objcopy",
+        "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:strip": ":llvm-strip",
+        "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:ar_actions": ":llvm-ar",
+    },
+)
+```
+
+Note:
+   Due to an implementation limitation, if you need to map the same tool to multiple actions,
+   you will need to create an intermediate alias for the tool for each set of actions. See
+   https://github.com/bazelbuild/rules_cc/issues/235 for more details.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="cc_tool_map-name"></a>name |  (str) The name of the target.   |  none |
+| <a id="cc_tool_map-tools"></a>tools |  (Dict[target providing ActionTypeSetInfo, Executable target]) A mapping between `cc_action_type` targets and the `cc_tool` or executable target that implements that action.   |  none |
+| <a id="cc_tool_map-kwargs"></a>kwargs |  [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.   |  none |
+
+