Automated rollback of commit 0f352c3497f480bbebc9507a1cfc2cdc9472b827.
*** Reason for rollback ***
Rollforward with fix for b/365154741
*** Original change description ***
Automated rollback of commit 0bc1ba56ef2f8e791841bc074376a02ad8608dc2.
*** 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
diff --git a/MODULE.bazel b/MODULE.bazel
index e7e5603..51a00b2 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -6,6 +6,7 @@
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")
diff --git a/cc/BUILD b/cc/BUILD
index 60c4290..d0db658 100644
--- a/cc/BUILD
+++ b/cc/BUILD
@@ -97,7 +97,7 @@
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")
diff --git a/cc/toolchains/BUILD b/cc/toolchains/BUILD
index 1b001cb..8ae4d97 100644
--- a/cc/toolchains/BUILD
+++ b/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 @@
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 @@
]),
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",
+)
diff --git a/cc/toolchains/impl/BUILD b/cc/toolchains/impl/BUILD
index 8484e1c..2ad5817 100644
--- a/cc/toolchains/impl/BUILD
+++ b/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__"],
+)
diff --git a/cc/toolchains/impl/documented_api.bzl b/cc/toolchains/impl/documented_api.bzl
new file mode 100644
index 0000000..d840b7e
--- /dev/null
+++ b/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
diff --git a/cc/toolchains/tool_map.bzl b/cc/toolchains/tool_map.bzl
index 300523d..62e94e6 100644
--- a/cc/toolchains/tool_map.bzl
+++ b/cc/toolchains/tool_map.bzl
@@ -51,7 +51,7 @@
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 @@
allow_files = True,
doc = """The tool to use for the specified actions.
-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.
+The tool may be a `cc_tool` or other executable rule.
""",
),
},
@@ -71,12 +68,47 @@
)
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
- tools: (Dict[Action target, Executable target])
- **kwargs: kwargs to be passed to the underlying rule.
+ name: (str) The name of the target.
+ 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.
+ **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
"""
_cc_tool_map(
name = name,
diff --git a/cc/toolchains/toolchain_api.md b/cc/toolchains/toolchain_api.md
new file mode 100644
index 0000000..3a4a490
--- /dev/null
+++ b/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 |
+
+
