22title : ' C++ Toolchain Configuration'
33---
44
5- ## Overview { :# overview }
5+ ## Overview
66
77To invoke the compiler with the right options, Bazel needs some knowledge about
88the compiler internals, such as include directories and important flags.
@@ -35,7 +35,7 @@ that provides the `CcToolchainConfigInfo` and you need to point the
3535You can create the ` CcToolchainConfigInfo ` by calling
3636[ ` cc_common.create_cc_toolchain_config_info() ` ] ( /rules/lib/toplevel/cc_common#create_cc_toolchain_config_info ) .
3737You can find Starlark constructors for all structs you'll need in the process in
38- [ ` @rules_cc//cc:cc_toolchain_config_lib.bzl ` ] ( https://github.com/bazelbuild/rules_cc/blob/master/cc/cc_toolchain_config_lib.bzl ) { : . external } .
38+ [ ` @rules_cc//cc:cc_toolchain_config_lib.bzl ` ] ( https://github.com/bazelbuild/rules_cc/blob/master/cc/cc_toolchain_config_lib.bzl ) .
3939
4040When a C++ target enters the analysis phase, Bazel selects the appropriate
4141` cc_toolchain ` target based on the ` BUILD ` file, and obtains the
@@ -59,7 +59,7 @@ The artifacts to be shipped to the sandbox are declared in the `cc_toolchain`
5959target. For example, with the ` cc_toolchain.linker_files ` attribute you can
6060specify the linker binary and toolchain libraries to ship into the sandbox.
6161
62- ## Toolchain selection { :# toolchain - selection }
62+ ## Toolchain selection
6363
6464The toolchain selection logic operates as follows:
6565
@@ -93,7 +93,7 @@ fully fledged C++ features in Bazel without modifying the
9393Bazel binary. C++ rules support multiple unique actions documented in detail
9494[ in the Bazel source code] ( https://source.bazel.build/bazel/+/4f547a7ea86df80e4c76145ffdbb0c8b75ba3afa:tools/build_defs/cc/action_names.bzl ) .
9595
96- ## Features { :# features }
96+ ## Features
9797
9898A feature is an entity that requires command-line flags, actions,
9999constraints on the execution environment, or dependency alterations. A feature
@@ -121,7 +121,7 @@ A feature is enabled in one of the following ways:
121121Features can have interdependencies, depend on command line flags, ` BUILD ` file
122122settings, and other variables.
123123
124- ### Feature relationships { :# feature - relationships }
124+ ### Feature relationships
125125
126126Dependencies are typically managed directly with Bazel, which simply enforces
127127the requirements and manages conflicts intrinsic to the nature of the features
@@ -195,7 +195,7 @@ support and expansion. These are:
195195 </tr >
196196</table >
197197
198- ## Actions { :# actions }
198+ ## Actions
199199
200200Actions provide the flexibility to modify the circumstances under
201201which an action executes without assuming how the action will be run. An
@@ -216,7 +216,7 @@ that implements an action (such as `CppCompileAction`). In particular, the
216216"assembler actions" and "compiler actions" in the table below are
217217` CppCompileAction ` , while the link actions are ` CppLinkAction ` .
218218
219- ### Assembler actions { :# assembler - actions }
219+ ### Assembler actions
220220
221221<table >
222222 <col width = " 300" >
@@ -241,7 +241,7 @@ that implements an action (such as `CppCompileAction`). In particular, the
241241 </tr >
242242</table >
243243
244- ### Compiler actions { :# compiler - actions }
244+ ### Compiler actions
245245
246246<table >
247247 <col width = " 300" >
@@ -280,7 +280,7 @@ that implements an action (such as `CppCompileAction`). In particular, the
280280 </tr >
281281</table >
282282
283- ### Link actions { :# link - actions }
283+ ### Link actions
284284
285285<table >
286286 <col width = " 300" >
@@ -311,7 +311,7 @@ that implements an action (such as `CppCompileAction`). In particular, the
311311 </tr >
312312</table >
313313
314- ### AR actions { :# ar - actions }
314+ ### AR actions
315315
316316AR actions assemble object files into archive libraries (` .a ` files) via ` ar `
317317and encode some semantics into the name.
@@ -333,7 +333,7 @@ and encode some semantics into the name.
333333 </tr >
334334</table >
335335
336- ### LTO actions { :# lto - actions }
336+ ### LTO actions
337337
338338<table >
339339 <col width = " 300" >
@@ -358,7 +358,7 @@ and encode some semantics into the name.
358358 </tr >
359359</table >
360360
361- ## Using action_config { :# using - action - config }
361+ ## Using action_config
362362
363363The ` action_config ` is a Starlark struct that describes a Bazel
364364action by specifying the tool (binary) to invoke during the action and sets of
@@ -424,7 +424,7 @@ within the same toolchain. This prevents ambiguity in tool paths
424424and enforces the intention behind ` action_config ` - that an action's properties
425425are clearly described in a single place in the toolchain.
426426
427- ### Using tool constructor { :# using - tool - constructor }
427+ ### Using tool constructor
428428
429429An` action_config ` can specify a set of tools via its ` tools ` parameter.
430430The ` tool() ` constructor takes in the following parameters:
@@ -461,7 +461,7 @@ with a `with_feature` set matching the feature configuration is found
461461for more information). You should end your tool lists with a default
462462tool that corresponds to an empty feature configuration.
463463
464- ### Example usage { :# example - usage }
464+ ### Example usage
465465
466466Features and actions can be used together to implement Bazel actions
467467with diverse cross-platform semantics. For example, debug symbol generation on
@@ -553,7 +553,7 @@ follows:
553553 ),
554554 ]
555555
556- ### Flag groups { :# flag - groups }
556+ ### Flag groups
557557
558558` CcToolchainConfigInfo ` allows you to bundle flags into groups that serve a
559559specific purpose. You can specify a flag within using pre-defined variables
@@ -622,7 +622,7 @@ example:
622622 ] ,
623623 )
624624
625- ### Conditional expansion { :# conditional - expansion }
625+ ### Conditional expansion
626626
627627Flag groups support conditional expansion based on the presence of a particular
628628variable or its field using the ` expand_if_available ` , ` expand_if_not_available ` ,
@@ -654,12 +654,12 @@ Note: The `--whole_archive` and `--no_whole_archive` options are added to
654654the build command only when a currently iterated library has an
655655` is_whole_archive ` field.
656656
657- ## CcToolchainConfigInfo reference { :# cctoolchainconfiginfo - reference }
657+ ## CcToolchainConfigInfo reference
658658
659659This section provides a reference of build variables, features, and other
660660information required to successfully configure C++ rules.
661661
662- ### CcToolchainConfigInfo build variables { :# cctoolchainconfiginfo - build - variables }
662+ ### CcToolchainConfigInfo build variables
663663
664664The following is a reference of ` CcToolchainConfigInfo ` build variables.
665665
@@ -988,7 +988,7 @@ Note: The **Action** column indicates the relevant action type, if applicable.
988988 </tr >
989989</table >
990990
991- ### Well-known features { :# wellknown - features }
991+ ### Well-known features
992992
993993The following is a reference of features and their activation
994994conditions.
@@ -1092,7 +1092,7 @@ conditions.
10921092 </tr >
10931093</table >
10941094
1095- #### Legacy features patching logic { :# legacy - features - patching - logic }
1095+ #### Legacy features patching logic
10961096
10971097<p >
10981098 Bazel applies the following changes to the toolchain's features for backwards
@@ -1142,7 +1142,7 @@ conditions.
11421142</p >
11431143
11441144This is a long list of features. The plan is to get rid of them once
1145- [ Crosstool in Starlark] ( https://github.com/bazelbuild/bazel/issues/5380 ) { : . external } is
1145+ [ Crosstool in Starlark] ( https://github.com/bazelbuild/bazel/issues/5380 ) is
11461146done. For the curious reader see the implementation in
11471147[ CppActionConfigs] ( https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/rules/cpp/CppActionConfigs.java?q=cppactionconfigs&ss=bazel ) ,
11481148and for production toolchains consider adding ` no_legacy_features ` to make
0 commit comments