Add cc_action_type and cc_tool documentation
BEGIN_PUBLIC
Add cc_action_type and cc_tool documentation
Extends the toolchain API documentation to include docs for cc_action_type, cc_action_type_set, cc_variable, and cc_tool.
Also improves cross-reference links and copybara behavior for docs.
END_PUBLIC
PiperOrigin-RevId: 680601617
Change-Id: Idbbdfbcb2c5a1c3598b6a7e7ba985ed14f871099
diff --git a/cc/toolchains/BUILD b/cc/toolchains/BUILD
index 45883c6..98fe2cf 100644
--- a/cc/toolchains/BUILD
+++ b/cc/toolchains/BUILD
@@ -16,6 +16,8 @@
load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@bazel_skylib//rules:expand_template.bzl", "expand_template")
load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+load("//cc/toolchains/impl:documented_api.bzl", "DOCUMENTED_TOOLCHAIN_RULES")
+load("//cc/toolchains/impl:markdown_helpers.bzl", "xref_substitutions")
bzl_library(
name = "toolchain_rules",
@@ -48,13 +50,22 @@
deps = [":toolchain_rules"],
)
-# In GitHub, we prefer to clarify all the labels that come from rules_cc.
expand_template(
name = "toolchain_api_md",
out = "generated_toolchain_api.md",
+ # Dictionary order 100% matters here!
+ # buildifier: disable=unsorted-dict-items
substitutions = {
- "\"//cc": "\"@rules_cc//cc",
- },
+ # Strip @rules_cc to prevent instances of @rules_cc@rules_cc//cc.
+ "@rules_cc//cc": "//cc",
+ # In GitHub, we prefer to clarify all the labels that come from
+ # rules_cc.
+ "//cc": "@rules_cc//cc",
+ } | xref_substitutions({
+ "`{}`".format(rule_name): "#{}".format(rule_name)
+ for rule_name in DOCUMENTED_TOOLCHAIN_RULES
+ }),
+ # buildifier: enable=unsorted-dict-items
template = ":raw_generated_toolchain_api.md",
)
diff --git a/cc/toolchains/actions.bzl b/cc/toolchains/actions.bzl
index fc91787..78c1fc6 100644
--- a/cc/toolchains/actions.bzl
+++ b/cc/toolchains/actions.bzl
@@ -37,14 +37,26 @@
},
doc = """A type of action (eg. c_compile, assemble, strip).
-Example:
+`cc_action_type` rules are used to associate arguments and tools together to
+perform a specific action. Bazel prescribes a set of known action types that are used to drive
+typical C/C++/ObjC actions like compiling, linking, and archiving. The set of well-known action
+types can be found in [//cc/toolchains/actions:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD).
-load("@rules_cc//cc:action_names.bzl", "ACTION_NAMES")
+It's possible to create project-specific action types for use in toolchains. Be careful when
+doing this, because every toolchain that encounters the action will need to be configured to
+support the custom action type. If your project is a library, avoid creating new action types as
+it will reduce compatibility with existing toolchains and increase setup complexity for users.
+
+Example:
+```
+load("//cc:action_names.bzl", "ACTION_NAMES")
+load("//cc/toolchains:actions.bzl", "cc_action_type")
cc_action_type(
- name = "cpp_compile",
- action_name = = ACTION_NAMES.cpp_compile,
+ name = "cpp_compile",
+ action_name = = ACTION_NAMES.cpp_compile,
)
+```
""",
provides = [ActionTypeInfo, ActionTypeSetInfo],
)
@@ -60,15 +72,21 @@
cc_action_type_set = rule(
doc = """Represents a set of actions.
+This is a convenience rule to allow for more compact representation of a group of action types.
+Use this anywhere a `cc_action_type` is accepted.
+
Example:
+```
+load("//cc/toolchains:actions.bzl", "cc_action_type_set")
cc_action_type_set(
name = "link_executable_actions",
actions = [
- ":cpp_link_executable",
- ":lto_index_for_executable",
+ "//cc/toolchains/actions:cpp_link_executable",
+ "//cc/toolchains/actions:lto_index_for_executable",
],
)
+```
""",
implementation = _cc_action_type_set_impl,
attrs = {
diff --git a/cc/toolchains/args.bzl b/cc/toolchains/args.bzl
index eb3833e..bdcf7ce 100644
--- a/cc/toolchains/args.bzl
+++ b/cc/toolchains/args.bzl
@@ -139,9 +139,10 @@
This rule is the fundamental building building block for every toolchain tool invocation. Each
argument expressed in a toolchain tool invocation (e.g. `gcc`, `llvm-ar`) is declared in a
- `cc_args` rule that applies an ordered list of arguments to a set of toolchain actions.
- `cc_args` rules can be added unconditionally to a `cc_toolchain`, conditionally via `select()`
- statements, or dynamically via an intermediate `cc_feature`.
+ `cc_args` rule that applies an ordered list of arguments to a set of toolchain
+ actions. `cc_args` rules can be added unconditionally to a
+ `cc_toolchain`, conditionally via `select()` statements, or dynamically via an
+ intermediate `cc_feature`.
Conceptually, this is similar to the old `CFLAGS`, `CPPFLAGS`, etc. environment variables that
many build systems use to determine which flags to use for a given action. The significant
@@ -208,49 +209,62 @@
Args:
name: (str) The name of the target.
- actions: (List[Label]) A list of labels of `cc_action_type` or `cc_action_type_set` rules
- that dictate which actions these arguments should be applied to.
+ actions: (List[Label]) A list of labels of `cc_action_type` or
+ `cc_action_type_set` rules that dictate which actions these
+ arguments should be applied to.
allowlist_include_directories: (List[Label]) A list of include paths that are implied by
using this rule. These must point to a skylib
- [directory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_doc.md#directory)
- or [subdirectory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_subdirectory_doc.md#subdirectory) rule.
+ [directory](https://github.com/bazelbuild/bazel-skylib/tree/main/doc/directory_doc.md#directory)
+ or [subdirectory](https://github.com/bazelbuild/bazel-skylib/tree/main/doc/directory_subdirectory_doc.md#subdirectory) rule.
Some flags (e.g. --sysroot) imply certain include paths are available despite
not explicitly specifying a normal include path flag (`-I`, `-isystem`, etc.).
Bazel checks that all included headers are properly provided by a dependency or
allowlisted through this mechanism.
+
+ As a rule of thumb, only use this if Bazel is complaining about absolute paths in
+ your toolchain and you've ensured that the toolchain is compiling with the
+ `-no-canonical-prefixes` and/or `-fno-canonical-system-headers` arguments.
+
+ This can help work around errors like:
+ `the source file 'main.c' includes the following non-builtin files with absolute paths
+ (if these are builtin files, make sure these paths are in your toolchain)`.
args: (List[str]) The command-line arguments that are applied by using this rule. This is
mutually exclusive with [nested](#cc_args-nested).
data: (List[Label]) A list of runtime data dependencies that are required for these
arguments to work as intended.
env: (Dict[str, str]) Environment variables that should be set when the tool is invoked.
format: (Dict[str, Label]) A mapping of format strings to the label of the corresponding
- `cc_variable` that the value should be pulled from. All instances of `{variable_name}`
- will be replaced with the expanded value of `variable_name` in this dictionary. The
- complete list of possible variables can be found in
- https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is
- not possible to declare custom variables--these are inherent to Bazel itself.
+ `cc_variable` that the value should be pulled from. All instances of
+ `{variable_name}` will be replaced with the expanded value of `variable_name` in this
+ dictionary. The complete list of possible variables can be found in
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD.
+ It is not possible to declare custom variables--these are inherent to Bazel itself.
iterate_over: (Label) The label of a `cc_variable` that should be iterated over. This is
intended for use with built-in variables that are lists.
- nested: (List[Label]) A list of [cc_nested_args](#cc_nested_args) rules that should be
+ nested: (List[Label]) A list of `cc_nested_args` rules that should be
expanded to command-line arguments when this rule is used. This is mutually exclusive
with [args](#cc_args-args).
- requires_not_none: (Label) The label of a `cc_variable` that should be checked for
- existence before expanding this rule. If the variable is None, this rule will be
+ requires_not_none: (Label) The label of a `cc_variable` that should be checked
+ for existence before expanding this rule. If the variable is None, this rule will be
ignored.
- requires_none: (Label) The label of a `cc_variable` that should be checked for non-existence
- before expanding this rule. If the variable is not None, this rule will be ignored.
- requires_true: (Label) The label of a `cc_variable` that should be checked for truthiness
- before expanding this rule. If the variable is false, this rule will be ignored.
- requires_false: (Label) The label of a `cc_variable` that should be checked for falsiness
- before expanding this rule. If the variable is true, this rule will be ignored.
- requires_equal: (Label) The label of a `cc_variable` that should be checked for equality
- before expanding this rule. If the variable is not equal to
+ requires_none: (Label) The label of a `cc_variable` that should be checked for
+ non-existence before expanding this rule. If the variable is not None, this rule will be
+ ignored.
+ requires_true: (Label) The label of a `cc_variable` that should be checked for
+ truthiness before expanding this rule. If the variable is false, this rule will be
+ ignored.
+ requires_false: (Label) The label of a `cc_variable` that should be checked
+ for falsiness before expanding this rule. If the variable is true, this rule will be
+ ignored.
+ requires_equal: (Label) The label of a `cc_variable` that should be checked
+ for equality before expanding this rule. If the variable is not equal to
(requires_equal_value)[#cc_args-requires_equal_value], this rule will be ignored.
requires_equal_value: (str) The value to compare (requires_equal)[#cc_args-requires_equal]
against.
requires_any_of: (List[Label]) These arguments will be used
- in a tool invocation when at least one of the `cc_feature_constraint` entries in this
- list are satisfied. If omitted, this flag set will be enabled unconditionally.
+ in a tool invocation when at least one of the [cc_feature_constraint](#cc_feature_constraint)
+ entries in this list are satisfied. If omitted, this flag set will be enabled
+ unconditionally.
**kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
"""
return _cc_args(
diff --git a/cc/toolchains/args_list.bzl b/cc/toolchains/args_list.bzl
index 1f93a84..0747acb 100644
--- a/cc/toolchains/args_list.bzl
+++ b/cc/toolchains/args_list.bzl
@@ -26,7 +26,7 @@
implementation = _cc_args_list_impl,
doc = """An ordered list of cc_args.
- This is a convenience rule to allow you to group a set of multiple [cc_args](#cc_args) into a
+ This is a convenience rule to allow you to group a set of multiple `cc_args` into a
single list. This particularly useful for toolchain behaviors that require different flags for
different actions.
diff --git a/cc/toolchains/impl/documented_api.bzl b/cc/toolchains/impl/documented_api.bzl
index b2ca091..827d7fb 100644
--- a/cc/toolchains/impl/documented_api.bzl
+++ b/cc/toolchains/impl/documented_api.bzl
@@ -13,12 +13,33 @@
# limitations under the License.
"""This is a list of rules/macros that should be exported as documentation."""
+load("//cc/toolchains:actions.bzl", _cc_action_type = "cc_action_type", _cc_action_type_set = "cc_action_type_set")
load("//cc/toolchains:args.bzl", _cc_args = "cc_args")
load("//cc/toolchains:args_list.bzl", _cc_args_list = "cc_args_list")
load("//cc/toolchains:nested_args.bzl", _cc_nested_args = "cc_nested_args")
+load("//cc/toolchains:tool.bzl", _cc_tool = "cc_tool")
load("//cc/toolchains:tool_map.bzl", _cc_tool_map = "cc_tool_map")
+load("//cc/toolchains/impl:variables.bzl", _cc_variable = "cc_variable")
cc_tool_map = _cc_tool_map
+cc_tool = _cc_tool
cc_args = _cc_args
cc_nested_args = _cc_nested_args
cc_args_list = _cc_args_list
+cc_action_type = _cc_action_type
+cc_action_type_set = _cc_action_type_set
+cc_variable = _cc_variable
+
+# This list is used to automatically remap instances of `foo` to [`foo`](#foo)
+# links in the generated documentation so that maintainers don't need to manually
+# ensure every reference to a rule is properly linked.
+DOCUMENTED_TOOLCHAIN_RULES = [
+ "cc_tool_map",
+ "cc_tool",
+ "cc_args",
+ "cc_nested_args",
+ "cc_args_list",
+ "cc_action_type",
+ "cc_action_type_set",
+ "cc_variable",
+]
diff --git a/cc/toolchains/impl/markdown_helpers.bzl b/cc/toolchains/impl/markdown_helpers.bzl
new file mode 100644
index 0000000..1ae401f
--- /dev/null
+++ b/cc/toolchains/impl/markdown_helpers.bzl
@@ -0,0 +1,53 @@
+# 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.
+"""A few small helpers for working with Markdown."""
+
+def markdown_link(link_text, href):
+ """Creates a markdown link.
+
+ Args:
+ link_text: The text to display for the link.
+ href: The href for the link.
+
+ Returns:
+ A markdown link.
+ """
+ return "[" + link_text + "](" + href + ")"
+
+def xref_substitutions(match_text_patterns):
+ """Creates a dictionary of substitutions for use for linkification of text.
+
+ Example:
+ ```
+ # Produces a dictionary containing:
+ # {
+ # "foo": "[foo](http://foo.com)"
+ # "bar": "[bar](http://bar.com)"
+ # }
+ substitutions = xref_substitutions({
+ "foo": "http://foo.com",
+ "bar": "http://bar.com",
+ })
+ ```
+
+ Args:
+ match_text_patterns: A dictionary mapping string literals to the links they should point to.
+
+ Returns:
+ A dictionary of string literals mapped to their linkified substitutions.
+ """
+ return {
+ match_text: markdown_link(match_text, href)
+ for match_text, href in match_text_patterns.items()
+ }
diff --git a/cc/toolchains/impl/variables.bzl b/cc/toolchains/impl/variables.bzl
index c2820f3..aac945e 100644
--- a/cc/toolchains/impl/variables.bzl
+++ b/cc/toolchains/impl/variables.bzl
@@ -67,19 +67,32 @@
)
def cc_variable(name, type, **kwargs):
- """Defines a variable for both the specified variable, and all nested ones.
+ """Exposes a toolchain variable to use in toolchain argument expansions.
- Eg. cc_variable(
- name = "foo",
- type = types.list(types.struct(bar = types.string))
+ This internal rule exposes [toolchain variables](https://bazel.build/docs/cc-toolchain-config-reference#cctoolchainconfiginfo-build-variables)
+ that may be expanded in `cc_args` or `cc_nested_args`
+ rules. Because these varaibles merely expose variables inherrent to Bazel,
+ it's not possible to declare custom variables.
+
+ For a full list of available variables, see
+ [//cc/toolchains/varaibles:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD).
+
+ Example:
+ ```
+ load("//cc/toolchains/impl:variables.bzl", "cc_variable")
+
+ # Defines two targets, ":foo" and ":foo.bar"
+ cc_variable(
+ name = "foo",
+ type = types.list(types.struct(bar = types.string)),
)
-
- would define two targets, ":foo" and ":foo.bar"
+ ```
Args:
name: (str) The name of the outer variable, and the rule.
- type: The type of the variable, constructed using types above.
- **kwargs: kwargs to pass to _cc_variable.
+ type: The type of the variable, constructed using `types` factory in
+ [//cc/toolchains/impl:variables.bzl](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/impl/variables.bzl).
+ **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
"""
_cc_variable(name = name, type = json.encode(type), **kwargs)
diff --git a/cc/toolchains/nested_args.bzl b/cc/toolchains/nested_args.bzl
index 0f27a0f..d81dd99 100644
--- a/cc/toolchains/nested_args.bzl
+++ b/cc/toolchains/nested_args.bzl
@@ -56,19 +56,19 @@
requires_equal = None,
requires_equal_value = None,
**kwargs):
- """Nested arguments for use in more complex cc_args expansions.
+ """Nested arguments for use in more complex `cc_args` expansions.
- While this rule is very similar in shape to [cc_args](#cc_args), it is intended to be used as a
- dependency of [cc_args](#cc_args) to provide additional arguments that should be applied to the
- same actions as defined by the parent [cc_args](#cc_args) rule. The key motivation for this rule
+ While this rule is very similar in shape to `cc_args`, it is intended to be used as a
+ dependency of `cc_args` to provide additional arguments that should be applied to the
+ same actions as defined by the parent `cc_args` rule. The key motivation for this rule
is to allow for more complex variable-based argument expensions.
- Prefer expressing collections of arguments as [cc_args](#cc_args) and
- [cc_args_list](#cc_args_list) rules when possible.
+ Prefer expressing collections of arguments as `cc_args` and
+ `cc_args_list` rules when possible.
For living examples of how this rule is used, see the usages here:
- https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/runtime_library_search_directories/BUILD
- https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/libraries_to_link/BUILD
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/runtime_library_search_directories/BUILD
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/libraries_to_link/BUILD
Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to
use this rule.
@@ -80,27 +80,30 @@
data: (List[Label]) A list of runtime data dependencies that are required for these
arguments to work as intended.
format: (Dict[str, Label]) A mapping of format strings to the label of the corresponding
- `cc_variable` that the value should be pulled from. All instances of `{variable_name}`
- will be replaced with the expanded value of `variable_name` in this dictionary. The
- complete list of possible variables can be found in
- https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is
- not possible to declare custom variables--these are inherent to Bazel itself.
- iterate_over: (Label) The label of a `cc_variable` that should be iterated over. This is
- intended for use with built-in variables that are lists.
- nested: (List[Label]) A list of [cc_nested_args](#cc_nested_args) rules that should be
+ `cc_variable` that the value should be pulled from. All instances of
+ `{variable_name}` will be replaced with the expanded value of `variable_name` in this
+ dictionary. The complete list of possible variables can be found in
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD.
+ It is not possible to declare custom variables--these are inherent to Bazel itself.
+ iterate_over: (Label) The label of a `cc_variable` that should be iterated
+ over. This is intended for use with built-in variables that are lists.
+ nested: (List[Label]) A list of `cc_nested_args` rules that should be
expanded to command-line arguments when this rule is used. This is mutually exclusive
with [args](#cc_nested_args-args).
- requires_not_none: (Label) The label of a `cc_variable` that should be checked for
- existence before expanding this rule. If the variable is None, this rule will be
+ requires_not_none: (Label) The label of a `cc_variable` that should be checked
+ for existence before expanding this rule. If the variable is None, this rule will be
ignored.
- requires_none: (Label) The label of a `cc_variable` that should be checked for non-existence
- before expanding this rule. If the variable is not None, this rule will be ignored.
- requires_true: (Label) The label of a `cc_variable` that should be checked for truthiness
- before expanding this rule. If the variable is false, this rule will be ignored.
- requires_false: (Label) The label of a `cc_variable` that should be checked for falsiness
- before expanding this rule. If the variable is true, this rule will be ignored.
- requires_equal: (Label) The label of a `cc_variable` that should be checked for equality
- before expanding this rule. If the variable is not equal to
+ requires_none: (Label) The label of a `cc_variable` that should be checked for
+ non-existence before expanding this rule. If the variable is not None, this rule will be
+ ignored.
+ requires_true: (Label) The label of a `cc_variable` that should be checked for
+ truthiness before expanding this rule. If the variable is false, this rule will be
+ ignored.
+ requires_false: (Label) The label of a `cc_variable` that should be checked
+ for falsiness before expanding this rule. If the variable is true, this rule will be
+ ignored.
+ requires_equal: (Label) The label of a `cc_variable` that should be checked
+ for equality before expanding this rule. If the variable is not equal to
(requires_equal_value)[#cc_nested_args-requires_equal_value], this rule will be ignored.
requires_equal_value: (str) The value to compare
(requires_equal)[#cc_nested_args-requires_equal] against.
diff --git a/cc/toolchains/tool.bzl b/cc/toolchains/tool.bzl
index 159a9d6..0dc309d 100644
--- a/cc/toolchains/tool.bzl
+++ b/cc/toolchains/tool.bzl
@@ -66,13 +66,17 @@
cfg = "exec",
doc = """The underlying binary that this tool represents.
-Usually just a single prebuilt (eg. @sysroot//:bin/clang), but may be any
+Usually just a single prebuilt (eg. @toolchain//:bin/clang), but may be any
executable label.
""",
),
"data": attr.label_list(
allow_files = True,
- doc = "Additional files that are required for this tool to run.",
+ doc = """Additional files that are required for this tool to run.
+
+Frequently, clang and gcc require additional files to execute as they often shell out to
+other binaries (e.g. `cc1`).
+""",
),
"allowlist_include_directories": attr.label_list(
providers = [DirectoryInfo],
@@ -82,17 +86,34 @@
unless flags like `-nostdinc` are provided. Bazel checks that all included
headers are properly provided by a dependency or allowlisted through this
mechanism.
+
+As a rule of thumb, only use this if Bazel is complaining about absolute paths in your
+toolchain and you've ensured that the toolchain is compiling with the `-no-canonical-prefixes`
+and/or `-fno-canonical-system-headers` arguments.
+
+This can help work around errors like:
+`the source file 'main.c' includes the following non-builtin files with absolute paths
+(if these are builtin files, make sure these paths are in your toolchain)`.
""",
),
},
provides = [ToolInfo],
- doc = """Declares a tool that can be bound to action configs.
+ doc = """Declares a tool for use by toolchain actions.
-A tool is a binary with extra metadata for the action config rule to consume
-(eg. execution_requirements).
+`cc_tool` rules are used in a `cc_tool_map` rule to ensure all files and
+metadata required to run a tool are available when constructing a `cc_toolchain`.
+
+In general, include all files that are always required to run a tool (e.g. libexec/** and
+cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
+required when certain flags are passed to the tool, consider using a `cc_args` rule to
+bind the files to the flags that require them. This reduces the overhead required to properly
+enumerate a sandbox with all the files required to run a tool, and ensures that there isn't
+unintentional leakage across configurations and actions.
Example:
```
+load("//cc/toolchains:tool.bzl", "cc_tool")
+
cc_tool(
name = "clang_tool",
executable = "@llvm_toolchain//:bin/clang",
diff --git a/cc/toolchains/tool_map.bzl b/cc/toolchains/tool_map.bzl
index 62e94e6..b4f7e35 100644
--- a/cc/toolchains/tool_map.bzl
+++ b/cc/toolchains/tool_map.bzl
@@ -70,11 +70,12 @@
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
+ 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](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD)) 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
@@ -106,7 +107,8 @@
Args:
name: (str) The name of the target.
- tools: (Dict[target providing ActionTypeSetInfo, Executable target]) A mapping between `cc_action_type` targets
+ tools: (Dict[Label, Label]) A mapping between
+ `cc_action_type`/`cc_action_type_set` 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.
"""
diff --git a/cc/toolchains/toolchain_api.md b/cc/toolchains/toolchain_api.md
index 8d17b6e..013df8a 100644
--- a/cc/toolchains/toolchain_api.md
+++ b/cc/toolchains/toolchain_api.md
@@ -2,6 +2,82 @@
This is a list of rules/macros that should be exported as documentation.
+<a id="cc_action_type"></a>
+
+## cc_action_type
+
+<pre>
+cc_action_type(<a href="#cc_action_type-name">name</a>, <a href="#cc_action_type-action_name">action_name</a>)
+</pre>
+
+A type of action (eg. c_compile, assemble, strip).
+
+[`cc_action_type`](#cc_action_type) rules are used to associate arguments and tools together to
+perform a specific action. Bazel prescribes a set of known action types that are used to drive
+typical C/C++/ObjC actions like compiling, linking, and archiving. The set of well-known action
+types can be found in [@rules_cc//cc/toolchains/actions:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD).
+
+It's possible to create project-specific action types for use in toolchains. Be careful when
+doing this, because every toolchain that encounters the action will need to be configured to
+support the custom action type. If your project is a library, avoid creating new action types as
+it will reduce compatibility with existing toolchains and increase setup complexity for users.
+
+Example:
+```
+load("@rules_cc//cc:action_names.bzl", "ACTION_NAMES")
+load("@rules_cc//cc/toolchains:actions.bzl", "cc_action_type")
+
+cc_action_type(
+ name = "cpp_compile",
+ action_name = = ACTION_NAMES.cpp_compile,
+)
+```
+
+**ATTRIBUTES**
+
+
+| Name | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="cc_action_type-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="cc_action_type-action_name"></a>action_name | - | String | required | |
+
+
+<a id="cc_action_type_set"></a>
+
+## cc_action_type_set
+
+<pre>
+cc_action_type_set(<a href="#cc_action_type_set-name">name</a>, <a href="#cc_action_type_set-actions">actions</a>, <a href="#cc_action_type_set-allow_empty">allow_empty</a>)
+</pre>
+
+Represents a set of actions.
+
+This is a convenience rule to allow for more compact representation of a group of action types.
+Use this anywhere a [`cc_action_type`](#cc_action_type) is accepted.
+
+Example:
+```
+load("@rules_cc//cc/toolchains:actions.bzl", "cc_action_type_set")
+
+cc_action_type_set(
+ name = "link_executable_actions",
+ actions = [
+ "@rules_cc//cc/toolchains/actions:cpp_link_executable",
+ "@rules_cc//cc/toolchains/actions:lto_index_for_executable",
+ ],
+)
+```
+
+**ATTRIBUTES**
+
+
+| Name | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="cc_action_type_set-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="cc_action_type_set-actions"></a>actions | A list of cc_action_type or cc_action_type_set | <a href="https://bazel.build/concepts/labels">List of labels</a> | required | |
+| <a id="cc_action_type_set-allow_empty"></a>allow_empty | - | Boolean | optional | `False` |
+
+
<a id="cc_args_list"></a>
## cc_args_list
@@ -12,7 +88,7 @@
An ordered list of cc_args.
-This is a convenience rule to allow you to group a set of multiple [cc_args](#cc_args) into a
+This is a convenience rule to allow you to group a set of multiple [`cc_args`](#cc_args) into a
single list. This particularly useful for toolchain behaviors that require different flags for
different actions.
@@ -58,6 +134,50 @@
| <a id="cc_args_list-args"></a>args | (ordered) cc_args to include in this list. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
+<a id="cc_tool"></a>
+
+## cc_tool
+
+<pre>
+cc_tool(<a href="#cc_tool-name">name</a>, <a href="#cc_tool-src">src</a>, <a href="#cc_tool-data">data</a>, <a href="#cc_tool-allowlist_include_directories">allowlist_include_directories</a>)
+</pre>
+
+Declares a tool for use by toolchain actions.
+
+[`cc_tool`](#cc_tool) rules are used in a [`cc_tool_map`](#cc_tool_map) rule to ensure all files and
+metadata required to run a tool are available when constructing a `cc_toolchain`.
+
+In general, include all files that are always required to run a tool (e.g. libexec/** and
+cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
+required when certain flags are passed to the tool, consider using a [`cc_args`](#cc_args) rule to
+bind the files to the flags that require them. This reduces the overhead required to properly
+enumerate a sandbox with all the files required to run a tool, and ensures that there isn't
+unintentional leakage across configurations and actions.
+
+Example:
+```
+load("@rules_cc//cc/toolchains:tool.bzl", "cc_tool")
+
+cc_tool(
+ name = "clang_tool",
+ executable = "@llvm_toolchain//:bin/clang",
+ # Suppose clang needs libc to run.
+ data = ["@llvm_toolchain//:lib/x86_64-linux-gnu/libc.so.6"]
+ tags = ["requires-network"],
+)
+```
+
+**ATTRIBUTES**
+
+
+| Name | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="cc_tool-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | |
+| <a id="cc_tool-src"></a>src | The underlying binary that this tool represents.<br><br>Usually just a single prebuilt (eg. @toolchain//:bin/clang), but may be any executable label. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` |
+| <a id="cc_tool-data"></a>data | Additional files that are required for this tool to run.<br><br>Frequently, clang and gcc require additional files to execute as they often shell out to other binaries (e.g. `cc1`). | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
+| <a id="cc_tool-allowlist_include_directories"></a>allowlist_include_directories | Include paths implied by using this tool.<br><br>Compilers may include a set of built-in headers that are implicitly available unless flags like `-nostdinc` are provided. Bazel checks that all included headers are properly provided by a dependency or allowlisted through this mechanism.<br><br>As a rule of thumb, only use this if Bazel is complaining about absolute paths in your toolchain and you've ensured that the toolchain is compiling with the `-no-canonical-prefixes` and/or `-fno-canonical-system-headers` arguments.<br><br>This can help work around errors like: `the source file 'main.c' includes the following non-builtin files with absolute paths (if these are builtin files, make sure these paths are in your toolchain)`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
+
+
<a id="cc_args"></a>
## cc_args
@@ -72,13 +192,14 @@
This rule is the fundamental building building block for every toolchain tool invocation. Each
argument expressed in a toolchain tool invocation (e.g. `gcc`, `llvm-ar`) is declared in a
-`cc_args` rule that applies an ordered list of arguments to a set of toolchain actions.
-`cc_args` rules can be added unconditionally to a `cc_toolchain`, conditionally via `select()`
-statements, or dynamically via an intermediate `cc_feature`.
+[`cc_args`](#cc_args) rule that applies an ordered list of arguments to a set of toolchain
+actions. [`cc_args`](#cc_args) rules can be added unconditionally to a
+`cc_toolchain`, conditionally via `select()` statements, or dynamically via an
+intermediate `cc_feature`.
Conceptually, this is similar to the old `CFLAGS`, `CPPFLAGS`, etc. environment variables that
many build systems use to determine which flags to use for a given action. The significant
-difference is that `cc_args` rules are declared in a structured way that allows for
+difference is that [`cc_args`](#cc_args) rules are declared in a structured way that allows for
significantly more powerful and sharable toolchain configurations. Also, due to Bazel's more
granular action types, it's possible to bind flags to very specific actions (e.g. LTO indexing
for an executable vs a dynamic library) multiple different actions (e.g. C++ compile and link
@@ -90,7 +211,7 @@
# Basic usage: a trivial flag.
#
-# An example of expressing `-Werror` as a `cc_args` rule.
+# An example of expressing `-Werror` as a [`cc_args`](#cc_args) rule.
cc_args(
name = "warnings_as_errors",
actions = [
@@ -146,21 +267,21 @@
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="cc_args-name"></a>name | (str) The name of the target. | none |
-| <a id="cc_args-actions"></a>actions | (List[Label]) A list of labels of `cc_action_type` or `cc_action_type_set` rules that dictate which actions these arguments should be applied to. | `None` |
-| <a id="cc_args-allowlist_include_directories"></a>allowlist_include_directories | (List[Label]) A list of include paths that are implied by using this rule. These must point to a skylib [directory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_doc.md#directory) or [subdirectory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_subdirectory_doc.md#subdirectory) rule. Some flags (e.g. --sysroot) imply certain include paths are available despite not explicitly specifying a normal include path flag (`-I`, `-isystem`, etc.). Bazel checks that all included headers are properly provided by a dependency or allowlisted through this mechanism. | `None` |
+| <a id="cc_args-actions"></a>actions | (List[Label]) A list of labels of [`cc_action_type`](#cc_action_type) or [`cc_action_type_set`](#cc_action_type_set) rules that dictate which actions these arguments should be applied to. | `None` |
+| <a id="cc_args-allowlist_include_directories"></a>allowlist_include_directories | (List[Label]) A list of include paths that are implied by using this rule. These must point to a skylib [directory](https://github.com/bazelbuild/bazel-skylib/tree/main/doc/directory_doc.md#directory) or [subdirectory](https://github.com/bazelbuild/bazel-skylib/tree/main/doc/directory_subdirectory_doc.md#subdirectory) rule. Some flags (e.g. --sysroot) imply certain include paths are available despite not explicitly specifying a normal include path flag (`-I`, `-isystem`, etc.). Bazel checks that all included headers are properly provided by a dependency or allowlisted through this mechanism.<br><br>As a rule of thumb, only use this if Bazel is complaining about absolute paths in your toolchain and you've ensured that the toolchain is compiling with the `-no-canonical-prefixes` and/or `-fno-canonical-system-headers` arguments.<br><br>This can help work around errors like: `the source file 'main.c' includes the following non-builtin files with absolute paths (if these are builtin files, make sure these paths are in your toolchain)`. | `None` |
| <a id="cc_args-args"></a>args | (List[str]) The command-line arguments that are applied by using this rule. This is mutually exclusive with [nested](#cc_args-nested). | `None` |
| <a id="cc_args-data"></a>data | (List[Label]) A list of runtime data dependencies that are required for these arguments to work as intended. | `None` |
| <a id="cc_args-env"></a>env | (Dict[str, str]) Environment variables that should be set when the tool is invoked. | `None` |
-| <a id="cc_args-format"></a>format | (Dict[str, Label]) A mapping of format strings to the label of the corresponding `cc_variable` that the value should be pulled from. All instances of `{variable_name}` will be replaced with the expanded value of `variable_name` in this dictionary. The complete list of possible variables can be found in https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is not possible to declare custom variables--these are inherent to Bazel itself. | `{}` |
-| <a id="cc_args-iterate_over"></a>iterate_over | (Label) The label of a `cc_variable` that should be iterated over. This is intended for use with built-in variables that are lists. | `None` |
-| <a id="cc_args-nested"></a>nested | (List[Label]) A list of [cc_nested_args](#cc_nested_args) rules that should be expanded to command-line arguments when this rule is used. This is mutually exclusive with [args](#cc_args-args). | `None` |
-| <a id="cc_args-requires_not_none"></a>requires_not_none | (Label) The label of a `cc_variable` that should be checked for existence before expanding this rule. If the variable is None, this rule will be ignored. | `None` |
-| <a id="cc_args-requires_none"></a>requires_none | (Label) The label of a `cc_variable` that should be checked for non-existence before expanding this rule. If the variable is not None, this rule will be ignored. | `None` |
-| <a id="cc_args-requires_true"></a>requires_true | (Label) The label of a `cc_variable` that should be checked for truthiness before expanding this rule. If the variable is false, this rule will be ignored. | `None` |
-| <a id="cc_args-requires_false"></a>requires_false | (Label) The label of a `cc_variable` that should be checked for falsiness before expanding this rule. If the variable is true, this rule will be ignored. | `None` |
-| <a id="cc_args-requires_equal"></a>requires_equal | (Label) The label of a `cc_variable` that should be checked for equality before expanding this rule. If the variable is not equal to (requires_equal_value)[#cc_args-requires_equal_value], this rule will be ignored. | `None` |
+| <a id="cc_args-format"></a>format | (Dict[str, Label]) A mapping of format strings to the label of the corresponding [`cc_variable`](#cc_variable) that the value should be pulled from. All instances of `{variable_name}` will be replaced with the expanded value of `variable_name` in this dictionary. The complete list of possible variables can be found in https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD. It is not possible to declare custom variables--these are inherent to Bazel itself. | `{}` |
+| <a id="cc_args-iterate_over"></a>iterate_over | (Label) The label of a [`cc_variable`](#cc_variable) that should be iterated over. This is intended for use with built-in variables that are lists. | `None` |
+| <a id="cc_args-nested"></a>nested | (List[Label]) A list of [`cc_nested_args`](#cc_nested_args) rules that should be expanded to command-line arguments when this rule is used. This is mutually exclusive with [args](#cc_args-args). | `None` |
+| <a id="cc_args-requires_not_none"></a>requires_not_none | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for existence before expanding this rule. If the variable is None, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_none"></a>requires_none | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for non-existence before expanding this rule. If the variable is not None, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_true"></a>requires_true | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for truthiness before expanding this rule. If the variable is false, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_false"></a>requires_false | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for falsiness before expanding this rule. If the variable is true, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_equal"></a>requires_equal | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for equality before expanding this rule. If the variable is not equal to (requires_equal_value)[#cc_args-requires_equal_value], this rule will be ignored. | `None` |
| <a id="cc_args-requires_equal_value"></a>requires_equal_value | (str) The value to compare (requires_equal)[#cc_args-requires_equal] against. | `None` |
-| <a id="cc_args-requires_any_of"></a>requires_any_of | (List[Label]) These arguments will be used in a tool invocation when at least one of the `cc_feature_constraint` entries in this list are satisfied. If omitted, this flag set will be enabled unconditionally. | `None` |
+| <a id="cc_args-requires_any_of"></a>requires_any_of | (List[Label]) These arguments will be used in a tool invocation when at least one of the [cc_feature_constraint](#cc_feature_constraint) entries in this list are satisfied. If omitted, this flag set will be enabled unconditionally. | `None` |
| <a id="cc_args-kwargs"></a>kwargs | [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule. | none |
@@ -173,19 +294,19 @@
<a href="#cc_nested_args-requires_true">requires_true</a>, <a href="#cc_nested_args-requires_false">requires_false</a>, <a href="#cc_nested_args-requires_equal">requires_equal</a>, <a href="#cc_nested_args-requires_equal_value">requires_equal_value</a>, <a href="#cc_nested_args-kwargs">kwargs</a>)
</pre>
-Nested arguments for use in more complex cc_args expansions.
+Nested arguments for use in more complex [`cc_args`](#cc_args) expansions.
-While this rule is very similar in shape to [cc_args](#cc_args), it is intended to be used as a
-dependency of [cc_args](#cc_args) to provide additional arguments that should be applied to the
-same actions as defined by the parent [cc_args](#cc_args) rule. The key motivation for this rule
+While this rule is very similar in shape to [`cc_args`](#cc_args), it is intended to be used as a
+dependency of [`cc_args`](#cc_args) to provide additional arguments that should be applied to the
+same actions as defined by the parent [`cc_args`](#cc_args) rule. The key motivation for this rule
is to allow for more complex variable-based argument expensions.
-Prefer expressing collections of arguments as [cc_args](#cc_args) and
-[cc_args_list](#cc_args_list) rules when possible.
+Prefer expressing collections of arguments as [`cc_args`](#cc_args) and
+[`cc_args_list`](#cc_args_list) rules when possible.
For living examples of how this rule is used, see the usages here:
- https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/runtime_library_search_directories/BUILD
- https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/libraries_to_link/BUILD
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/runtime_library_search_directories/BUILD
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/libraries_to_link/BUILD
Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to
use this rule.
@@ -199,14 +320,14 @@
| <a id="cc_nested_args-name"></a>name | (str) The name of the target. | none |
| <a id="cc_nested_args-args"></a>args | (List[str]) The command-line arguments that are applied by using this rule. This is mutually exclusive with [nested](#cc_nested_args-nested). | `None` |
| <a id="cc_nested_args-data"></a>data | (List[Label]) A list of runtime data dependencies that are required for these arguments to work as intended. | `None` |
-| <a id="cc_nested_args-format"></a>format | (Dict[str, Label]) A mapping of format strings to the label of the corresponding `cc_variable` that the value should be pulled from. All instances of `{variable_name}` will be replaced with the expanded value of `variable_name` in this dictionary. The complete list of possible variables can be found in https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is not possible to declare custom variables--these are inherent to Bazel itself. | `{}` |
-| <a id="cc_nested_args-iterate_over"></a>iterate_over | (Label) The label of a `cc_variable` that should be iterated over. This is intended for use with built-in variables that are lists. | `None` |
-| <a id="cc_nested_args-nested"></a>nested | (List[Label]) A list of [cc_nested_args](#cc_nested_args) rules that should be expanded to command-line arguments when this rule is used. This is mutually exclusive with [args](#cc_nested_args-args). | `None` |
-| <a id="cc_nested_args-requires_not_none"></a>requires_not_none | (Label) The label of a `cc_variable` that should be checked for existence before expanding this rule. If the variable is None, this rule will be ignored. | `None` |
-| <a id="cc_nested_args-requires_none"></a>requires_none | (Label) The label of a `cc_variable` that should be checked for non-existence before expanding this rule. If the variable is not None, this rule will be ignored. | `None` |
-| <a id="cc_nested_args-requires_true"></a>requires_true | (Label) The label of a `cc_variable` that should be checked for truthiness before expanding this rule. If the variable is false, this rule will be ignored. | `None` |
-| <a id="cc_nested_args-requires_false"></a>requires_false | (Label) The label of a `cc_variable` that should be checked for falsiness before expanding this rule. If the variable is true, this rule will be ignored. | `None` |
-| <a id="cc_nested_args-requires_equal"></a>requires_equal | (Label) The label of a `cc_variable` that should be checked for equality before expanding this rule. If the variable is not equal to (requires_equal_value)[#cc_nested_args-requires_equal_value], this rule will be ignored. | `None` |
+| <a id="cc_nested_args-format"></a>format | (Dict[str, Label]) A mapping of format strings to the label of the corresponding [`cc_variable`](#cc_variable) that the value should be pulled from. All instances of `{variable_name}` will be replaced with the expanded value of `variable_name` in this dictionary. The complete list of possible variables can be found in https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD. It is not possible to declare custom variables--these are inherent to Bazel itself. | `{}` |
+| <a id="cc_nested_args-iterate_over"></a>iterate_over | (Label) The label of a [`cc_variable`](#cc_variable) that should be iterated over. This is intended for use with built-in variables that are lists. | `None` |
+| <a id="cc_nested_args-nested"></a>nested | (List[Label]) A list of [`cc_nested_args`](#cc_nested_args) rules that should be expanded to command-line arguments when this rule is used. This is mutually exclusive with [args](#cc_nested_args-args). | `None` |
+| <a id="cc_nested_args-requires_not_none"></a>requires_not_none | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for existence before expanding this rule. If the variable is None, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_none"></a>requires_none | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for non-existence before expanding this rule. If the variable is not None, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_true"></a>requires_true | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for truthiness before expanding this rule. If the variable is false, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_false"></a>requires_false | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for falsiness before expanding this rule. If the variable is true, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_equal"></a>requires_equal | (Label) The label of a [`cc_variable`](#cc_variable) that should be checked for equality before expanding this rule. If the variable is not equal to (requires_equal_value)[#cc_nested_args-requires_equal_value], this rule will be ignored. | `None` |
| <a id="cc_nested_args-requires_equal_value"></a>requires_equal_value | (str) The value to compare (requires_equal)[#cc_nested_args-requires_equal] against. | `None` |
| <a id="cc_nested_args-kwargs"></a>kwargs | [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule. | none |
@@ -221,11 +342,12 @@
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,
-@rules_cc//cc/toolchains/actions:cpp_compile_actions) to
+A [`cc_tool_map`](#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,
+[@rules_cc//cc/toolchains/actions:cpp_compile_actions](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD)) 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
@@ -262,7 +384,47 @@
| 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-tools"></a>tools | (Dict[Label, Label]) A mapping between [`cc_action_type`](#cc_action_type)/[`cc_action_type_set`](#cc_action_type_set) targets and the [`cc_tool`](#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 |
+<a id="cc_variable"></a>
+
+## cc_variable
+
+<pre>
+cc_variable(<a href="#cc_variable-name">name</a>, <a href="#cc_variable-type">type</a>, <a href="#cc_variable-kwargs">kwargs</a>)
+</pre>
+
+Exposes a toolchain variable to use in toolchain argument expansions.
+
+This internal rule exposes [toolchain variables](https://bazel.build/docs/cc-toolchain-config-reference#cctoolchainconfiginfo-build-variables)
+that may be expanded in [`cc_args`](#cc_args) or [`cc_nested_args`](#cc_nested_args)
+rules. Because these varaibles merely expose variables inherrent to Bazel,
+it's not possible to declare custom variables.
+
+For a full list of available variables, see
+[@rules_cc//cc/toolchains/varaibles:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD).
+
+Example:
+```
+load("@rules_cc//cc/toolchains/impl:variables.bzl", "cc_variable")
+
+# Defines two targets, ":foo" and ":foo.bar"
+cc_variable(
+ name = "foo",
+ type = types.list(types.struct(bar = types.string)),
+)
+```
+
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="cc_variable-name"></a>name | (str) The name of the outer variable, and the rule. | none |
+| <a id="cc_variable-type"></a>type | The type of the variable, constructed using `types` factory in [@rules_cc//cc/toolchains/impl:variables.bzl](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/impl/variables.bzl). | none |
+| <a id="cc_variable-kwargs"></a>kwargs | [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule. | none |
+
+
