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

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
This commit is contained in:
Googler 2024-09-30 09:14:24 -07:00 committed by Copybara-Service
parent 9cb80cfc32
commit b06d2f7d53
11 changed files with 437 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
cc/toolchains/BUILD
View File

@ -16,6 +16,8 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
load("@bazel_skylib//rules:diff_test.bzl", "diff_test") load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@bazel_skylib//rules:expand_template.bzl", "expand_template") load("@bazel_skylib//rules:expand_template.bzl", "expand_template")
load("@stardoc//stardoc:stardoc.bzl", "stardoc") 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( bzl_library(
name = "toolchain_rules", name = "toolchain_rules",
@ -48,13 +50,22 @@ stardoc(
deps = [":toolchain_rules"], deps = [":toolchain_rules"],
) )
# In GitHub, we prefer to clarify all the labels that come from rules_cc.
expand_template( expand_template(
name = "toolchain_api_md", name = "toolchain_api_md",
out = "generated_toolchain_api.md", out = "generated_toolchain_api.md",
# Dictionary order 100% matters here!
# buildifier: disable=unsorted-dict-items
substitutions = { 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", template = ":raw_generated_toolchain_api.md",
) )

26
cc/toolchains/actions.bzl
View File

@ -37,14 +37,26 @@ cc_action_type = rule(
}, },
doc = """A type of action (eg. c_compile, assemble, strip). 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( cc_action_type(
name = "cpp_compile", name = "cpp_compile",
action_name = = ACTION_NAMES.cpp_compile, action_name = = ACTION_NAMES.cpp_compile,
) )
```
""", """,
provides = [ActionTypeInfo, ActionTypeSetInfo], provides = [ActionTypeInfo, ActionTypeSetInfo],
) )
@ -60,15 +72,21 @@ def _cc_action_type_set_impl(ctx):
cc_action_type_set = rule( cc_action_type_set = rule(
doc = """Represents a set of actions. 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: Example:
```
load("//cc/toolchains:actions.bzl", "cc_action_type_set")
cc_action_type_set( cc_action_type_set(
name = "link_executable_actions", name = "link_executable_actions",
actions = [ actions = [
":cpp_link_executable", "//cc/toolchains/actions:cpp_link_executable",
":lto_index_for_executable", "//cc/toolchains/actions:lto_index_for_executable",
], ],
) )
```
""", """,
implementation = _cc_action_type_set_impl, implementation = _cc_action_type_set_impl,
attrs = { attrs = {

64
cc/toolchains/args.bzl
View File

@ -139,9 +139,10 @@ def cc_args(
This rule is the fundamental building building block for every toolchain tool invocation. Each 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 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` rule that applies an ordered list of arguments to a set of toolchain
`cc_args` rules can be added unconditionally to a `cc_toolchain`, conditionally via `select()` actions. `cc_args` rules can be added unconditionally to a
statements, or dynamically via an intermediate `cc_feature`. `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 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 many build systems use to determine which flags to use for a given action. The significant
@ -208,49 +209,62 @@ def cc_args(
Args: Args:
name: (str) The name of the target. name: (str) The name of the target.
actions: (List[Label]) A list of labels of `cc_action_type` or `cc_action_type_set` rules actions: (List[Label]) A list of labels of `cc_action_type` or
that dictate which actions these arguments should be applied to. `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 allowlist_include_directories: (List[Label]) A list of include paths that are implied by
using this rule. These must point to a skylib using this rule. These must point to a skylib
[directory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_doc.md#directory) [directory](https://github.com/bazelbuild/bazel-skylib/tree/main/doc/directory_doc.md#directory)
or [subdirectory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_subdirectory_doc.md#subdirectory) rule. 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 Some flags (e.g. --sysroot) imply certain include paths are available despite
not explicitly specifying a normal include path flag (`-I`, `-isystem`, etc.). not explicitly specifying a normal include path flag (`-I`, `-isystem`, etc.).
Bazel checks that all included headers are properly provided by a dependency or Bazel checks that all included headers are properly provided by a dependency or
allowlisted through this mechanism. 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 args: (List[str]) The command-line arguments that are applied by using this rule. This is
mutually exclusive with [nested](#cc_args-nested). mutually exclusive with [nested](#cc_args-nested).
data: (List[Label]) A list of runtime data dependencies that are required for these data: (List[Label]) A list of runtime data dependencies that are required for these
arguments to work as intended. arguments to work as intended.
env: (Dict[str, str]) Environment variables that should be set when the tool is invoked. 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 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}` `cc_variable` that the value should be pulled from. All instances of
will be replaced with the expanded value of `variable_name` in this dictionary. The `{variable_name}` will be replaced with the expanded value of `variable_name` in this
complete list of possible variables can be found in 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 https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD.
not possible to declare custom variables--these are inherent to Bazel itself. 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 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. 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 expanded to command-line arguments when this rule is used. This is mutually exclusive
with [args](#cc_args-args). with [args](#cc_args-args).
requires_not_none: (Label) The label of a `cc_variable` that should be checked for requires_not_none: (Label) The label of a `cc_variable` that should be checked
existence before expanding this rule. If the variable is None, this rule will be for existence before expanding this rule. If the variable is None, this rule will be
ignored. ignored.
requires_none: (Label) The label of a `cc_variable` that should be checked for non-existence requires_none: (Label) The label of a `cc_variable` that should be checked for
before expanding this rule. If the variable is not None, this rule will be ignored. non-existence before expanding this rule. If the variable is not None, this rule will be
requires_true: (Label) The label of a `cc_variable` that should be checked for truthiness ignored.
before expanding this rule. If the variable is false, this rule will be ignored. requires_true: (Label) The label of a `cc_variable` that should be checked for
requires_false: (Label) The label of a `cc_variable` that should be checked for falsiness truthiness before expanding this rule. If the variable is false, this rule will be
before expanding this rule. If the variable is true, this rule will be ignored. ignored.
requires_equal: (Label) The label of a `cc_variable` that should be checked for equality requires_false: (Label) The label of a `cc_variable` that should be checked
before expanding this rule. If the variable is not equal to 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)[#cc_args-requires_equal_value], this rule will be ignored.
requires_equal_value: (str) The value to compare (requires_equal)[#cc_args-requires_equal] requires_equal_value: (str) The value to compare (requires_equal)[#cc_args-requires_equal]
against. against.
requires_any_of: (List[Label]) These arguments will be used 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 in a tool invocation when at least one of the [cc_feature_constraint](#cc_feature_constraint)
list are satisfied. If omitted, this flag set will be enabled unconditionally. 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. **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
""" """
return _cc_args( return _cc_args(

2
cc/toolchains/args_list.bzl
View File

@ -26,7 +26,7 @@ cc_args_list = rule(
implementation = _cc_args_list_impl, implementation = _cc_args_list_impl,
doc = """An ordered list of cc_args. 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 single list. This particularly useful for toolchain behaviors that require different flags for
different actions. different actions.

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

@ -13,12 +13,33 @@
# limitations under the License. # limitations under the License.
"""This is a list of rules/macros that should be exported as documentation.""" """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.bzl", _cc_args = "cc_args")
load("//cc/toolchains:args_list.bzl", _cc_args_list = "cc_args_list") 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: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: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_map = _cc_tool_map
cc_tool = _cc_tool
cc_args = _cc_args cc_args = _cc_args
cc_nested_args = _cc_nested_args cc_nested_args = _cc_nested_args
cc_args_list = _cc_args_list 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",
]

53
cc/toolchains/impl/markdown_helpers.bzl Normal file
View File

@ -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()
}

27
cc/toolchains/impl/variables.bzl
View File

@ -67,19 +67,32 @@ _cc_variable = rule(
) )
def cc_variable(name, type, **kwargs): 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( 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", name = "foo",
type = types.list(types.struct(bar = types.string)) type = types.list(types.struct(bar = types.string)),
) )
```
would define two targets, ":foo" and ":foo.bar"
Args: Args:
name: (str) The name of the outer variable, and the rule. name: (str) The name of the outer variable, and the rule.
type: The type of the variable, constructed using types above. type: The type of the variable, constructed using `types` factory in
**kwargs: kwargs to pass to _cc_variable. [//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) _cc_variable(name = name, type = json.encode(type), **kwargs)

55
cc/toolchains/nested_args.bzl
View File

@ -56,19 +56,19 @@ def cc_nested_args(
requires_equal = None, requires_equal = None,
requires_equal_value = None, requires_equal_value = None,
**kwargs): **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 While this rule is very similar in shape to `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 dependency of `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 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. is to allow for more complex variable-based argument expensions.
Prefer expressing collections of arguments as [cc_args](#cc_args) and Prefer expressing collections of arguments as `cc_args` and
[cc_args_list](#cc_args_list) rules when possible. `cc_args_list` rules when possible.
For living examples of how this rule is used, see the usages here: 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/tree/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/libraries_to_link/BUILD
Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to
use this rule. use this rule.
@ -80,27 +80,30 @@ def cc_nested_args(
data: (List[Label]) A list of runtime data dependencies that are required for these data: (List[Label]) A list of runtime data dependencies that are required for these
arguments to work as intended. arguments to work as intended.
format: (Dict[str, Label]) A mapping of format strings to the label of the corresponding 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}` `cc_variable` that the value should be pulled from. All instances of
will be replaced with the expanded value of `variable_name` in this dictionary. The `{variable_name}` will be replaced with the expanded value of `variable_name` in this
complete list of possible variables can be found in 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 https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD.
not possible to declare custom variables--these are inherent to Bazel itself. 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 iterate_over: (Label) The label of a `cc_variable` that should be iterated
intended for use with built-in variables that are lists. 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 expanded to command-line arguments when this rule is used. This is mutually exclusive
with [args](#cc_nested_args-args). with [args](#cc_nested_args-args).
requires_not_none: (Label) The label of a `cc_variable` that should be checked for requires_not_none: (Label) The label of a `cc_variable` that should be checked
existence before expanding this rule. If the variable is None, this rule will be for existence before expanding this rule. If the variable is None, this rule will be
ignored. ignored.
requires_none: (Label) The label of a `cc_variable` that should be checked for non-existence requires_none: (Label) The label of a `cc_variable` that should be checked for
before expanding this rule. If the variable is not None, this rule will be ignored. non-existence before expanding this rule. If the variable is not None, this rule will be
requires_true: (Label) The label of a `cc_variable` that should be checked for truthiness ignored.
before expanding this rule. If the variable is false, this rule will be ignored. requires_true: (Label) The label of a `cc_variable` that should be checked for
requires_false: (Label) The label of a `cc_variable` that should be checked for falsiness truthiness before expanding this rule. If the variable is false, this rule will be
before expanding this rule. If the variable is true, this rule will be ignored. ignored.
requires_equal: (Label) The label of a `cc_variable` that should be checked for equality requires_false: (Label) The label of a `cc_variable` that should be checked
before expanding this rule. If the variable is not equal to 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)[#cc_nested_args-requires_equal_value], this rule will be ignored.
requires_equal_value: (str) The value to compare requires_equal_value: (str) The value to compare
(requires_equal)[#cc_nested_args-requires_equal] against. (requires_equal)[#cc_nested_args-requires_equal] against.

31
cc/toolchains/tool.bzl
View File

@ -66,13 +66,17 @@ cc_tool = rule(
cfg = "exec", cfg = "exec",
doc = """The underlying binary that this tool represents. 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. executable label.
""", """,
), ),
"data": attr.label_list( "data": attr.label_list(
allow_files = True, 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( "allowlist_include_directories": attr.label_list(
providers = [DirectoryInfo], providers = [DirectoryInfo],
@ -82,17 +86,34 @@ Compilers may include a set of built-in headers that are implicitly available
unless flags like `-nostdinc` are provided. Bazel checks that all included unless flags like `-nostdinc` are provided. Bazel checks that all included
headers are properly provided by a dependency or allowlisted through this headers are properly provided by a dependency or allowlisted through this
mechanism. 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], 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 `cc_tool` rules are used in a `cc_tool_map` rule to ensure all files and
(eg. execution_requirements). 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: Example:
``` ```
load("//cc/toolchains:tool.bzl", "cc_tool")
cc_tool( cc_tool(
name = "clang_tool", name = "clang_tool",
executable = "@llvm_toolchain//:bin/clang", executable = "@llvm_toolchain//:bin/clang",

14
cc/toolchains/tool_map.bzl
View File

@ -70,11 +70,12 @@ The tool may be a `cc_tool` or other executable rule.
def cc_tool_map(name, tools, **kwargs): def cc_tool_map(name, tools, **kwargs):
"""A toolchain configuration rule that maps toolchain actions to 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 A `cc_tool_map` aggregates all the tools that may be used for a given toolchain
their corresponding actions. Conceptually, this is similar to the `CXX=/path/to/clang++` and maps them to their corresponding actions. Conceptually, this is similar to the
environment variables that most build systems use to determine which tools to use for a given `CXX=/path/to/clang++` environment variables that most build systems use to determine which
action. To simplify usage, some actions have been grouped together (for example, tools to use for a given action. To simplify usage, some actions have been grouped together (for
//cc/toolchains/actions:cpp_compile_actions) to 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". 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 In Bazel, there is a little more granularity to the mapping, so the mapping doesn't follow the
@ -106,7 +107,8 @@ def cc_tool_map(name, tools, **kwargs):
Args: Args:
name: (str) The name of the target. 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. 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. **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
""" """

240
cc/toolchains/toolchain_api.md
View File

@ -2,6 +2,82 @@
This is a list of rules/macros that should be exported as documentation. 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> <a id="cc_args_list"></a>
## cc_args_list ## cc_args_list
@ -12,7 +88,7 @@ cc_args_list(<a href="#cc_args_list-name">name</a>, <a href="#cc_args_list-args"
An ordered list of cc_args. 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 single list. This particularly useful for toolchain behaviors that require different flags for
different actions. different actions.
@ -58,6 +134,50 @@ cc_args_list(
| <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_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> <a id="cc_args"></a>
## cc_args ## cc_args
@ -72,13 +192,14 @@ Action-specific arguments for use with a cc_toolchain.
This rule is the fundamental building building block for every toolchain tool invocation. Each 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 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`](#cc_args) rule that applies an ordered list of arguments to a set of toolchain
`cc_args` rules can be added unconditionally to a `cc_toolchain`, conditionally via `select()` actions. [`cc_args`](#cc_args) rules can be added unconditionally to a
statements, or dynamically via an intermediate `cc_feature`. `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 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 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 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 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 for an executable vs a dynamic library) multiple different actions (e.g. C++ compile and link
@ -90,7 +211,7 @@ load("@rules_cc//cc/toolchains:args.bzl", "cc_args")
# Basic usage: a trivial flag. # 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( cc_args(
name = "warnings_as_errors", name = "warnings_as_errors",
actions = [ actions = [
@ -146,21 +267,21 @@ For more extensive examples, see the usages here:
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="cc_args-name"></a>name | (str) The name of the target. | none | | <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-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/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-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-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-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-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-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` that should be iterated over. This is intended for use with built-in variables that are lists. | `None` | | <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-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_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` 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_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` 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_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` 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_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` 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"></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_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 | | <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 @@ cc_nested_args(<a href="#cc_nested_args-name">name</a>, <a href="#cc_nested_args
<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>) <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> </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 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 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 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. is to allow for more complex variable-based argument expensions.
Prefer expressing collections of arguments as [cc_args](#cc_args) and Prefer expressing collections of arguments as [`cc_args`](#cc_args) and
[cc_args_list](#cc_args_list) rules when possible. [`cc_args_list`](#cc_args_list) rules when possible.
For living examples of how this rule is used, see the usages here: 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/tree/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/libraries_to_link/BUILD
Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to
use this rule. use this rule.
@ -199,14 +320,14 @@ use this rule.
| <a id="cc_nested_args-name"></a>name | (str) The name of the target. | none | | <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-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-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-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` that should be iterated over. This is intended for use with built-in variables that are lists. | `None` | | <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-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_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` 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_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` 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_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` 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_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` 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"></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-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 | | <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 @@ cc_tool_map(<a href="#cc_tool_map-name">name</a>, <a href="#cc_tool_map-tools">t
A toolchain configuration rule that maps toolchain actions to 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 A [`cc_tool_map`](#cc_tool_map) aggregates all the tools that may be used for a given toolchain
their corresponding actions. Conceptually, this is similar to the `CXX=/path/to/clang++` and maps them to their corresponding actions. Conceptually, this is similar to the
environment variables that most build systems use to determine which tools to use for a given `CXX=/path/to/clang++` environment variables that most build systems use to determine which
action. To simplify usage, some actions have been grouped together (for example, tools to use for a given action. To simplify usage, some actions have been grouped together (for
@rules_cc//cc/toolchains/actions:cpp_compile_actions) to 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". 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 In Bazel, there is a little more granularity to the mapping, so the mapping doesn't follow the
@ -262,7 +384,47 @@ Note:
| Name | Description | Default Value | | Name | Description | Default Value |
| :------------- | :------------- | :------------- | | :------------- | :------------- | :------------- |
| <a id="cc_tool_map-name"></a>name | (str) The name of the target. | none | | <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_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 |