diff --git a/MODULE.bazel b/MODULE.bazel
index e7e5603..51a00b2 100644
--- a/MODULE.bazel
+++ b/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")
diff --git a/cc/BUILD b/cc/BUILD
index 60c4290..d0db658 100644
--- a/cc/BUILD
+++ b/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")
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 @@ 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",
+)
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 @@ _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`.
-
-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 @@ 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
- 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 @@
+
+
+This is a list of rules/macros that should be exported as documentation.
+
+
+
+## cc_tool_map
+
+
+cc_tool_map(name, tools, kwargs)
+
+
+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 |
+| :------------- | :------------- | :------------- |
+| name | (str) The name of the target. | none |
+| 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 |
+| kwargs | [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule. | none |
+
+