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: 671898382
Change-Id: Iead81a71adb17dff46b1b442471e595769fb5c2e

MODULE.bazel

@@ -6,7 +6,6 @@ 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 = ["//cc/toolchains:__subpackages__"],
+    visibility = ["//visibility:private"],
 )
 
 cc_toolchain_alias(name = "current_cc_toolchain")

cc/toolchains/BUILD

@@ -14,8 +14,6 @@
 
 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",
@@ -29,11 +27,9 @@ 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",
     ],
 )
@@ -46,16 +42,3 @@ 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,16 +4,3 @@
 
 # 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

@@ -1,18 +0,0 @@
-# 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 //cc/toolchains/actions:BUILD for valid options.
+See @toolchain//actions:all for valid options.
 """,
         ),
         "tools": attr.label_list(
@@ -60,7 +60,10 @@ See //cc/toolchains/actions:BUILD for valid options.
             allow_files = True,
             doc = """The tool to use for the specified actions.
 
-The tool may be a `cc_tool` or other executable rule.
+A tool is usually a binary, but may be a `cc_tool`.
+
+If multiple tools are specified, the first tool that has `with_features` that
+satisfy the currently enabled feature set is used.
 """,
         ),
     },
@@ -68,47 +71,12 @@ The tool may be a `cc_tool` or other executable rule.
 )
 
 def cc_tool_map(name, tools, **kwargs):
-    """A toolchain configuration rule that maps toolchain actions to tools.
+    """Configuration for which actions require which 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[target providing ActionTypeSetInfo, Executable target]) A mapping between `cc_action_type` targets
+        tools: (Dict[Action target, Executable target])
-            and the `cc_tool` or executable target that implements that action.
+        **kwargs: kwargs to be passed to the underlying rule.
-        **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

@@ -1,59 +0,0 @@
-<!-- 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 |
-
-