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
diff --git a/cc/toolchains/args.bzl b/cc/toolchains/args.bzl
index bdcf7ce..78d551c 100644
--- a/cc/toolchains/args.bzl
+++ b/cc/toolchains/args.bzl
@@ -135,7 +135,7 @@
requires_equal_value = None,
requires_any_of = None,
**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
argument expressed in a toolchain tool invocation (e.g. `gcc`, `llvm-ar`) is declared in a
diff --git a/cc/toolchains/feature_set.bzl b/cc/toolchains/feature_set.bzl
index 5fcdae4..c4a0756 100644
--- a/cc/toolchains/feature_set.bzl
+++ b/cc/toolchains/feature_set.bzl
@@ -45,7 +45,7 @@
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
-a logical `AND` operation across multiple requred features.
+a logical `AND` operation across multiple required features.
Example:
```
diff --git a/cc/toolchains/impl/documented_api.bzl b/cc/toolchains/impl/documented_api.bzl
index f1f634e..e6cfa99 100644
--- a/cc/toolchains/impl/documented_api.bzl
+++ b/cc/toolchains/impl/documented_api.bzl
@@ -24,6 +24,7 @@
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_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:variables.bzl", _cc_variable = "cc_variable")
@@ -41,6 +42,7 @@
cc_feature_set = _cc_feature_set
cc_mutually_exclusive_category = _cc_mutually_exclusive_category
cc_external_feature = _cc_external_feature
+cc_toolchain = _cc_toolchain
# 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
@@ -60,4 +62,5 @@
"cc_feature_set",
"cc_mutually_exclusive_category",
"cc_external_feature",
+ "cc_toolchain",
]
diff --git a/cc/toolchains/toolchain.bzl b/cc/toolchains/toolchain.bzl
index ca4b639..e381e22 100644
--- a/cc/toolchains/toolchain.bzl
+++ b/cc/toolchains/toolchain.bzl
@@ -13,7 +13,7 @@
# limitations under the License.
"""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(
"//cc/toolchains/impl:toolchain_config.bzl",
"cc_legacy_file_group",
@@ -53,21 +53,49 @@
}
def cc_toolchain(
+ *,
name,
- dynamic_runtime_lib = None,
- libc_top = None,
- module_map = None,
- output_licenses = [],
- static_runtime_lib = None,
- supports_header_parsing = False,
- supports_param_files = True,
- target_compatible_with = None,
- exec_compatible_with = None,
- compatible_with = None,
- tags = [],
- visibility = None,
+ tool_map,
+ args,
+ known_features,
+ enabled_features,
+ libc_top,
+ module_map,
+ dynamic_runtime_lib,
+ static_runtime_lib,
+ supports_header_parsing,
+ supports_param_files,
**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:
{name}: A `cc_toolchain` for this toolchain.
@@ -78,38 +106,65 @@
normally enumerated as part of the `cc_toolchain` rule.
Args:
- name: str: The name of the label for the toolchain.
- dynamic_runtime_lib: See cc_toolchain.dynamic_runtime_lib
- libc_top: See cc_toolchain.libc_top
- module_map: See cc_toolchain.module_map
- output_licenses: See cc_toolchain.output_licenses
- static_runtime_lib: See cc_toolchain.static_runtime_lib
- supports_header_parsing: See cc_toolchain.supports_header_parsing
- supports_param_files: See cc_toolchain.supports_param_files
- target_compatible_with: target_compatible_with to apply to all generated
- rules
- exec_compatible_with: exec_compatible_with to apply to all generated
- rules
- compatible_with: compatible_with to apply to all generated rules
- tags: Tags to apply to all generated rules
- visibility: Visibility of toolchain rule
- **kwargs: Args to be passed through to cc_toolchain_config.
+ name: (str) The name of the label for the toolchain.
+ tool_map: (Label) The `cc_tool_map` that specifies the tools to use for various toolchain
+ actions.
+ args: (List[Label]) A list of `cc_args` and `cc_arg_list` to apply across this toolchain.
+ known_features: (List[Label]) A list of `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` for more information.
+ enabled_features: (List[Label]) A list of `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` for more information.
+ 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.
+ 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 = {
- "compatible_with": compatible_with,
- "exec_compatible_with": exec_compatible_with,
- "tags": tags,
- "target_compatible_with": target_compatible_with,
- }
+ cc_toolchain_visibility = kwargs.pop("visibility", default = None)
+
for group in _LEGACY_FILE_GROUPS:
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)
cc_toolchain_config(
name = config_name,
+ tool_map = tool_map,
+ args = args,
+ known_features = known_features,
+ enabled_features = enabled_features,
visibility = ["//visibility:private"],
- **(all_kwargs | kwargs)
+ **kwargs
)
# Provides ar_files, compiler_files, linker_files, ...
@@ -121,13 +176,10 @@
config = config_name,
actions = actions,
visibility = ["//visibility:private"],
- **all_kwargs
+ **kwargs
)
legacy_file_groups[group] = group_name
- if visibility != None:
- all_kwargs["visibility"] = visibility
-
_cc_toolchain(
name = name,
toolchain_config = config_name,
@@ -135,11 +187,11 @@
dynamic_runtime_lib = dynamic_runtime_lib,
libc_top = libc_top,
module_map = module_map,
- output_licenses = output_licenses,
static_runtime_lib = static_runtime_lib,
supports_header_parsing = supports_header_parsing,
supports_param_files = supports_param_files,
# This is required for Bazel versions <= 7.x.x. It is ignored in later versions.
exec_transition_for_inputs = False,
- **(all_kwargs | legacy_file_groups)
+ visibility = cc_toolchain_visibility,
+ **(kwargs | legacy_file_groups)
)
diff --git a/docs/toolchain_api.md b/docs/toolchain_api.md
index d5b3be1..999b095 100644
--- a/docs/toolchain_api.md
+++ b/docs/toolchain_api.md
@@ -200,7 +200,7 @@
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
-`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.
You should use a [`cc_feature`](#cc_feature) when any of the following apply:
@@ -301,7 +301,7 @@
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
-a logical `AND` operation across multiple requred features.
+a logical `AND` operation across multiple required features.
Example:
```
@@ -386,7 +386,7 @@
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`.
+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
cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
@@ -473,13 +473,13 @@
<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>
-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
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
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).
Conceptually, this is similar to the old `CFLAGS`, `CPPFLAGS`, etc. environment variables that
@@ -673,6 +673,75 @@
| <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>
## cc_variable
