bazel
/
rules_cc
mirror of https://github.com/bazelbuild/rules_cc
2
0
Fork 0
Code Issues Releases Activity

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
This commit is contained in:
Googler 2024-09-06 14:49:38 -07:00 committed by Copybara-Service
parent 0bc1ba56ef
commit 0f352c3497
7 changed files with 10 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
MODULE.bazel
View File

@ -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")

2
cc/BUILD
View File

@ -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")

17
cc/toolchains/BUILD
View File

@ -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",
)

13
cc/toolchains/impl/BUILD
View File

@ -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__"],
)

18
cc/toolchains/impl/documented_api.bzl
View File

@ -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

50
cc/toolchains/tool_map.bzl
View File

@ -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,

59
cc/toolchains/toolchain_api.md
View File

@ -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 |