mirror of https://github.com/bazelbuild/rules_cc
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: 671777889 Change-Id: Ib53de76f355db43a9530f7cbe11face3c9219675
This commit is contained in:
Googler
Copybara-Service
parent
0cd5c640a7
commit
0bc1ba56ef
|
|
@ -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")
|
||||
|
|
|
|||
2
cc/BUILD
2
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")
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
)
|
||||
|
|
|
|||
|
|
@ -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__"],
|
||||
)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
|
||||
Loading…
Reference in New Issue