From 0f352c3497f480bbebc9507a1cfc2cdc9472b827 Mon Sep 17 00:00:00 2001 From: Googler Date: Fri, 6 Sep 2024 14:49:38 -0700 Subject: [PATCH] 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: 671898382 Change-Id: Iead81a71adb17dff46b1b442471e595769fb5c2e --- MODULE.bazel | 1 - cc/BUILD | 2 +- cc/toolchains/BUILD | 17 -------- cc/toolchains/impl/BUILD | 13 ------ cc/toolchains/impl/documented_api.bzl | 18 -------- cc/toolchains/tool_map.bzl | 50 ++++------------------- cc/toolchains/toolchain_api.md | 59 --------------------------- 7 files changed, 10 insertions(+), 150 deletions(-) delete mode 100644 cc/toolchains/impl/documented_api.bzl delete mode 100644 cc/toolchains/toolchain_api.md diff --git a/MODULE.bazel b/MODULE.bazel index 51a00b2..e7e5603 100644 --- a/MODULE.bazel +++ b/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") diff --git a/cc/BUILD b/cc/BUILD index d0db658..60c4290 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 = ["//cc/toolchains:__subpackages__"], + visibility = ["//visibility:private"], ) cc_toolchain_alias(name = "current_cc_toolchain") diff --git a/cc/toolchains/BUILD b/cc/toolchains/BUILD index 8ae4d97..1b001cb 100644 --- a/cc/toolchains/BUILD +++ b/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", -) diff --git a/cc/toolchains/impl/BUILD b/cc/toolchains/impl/BUILD index 2ad5817..8484e1c 100644 --- a/cc/toolchains/impl/BUILD +++ b/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__"], -) diff --git a/cc/toolchains/impl/documented_api.bzl b/cc/toolchains/impl/documented_api.bzl deleted file mode 100644 index d840b7e..0000000 --- a/cc/toolchains/impl/documented_api.bzl +++ /dev/null @@ -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 diff --git a/cc/toolchains/tool_map.bzl b/cc/toolchains/tool_map.bzl index 62e94e6..300523d 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 //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. - - 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. + """Configuration for which actions require which tools. Args: - 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. + name: (str) The name of the target + tools: (Dict[Action target, Executable target]) + **kwargs: kwargs to be passed to the underlying rule. """ _cc_tool_map( name = name, diff --git a/cc/toolchains/toolchain_api.md b/cc/toolchains/toolchain_api.md deleted file mode 100644 index 3a4a490..0000000 --- a/cc/toolchains/toolchain_api.md +++ /dev/null @@ -1,59 +0,0 @@ - - -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 | - -