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

Add documentation for `cc_toolchain` 

BEGIN_PUBLIC

Add documentation for `cc_toolchain`

Updates and includes documentation for the `cc_toolchain` rule, fixing some minor typos along the way.

END_PUBLIC

PiperOrigin-RevId: 684051451
Change-Id: I5bb62f22b3fb68e2d233fb85255d1a86bb45a47d
This commit is contained in:
Googler 2024-10-09 08:43:20 -07:00 committed by Copybara-Service
parent 56f4a8bfa1
commit 324612d107
5 changed files with 175 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
cc/toolchains/args.bzl
View File

@ -135,7 +135,7 @@ def cc_args(
requires_equal_value = None, requires_equal_value = None,
requires_any_of = None, requires_any_of = None,
**kwargs): **kwargs):
"""Action-specific arguments for use with a cc_toolchain. """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

2
cc/toolchains/feature_set.bzl
View File

@ -45,7 +45,7 @@ cc_feature_set = rule(
doc = """Defines a set of features. doc = """Defines a set of features.
This may be used by both `cc_feature` and `cc_args` rules, and is effectively a way to express This may be used by both `cc_feature` and `cc_args` rules, and is effectively a way to express
a logical `AND` operation across multiple requred features. a logical `AND` operation across multiple required features.
Example: Example:
``` ```

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

@ -24,6 +24,7 @@ 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.bzl", _cc_tool = "cc_tool")
load("//cc/toolchains:tool_capability.bzl", _cc_tool_capability = "cc_tool_capability") load("//cc/toolchains:tool_capability.bzl", _cc_tool_capability = "cc_tool_capability")
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:toolchain.bzl", _cc_toolchain = "cc_toolchain")
load("//cc/toolchains/impl:external_feature.bzl", _cc_external_feature = "cc_external_feature") load("//cc/toolchains/impl:external_feature.bzl", _cc_external_feature = "cc_external_feature")
load("//cc/toolchains/impl:variables.bzl", _cc_variable = "cc_variable") load("//cc/toolchains/impl:variables.bzl", _cc_variable = "cc_variable")
@ -41,6 +42,7 @@ cc_feature_constraint = _cc_feature_constraint
cc_feature_set = _cc_feature_set cc_feature_set = _cc_feature_set
cc_mutually_exclusive_category = _cc_mutually_exclusive_category cc_mutually_exclusive_category = _cc_mutually_exclusive_category
cc_external_feature = _cc_external_feature cc_external_feature = _cc_external_feature
cc_toolchain = _cc_toolchain
# This list is used to automatically remap instances of `foo` to [`foo`](#foo) # 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 # links in the generated documentation so that maintainers don't need to manually
@ -60,4 +62,5 @@ DOCUMENTED_TOOLCHAIN_RULES = [
"cc_feature_set", "cc_feature_set",
"cc_mutually_exclusive_category", "cc_mutually_exclusive_category",
"cc_external_feature", "cc_external_feature",
"cc_toolchain",
] ]

140
cc/toolchains/toolchain.bzl
View File

@ -13,7 +13,7 @@
# limitations under the License. # limitations under the License.
"""Implementation of the cc_toolchain rule.""" """Implementation of the cc_toolchain rule."""
load("//cc:defs.bzl", _cc_toolchain = "cc_toolchain") load("//cc/toolchains:cc_toolchain.bzl", _cc_toolchain = "cc_toolchain")
load( load(
"//cc/toolchains/impl:toolchain_config.bzl", "//cc/toolchains/impl:toolchain_config.bzl",
"cc_legacy_file_group", "cc_legacy_file_group",
@ -53,21 +53,49 @@ _LEGACY_FILE_GROUPS = {
} }
def cc_toolchain( def cc_toolchain(
*,
name, name,
dynamic_runtime_lib = None, tool_map,
libc_top = None, args,
module_map = None, known_features,
output_licenses = [], enabled_features,
static_runtime_lib = None, libc_top,
supports_header_parsing = False, module_map,
supports_param_files = True, dynamic_runtime_lib,
target_compatible_with = None, static_runtime_lib,
exec_compatible_with = None, supports_header_parsing,
compatible_with = None, supports_param_files,
tags = [],
visibility = None,
**kwargs): **kwargs):
"""A macro that invokes native.cc_toolchain under the hood. """A C/C++ toolchain configuration.
This rule is the core declaration of a complete C/C++ toolchain. It collects together
tool configuration, which arguments to pass to each tool, and how
[features](https://bazel.build/docs/cc-toolchain-config-reference#features)
(dynamically-toggleable argument lists) interact.
A single `cc_toolchain` may support a wide variety of platforms and configurations through
[configurable build attributes](https://bazel.build/docs/configurable-attributes) and
[feature relationships](https://bazel.build/docs/cc-toolchain-config-reference#feature-relationships).
Arguments are applied to commandline invocation of tools in the following order:
1. Arguments in the order they are listed in listed in [`args`](#cc_toolchain-args).
2. Any legacy/built-in features that have been implicitly or explicitly enabled.
3. User-defined features in the order they are listed in
[`known_features`](#cc_toolchain-known_features).
When building a `cc_toolchain` configuration, it's important to understand how `select`
statements will be evaluated:
* Most attributes and dependencies of a `cc_toolchain` are evaluated under the target platform.
This means that a `@platforms//os:linux` constraint will be satisfied when
the final compiled binaries are intended to be ran from a Linux machine. This means that
a different operating system (e.g. Windows) may be cross-compiling to linux.
* The `cc_tool_map` rule performs a transition to the exec platform when evaluating tools. This
means that a if a `@platforms//os:linux` constraint is satisfied in a
`select` statement on a `cc_tool`, that means the machine that will run the tool is a Linux
machine. This means that a Linux machine may be cross-compiling to a different OS
like Windows.
Generated rules: Generated rules:
{name}: A `cc_toolchain` for this toolchain. {name}: A `cc_toolchain` for this toolchain.
@ -78,38 +106,65 @@ def cc_toolchain(
normally enumerated as part of the `cc_toolchain` rule. normally enumerated as part of the `cc_toolchain` rule.
Args: Args:
name: str: The name of the label for the toolchain. name: (str) The name of the label for the toolchain.
dynamic_runtime_lib: See cc_toolchain.dynamic_runtime_lib tool_map: (Label) The `cc_tool_map` that specifies the tools to use for various toolchain
libc_top: See cc_toolchain.libc_top actions.
module_map: See cc_toolchain.module_map args: (List[Label]) A list of `cc_args` and `cc_arg_list` to apply across this toolchain.
output_licenses: See cc_toolchain.output_licenses known_features: (List[Label]) A list of `cc_feature` rules that this toolchain supports.
static_runtime_lib: See cc_toolchain.static_runtime_lib Whether or not these
supports_header_parsing: See cc_toolchain.supports_header_parsing [features](https://bazel.build/docs/cc-toolchain-config-reference#features)
supports_param_files: See cc_toolchain.supports_param_files are enabled may change over the course of a build. See the documentation for
target_compatible_with: target_compatible_with to apply to all generated `cc_feature` for more information.
rules enabled_features: (List[Label]) A list of `cc_feature` rules whose initial state should
exec_compatible_with: exec_compatible_with to apply to all generated be `enabled`. Note that it is still possible for these
rules [features](https://bazel.build/docs/cc-toolchain-config-reference#features)
compatible_with: compatible_with to apply to all generated rules to be disabled over the course of a build through other mechanisms. See the
tags: Tags to apply to all generated rules documentation for `cc_feature` for more information.
visibility: Visibility of toolchain rule libc_top: (Label) A collection of artifacts for libc passed as inputs to compile/linking
**kwargs: Args to be passed through to cc_toolchain_config. actions. See
[`cc_toolchain.libc_top`](https://bazel.build/reference/be/c-cpp#cc_toolchain.libc_top)
for more information.
module_map: (Label) Module map artifact to be used for modular builds. See
[`cc_toolchain.module_map`](https://bazel.build/reference/be/c-cpp#cc_toolchain.module_map)
for more information.
dynamic_runtime_lib: (Label) Dynamic library to link when the `static_link_cpp_runtimes`
and `dynamic_linking_mode`
[features](https://bazel.build/docs/cc-toolchain-config-reference#features) are both
enabled. See
[`cc_toolchain.dynamic_runtime_lib`](https://bazel.build/reference/be/c-cpp#cc_toolchain.dynamic_runtime_lib)
for more information.
static_runtime_lib: (Label) Static library to link when the `static_link_cpp_runtimes`
and `static_linking_mode`
[features](https://bazel.build/docs/cc-toolchain-config-reference#features) are both
enabled. See
[`cc_toolchain.dynamic_runtime_lib`](https://bazel.build/reference/be/c-cpp#cc_toolchain.dynamic_runtime_lib)
for more information.
supports_header_parsing: (bool) Whether or not this toolchain supports header parsing
actions. See
[`cc_toolchain.supports_header_parsing`](https://bazel.build/reference/be/c-cpp#cc_toolchain.supports_header_parsing)
for more information.
supports_param_files: (bool) Whether or not this toolchain supports linking via param files.
See
[`cc_toolchain.supports_param_files`](https://bazel.build/reference/be/c-cpp#cc_toolchain.supports_param_files)
for more information.
**kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes)
that should be applied to all rules created by this macro.
""" """
all_kwargs = { cc_toolchain_visibility = kwargs.pop("visibility", default = None)
"compatible_with": compatible_with,
"exec_compatible_with": exec_compatible_with,
"tags": tags,
"target_compatible_with": target_compatible_with,
}
for group in _LEGACY_FILE_GROUPS: for group in _LEGACY_FILE_GROUPS:
if group in kwargs: if group in kwargs:
fail("Don't use legacy file groups such as %s. Instead, associate files with tools, actions, and args." % group) fail("Don't use legacy file groups such as %s. Instead, associate files with `cc_tool` or `cc_args` rules." % group)
config_name = "_{}_config".format(name) config_name = "_{}_config".format(name)
cc_toolchain_config( cc_toolchain_config(
name = config_name, name = config_name,
tool_map = tool_map,
args = args,
known_features = known_features,
enabled_features = enabled_features,
visibility = ["//visibility:private"], visibility = ["//visibility:private"],
**(all_kwargs | kwargs) **kwargs
) )
# Provides ar_files, compiler_files, linker_files, ... # Provides ar_files, compiler_files, linker_files, ...
@ -121,13 +176,10 @@ def cc_toolchain(
config = config_name, config = config_name,
actions = actions, actions = actions,
visibility = ["//visibility:private"], visibility = ["//visibility:private"],
**all_kwargs **kwargs
) )
legacy_file_groups[group] = group_name legacy_file_groups[group] = group_name
if visibility != None:
all_kwargs["visibility"] = visibility
_cc_toolchain( _cc_toolchain(
name = name, name = name,
toolchain_config = config_name, toolchain_config = config_name,
@ -135,11 +187,11 @@ def cc_toolchain(
dynamic_runtime_lib = dynamic_runtime_lib, dynamic_runtime_lib = dynamic_runtime_lib,
libc_top = libc_top, libc_top = libc_top,
module_map = module_map, module_map = module_map,
output_licenses = output_licenses,
static_runtime_lib = static_runtime_lib, static_runtime_lib = static_runtime_lib,
supports_header_parsing = supports_header_parsing, supports_header_parsing = supports_header_parsing,
supports_param_files = supports_param_files, supports_param_files = supports_param_files,
# This is required for Bazel versions <= 7.x.x. It is ignored in later versions. # This is required for Bazel versions <= 7.x.x. It is ignored in later versions.
exec_transition_for_inputs = False, exec_transition_for_inputs = False,
**(all_kwargs | legacy_file_groups) visibility = cc_toolchain_visibility,
**(kwargs | legacy_file_groups)
) )

79
docs/toolchain_api.md
View File

@ -200,7 +200,7 @@ A feature may be enabled or disabled through the following mechanisms:
Note that a feature may alternate between enabled and disabled dynamically over the course of a Note that a feature may alternate between enabled and disabled dynamically over the course of a
build. Because of their toggleable nature, it's generally best to avoid adding arguments to a build. Because of their toggleable nature, it's generally best to avoid adding arguments to a
`cc_toolchain` as a [`cc_feature`](#cc_feature) unless strictly necessary. Instead, prefer to express arguments [`cc_toolchain`](#cc_toolchain) as a [`cc_feature`](#cc_feature) unless strictly necessary. Instead, prefer to express arguments
via [`cc_toolchain.args`](#cc_toolchain-args) whenever possible. via [`cc_toolchain.args`](#cc_toolchain-args) whenever possible.
You should use a [`cc_feature`](#cc_feature) when any of the following apply: You should use a [`cc_feature`](#cc_feature) when any of the following apply:
@ -301,7 +301,7 @@ cc_feature_set(<a href="#cc_feature_set-name">name</a>, <a href="#cc_feature_set
Defines a set of features. Defines a set of features.
This may be used by both [`cc_feature`](#cc_feature) and [`cc_args`](#cc_args) rules, and is effectively a way to express This may be used by both [`cc_feature`](#cc_feature) and [`cc_args`](#cc_args) rules, and is effectively a way to express
a logical `AND` operation across multiple requred features. a logical `AND` operation across multiple required features.
Example: Example:
``` ```
@ -386,7 +386,7 @@ cc_tool(<a href="#cc_tool-name">name</a>, <a href="#cc_tool-src">src</a>, <a hre
Declares a tool for use by toolchain actions. 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 [`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`. metadata required to run a tool are available when constructing a [`cc_toolchain`](#cc_toolchain).
In general, include all files that are always required to run a tool (e.g. libexec/** and 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 cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
@ -473,13 +473,13 @@ cc_args(<a href="#cc_args-name">name</a>, <a href="#cc_args-actions">actions</a>
<a href="#cc_args-requires_equal_value">requires_equal_value</a>, <a href="#cc_args-requires_any_of">requires_any_of</a>, <a href="#cc_args-kwargs">kwargs</a>) <a href="#cc_args-requires_equal_value">requires_equal_value</a>, <a href="#cc_args-requires_any_of">requires_any_of</a>, <a href="#cc_args-kwargs">kwargs</a>)
</pre> </pre>
Action-specific arguments for use with a cc_toolchain. Action-specific arguments for use with a [`cc_toolchain`](#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`](#cc_args) rule that applies an ordered list of arguments to a set of toolchain [`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 actions. [`cc_args`](#cc_args) rules can be added unconditionally to a
`cc_toolchain`, conditionally via `select()` statements, or dynamically via an [`cc_toolchain`](#cc_toolchain), conditionally via `select()` statements, or dynamically via an
intermediate [`cc_feature`](#cc_feature). intermediate [`cc_feature`](#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
@ -673,6 +673,75 @@ Note:
| <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_toolchain"></a>
## cc_toolchain
<pre>
cc_toolchain(<a href="#cc_toolchain-name">name</a>, <a href="#cc_toolchain-tool_map">tool_map</a>, <a href="#cc_toolchain-args">args</a>, <a href="#cc_toolchain-known_features">known_features</a>, <a href="#cc_toolchain-enabled_features">enabled_features</a>, <a href="#cc_toolchain-libc_top">libc_top</a>, <a href="#cc_toolchain-module_map">module_map</a>,
<a href="#cc_toolchain-dynamic_runtime_lib">dynamic_runtime_lib</a>, <a href="#cc_toolchain-static_runtime_lib">static_runtime_lib</a>, <a href="#cc_toolchain-supports_header_parsing">supports_header_parsing</a>, <a href="#cc_toolchain-supports_param_files">supports_param_files</a>,
<a href="#cc_toolchain-kwargs">kwargs</a>)
</pre>
A C/C++ toolchain configuration.
This rule is the core declaration of a complete C/C++ toolchain. It collects together
tool configuration, which arguments to pass to each tool, and how
[features](https://bazel.build/docs/cc-toolchain-config-reference#features)
(dynamically-toggleable argument lists) interact.
A single [`cc_toolchain`](#cc_toolchain) may support a wide variety of platforms and configurations through
[configurable build attributes](https://bazel.build/docs/configurable-attributes) and
[feature relationships](https://bazel.build/docs/cc-toolchain-config-reference#feature-relationships).
Arguments are applied to commandline invocation of tools in the following order:
1. Arguments in the order they are listed in listed in [`args`](#cc_toolchain-args).
2. Any legacy/built-in features that have been implicitly or explicitly enabled.
3. User-defined features in the order they are listed in
[`known_features`](#cc_toolchain-known_features).
When building a [`cc_toolchain`](#cc_toolchain) configuration, it's important to understand how `select`
statements will be evaluated:
* Most attributes and dependencies of a [`cc_toolchain`](#cc_toolchain) are evaluated under the target platform.
This means that a `//third_party/bazel_platforms/os:linux` constraint will be satisfied when
the final compiled binaries are intended to be ran from a Linux machine. This means that
a different operating system (e.g. Windows) may be cross-compiling to linux.
* The [`cc_tool_map`](#cc_tool_map) rule performs a transition to the exec platform when evaluating tools. This
means that a if a `//third_party/bazel_platforms/os:linux` constraint is satisfied in a
`select` statement on a [`cc_tool`](#cc_tool), that means the machine that will run the tool is a Linux
machine. This means that a Linux machine may be cross-compiling to a different OS
like Windows.
Generated rules:
{name}: A [`cc_toolchain`](#cc_toolchain) for this toolchain.
_{name}_config: A `cc_toolchain_config` for this toolchain.
_{name}_*_files: Generated rules that group together files for
"ar_files", "as_files", "compiler_files", "coverage_files",
"dwp_files", "linker_files", "objcopy_files", and "strip_files"
normally enumerated as part of the [`cc_toolchain`](#cc_toolchain) rule.
**PARAMETERS**
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="cc_toolchain-name"></a>name | (str) The name of the label for the toolchain. | none |
| <a id="cc_toolchain-tool_map"></a>tool_map | (Label) The [`cc_tool_map`](#cc_tool_map) that specifies the tools to use for various toolchain actions. | none |
| <a id="cc_toolchain-args"></a>args | (List[Label]) A list of [`cc_args`](#cc_args) and `cc_arg_list` to apply across this toolchain. | none |
| <a id="cc_toolchain-known_features"></a>known_features | (List[Label]) A list of [`cc_feature`](#cc_feature) rules that this toolchain supports. Whether or not these [features](https://bazel.build/docs/cc-toolchain-config-reference#features) are enabled may change over the course of a build. See the documentation for [`cc_feature`](#cc_feature) for more information. | none |
| <a id="cc_toolchain-enabled_features"></a>enabled_features | (List[Label]) A list of [`cc_feature`](#cc_feature) rules whose initial state should be `enabled`. Note that it is still possible for these [features](https://bazel.build/docs/cc-toolchain-config-reference#features) to be disabled over the course of a build through other mechanisms. See the documentation for [`cc_feature`](#cc_feature) for more information. | none |
| <a id="cc_toolchain-libc_top"></a>libc_top | (Label) A collection of artifacts for libc passed as inputs to compile/linking actions. See [`cc_toolchain.libc_top`](https://bazel.build/reference/be/c-cpp#cc_toolchain.libc_top) for more information. | none |
| <a id="cc_toolchain-module_map"></a>module_map | (Label) Module map artifact to be used for modular builds. See [`cc_toolchain.module_map`](https://bazel.build/reference/be/c-cpp#cc_toolchain.module_map) for more information. | none |
| <a id="cc_toolchain-dynamic_runtime_lib"></a>dynamic_runtime_lib | (Label) Dynamic library to link when the `static_link_cpp_runtimes` and `dynamic_linking_mode` [features](https://bazel.build/docs/cc-toolchain-config-reference#features) are both enabled. See [`cc_toolchain.dynamic_runtime_lib`](https://bazel.build/reference/be/c-cpp#cc_toolchain.dynamic_runtime_lib) for more information. | none |
| <a id="cc_toolchain-static_runtime_lib"></a>static_runtime_lib | (Label) Static library to link when the `static_link_cpp_runtimes` and `static_linking_mode` [features](https://bazel.build/docs/cc-toolchain-config-reference#features) are both enabled. See [`cc_toolchain.dynamic_runtime_lib`](https://bazel.build/reference/be/c-cpp#cc_toolchain.dynamic_runtime_lib) for more information. | none |
| <a id="cc_toolchain-supports_header_parsing"></a>supports_header_parsing | (bool) Whether or not this toolchain supports header parsing actions. See [`cc_toolchain.supports_header_parsing`](https://bazel.build/reference/be/c-cpp#cc_toolchain.supports_header_parsing) for more information. | none |
| <a id="cc_toolchain-supports_param_files"></a>supports_param_files | (bool) Whether or not this toolchain supports linking via param files. See [`cc_toolchain.supports_param_files`](https://bazel.build/reference/be/c-cpp#cc_toolchain.supports_param_files) for more information. | none |
| <a id="cc_toolchain-kwargs"></a>kwargs | [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to all rules created by this macro. | none |
<a id="cc_variable"></a> <a id="cc_variable"></a>
## cc_variable ## cc_variable