1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2 3This is a list of rules/macros that should be exported as documentation. 4 5<a id="cc_action_type"></a> 6 7## cc_action_type 8 9<pre> 10cc_action_type(<a href="#cc_action_type-name">name</a>, <a href="#cc_action_type-action_name">action_name</a>) 11</pre> 12 13A type of action (eg. c_compile, assemble, strip). 14 15[`cc_action_type`](#cc_action_type) rules are used to associate arguments and tools together to 16perform a specific action. Bazel prescribes a set of known action types that are used to drive 17typical C/C++/ObjC actions like compiling, linking, and archiving. The set of well-known action 18types can be found in [@rules_cc//cc/toolchains/actions:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD). 19 20It's possible to create project-specific action types for use in toolchains. Be careful when 21doing this, because every toolchain that encounters the action will need to be configured to 22support the custom action type. If your project is a library, avoid creating new action types as 23it will reduce compatibility with existing toolchains and increase setup complexity for users. 24 25Example: 26``` 27load("@rules_cc//cc:action_names.bzl", "ACTION_NAMES") 28load("@rules_cc//cc/toolchains:actions.bzl", "cc_action_type") 29 30cc_action_type( 31 name = "cpp_compile", 32 action_name = = ACTION_NAMES.cpp_compile, 33) 34``` 35 36**ATTRIBUTES** 37 38 39| Name | Description | Type | Mandatory | Default | 40| :------------- | :------------- | :------------- | :------------- | :------------- | 41| <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 | | 42| <a id="cc_action_type-action_name"></a>action_name | - | String | required | | 43 44 45<a id="cc_action_type_set"></a> 46 47## cc_action_type_set 48 49<pre> 50cc_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>) 51</pre> 52 53Represents a set of actions. 54 55This is a convenience rule to allow for more compact representation of a group of action types. 56Use this anywhere a [`cc_action_type`](#cc_action_type) is accepted. 57 58Example: 59``` 60load("@rules_cc//cc/toolchains:actions.bzl", "cc_action_type_set") 61 62cc_action_type_set( 63 name = "link_executable_actions", 64 actions = [ 65 "@rules_cc//cc/toolchains/actions:cpp_link_executable", 66 "@rules_cc//cc/toolchains/actions:lto_index_for_executable", 67 ], 68) 69``` 70 71**ATTRIBUTES** 72 73 74| Name | Description | Type | Mandatory | Default | 75| :------------- | :------------- | :------------- | :------------- | :------------- | 76| <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 | | 77| <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 | | 78| <a id="cc_action_type_set-allow_empty"></a>allow_empty | - | Boolean | optional | `False` | 79 80 81<a id="cc_args_list"></a> 82 83## cc_args_list 84 85<pre> 86cc_args_list(<a href="#cc_args_list-name">name</a>, <a href="#cc_args_list-args">args</a>) 87</pre> 88 89An ordered list of cc_args. 90 91This is a convenience rule to allow you to group a set of multiple [`cc_args`](#cc_args) into a 92single list. This particularly useful for toolchain behaviors that require different flags for 93different actions. 94 95Note: The order of the arguments in `args` is preserved to support order-sensitive flags. 96 97Example usage: 98``` 99load("@rules_cc//cc/toolchains:cc_args.bzl", "cc_args") 100load("@rules_cc//cc/toolchains:args_list.bzl", "cc_args_list") 101 102cc_args( 103 name = "gc_sections", 104 actions = [ 105 "@rules_cc//cc/toolchains/actions:link_actions", 106 ], 107 args = ["-Wl,--gc-sections"], 108) 109 110cc_args( 111 name = "function_sections", 112 actions = [ 113 "@rules_cc//cc/toolchains/actions:compile_actions", 114 "@rules_cc//cc/toolchains/actions:link_actions", 115 ], 116 args = ["-ffunction-sections"], 117) 118 119cc_args_list( 120 name = "gc_functions", 121 args = [ 122 ":function_sections", 123 ":gc_sections", 124 ], 125) 126``` 127 128**ATTRIBUTES** 129 130 131| Name | Description | Type | Mandatory | Default | 132| :------------- | :------------- | :------------- | :------------- | :------------- | 133| <a id="cc_args_list-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 134| <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 | `[]` | 135 136 137<a id="cc_external_feature"></a> 138 139## cc_external_feature 140 141<pre> 142cc_external_feature(<a href="#cc_external_feature-name">name</a>, <a href="#cc_external_feature-feature_name">feature_name</a>, <a href="#cc_external_feature-overridable">overridable</a>) 143</pre> 144 145A declaration that a [feature](https://bazel.build/docs/cc-toolchain-config-reference#features) with this name is defined elsewhere. 146 147This rule communicates that a feature has been defined externally to make it possible to reference 148features that live outside the rule-based cc toolchain ecosystem. This allows various toolchain 149rules to reference the external feature without accidentally re-defining said feature. 150 151This rule is currently considered a private API of the toolchain rules to encourage the Bazel 152ecosystem to migrate to properly defining their features as rules. 153 154Example: 155``` 156load("@rules_cc//cc/toolchains:external_feature.bzl", "cc_external_feature") 157 158# rules_rust defines a feature that is disabled whenever rust artifacts are being linked using 159# the cc toolchain to signal that incompatible flags should be disabled as well. 160cc_external_feature( 161 name = "rules_rust_unsupported_feature", 162 feature_name = "rules_rust_unsupported_feature", 163 overridable = False, 164) 165``` 166 167**ATTRIBUTES** 168 169 170| Name | Description | Type | Mandatory | Default | 171| :------------- | :------------- | :------------- | :------------- | :------------- | 172| <a id="cc_external_feature-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 173| <a id="cc_external_feature-feature_name"></a>feature_name | The name of the feature | String | required | | 174| <a id="cc_external_feature-overridable"></a>overridable | Whether the feature can be overridden | Boolean | required | | 175 176 177<a id="cc_feature"></a> 178 179## cc_feature 180 181<pre> 182cc_feature(<a href="#cc_feature-name">name</a>, <a href="#cc_feature-args">args</a>, <a href="#cc_feature-feature_name">feature_name</a>, <a href="#cc_feature-implies">implies</a>, <a href="#cc_feature-mutually_exclusive">mutually_exclusive</a>, <a href="#cc_feature-overrides">overrides</a>, <a href="#cc_feature-requires_any_of">requires_any_of</a>) 183</pre> 184 185A dynamic set of toolchain flags that create a singular [feature](https://bazel.build/docs/cc-toolchain-config-reference#features) definition. 186 187A feature is basically a dynamically toggleable [`cc_args_list`](#cc_args_list). There are a variety of 188dependencies and compatibility requirements that must be satisfied to enable a 189[`cc_feature`](#cc_feature). Once those conditions are met, the arguments in [`cc_feature.args`](#cc_feature-args) 190are expanded and added to the command-line. 191 192A feature may be enabled or disabled through the following mechanisms: 193* Via command-line flags, or a `.bazelrc` file via the 194 [`--features` flag](https://bazel.build/reference/command-line-reference#flag--features) 195* Through inter-feature relationships (via [`cc_feature.implies`](#cc_feature-implies)) where one 196 feature may implicitly enable another. 197* Individual rules (e.g. `cc_library`) or `package` definitions may elect to manually enable or 198 disable features through the 199 [`features` attribute](https://bazel.build/reference/be/common-definitions#common.features). 200 201Note that a feature may alternate between enabled and disabled dynamically over the course of a 202build. Because of their toggleable nature, it's generally best to avoid adding arguments to a 203[`cc_toolchain`](#cc_toolchain) as a [`cc_feature`](#cc_feature) unless strictly necessary. Instead, prefer to express arguments 204via [`cc_toolchain.args`](#cc_toolchain-args) whenever possible. 205 206You should use a [`cc_feature`](#cc_feature) when any of the following apply: 207* You need the flags to be dynamically toggled over the course of a build. 208* You want build files to be able to configure the flags in question. For example, a 209 binary might specify `features = ["optimize_for_size"]` to create a small 210 binary instead of optimizing for performance. 211* You need to carry forward Starlark toolchain behaviors. If you're migrating a 212 complex Starlark-based toolchain definition to these rules, many of the 213 workflows and flags were likely based on features. 214 215If you only need to configure flags via the Bazel command-line, instead 216consider adding a 217[`bool_flag`](https://github.com/bazelbuild/bazel-skylib/tree/main/doc/common_settings_doc.md#bool_flag) 218paired with a [`config_setting`](https://bazel.build/reference/be/general#config_setting) 219and then make your [`cc_args`](#cc_args) rule `select` on the `config_setting`. 220 221For more details about how Bazel handles features, see the official Bazel 222documentation at 223https://bazel.build/docs/cc-toolchain-config-reference#features. 224 225Example: 226``` 227load("@rules_cc//cc/toolchains:feature.bzl", "cc_feature") 228 229# A feature that enables LTO, which may be incompatible when doing interop with various 230# languages (e.g. rust, go), or may need to be disabled for particular `cc_binary` rules 231# for various reasons. 232cc_feature( 233 name = "lto", 234 feature_name = "lto", 235 args = [":lto_args"], 236) 237``` 238 239**ATTRIBUTES** 240 241 242| Name | Description | Type | Mandatory | Default | 243| :------------- | :------------- | :------------- | :------------- | :------------- | 244| <a id="cc_feature-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 245| <a id="cc_feature-args"></a>args | A list of [`cc_args`](#cc_args) or [`cc_args_list`](#cc_args_list) labels that are expanded when this feature is enabled. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 246| <a id="cc_feature-feature_name"></a>feature_name | The name of the feature that this rule implements.<br><br>The feature name is a string that will be used in the `features` attribute of rules to enable them (eg. `cc_binary(..., features = ["opt"])`.<br><br>While two features with the same `feature_name` may not be bound to the same toolchain, they can happily live alongside each other in the same BUILD file.<br><br>Example: <pre><code>cc_feature( name = "sysroot_macos", feature_name = "sysroot", ... ) cc_feature( name = "sysroot_linux", feature_name = "sysroot", ... )</code></pre> | String | optional | `""` | 247| <a id="cc_feature-implies"></a>implies | List of features enabled along with this feature.<br><br>Warning: If any of the features cannot be enabled, this feature is silently disabled. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 248| <a id="cc_feature-mutually_exclusive"></a>mutually_exclusive | A list of things that this feature is mutually exclusive with.<br><br>It can be either: * A feature, in which case the two features are mutually exclusive. * A [`cc_mutually_exclusive_category`](#cc_mutually_exclusive_category), in which case all features that write `mutually_exclusive = [":category"]` are mutually exclusive with each other.<br><br>If this feature has a side-effect of implementing another feature, it can be useful to list that feature here to ensure they aren't enabled at the same time. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 249| <a id="cc_feature-overrides"></a>overrides | A declaration that this feature overrides a known feature.<br><br>In the example below, if you missed the "overrides" attribute, it would complain that the feature "opt" was defined twice.<br><br>Example: <pre><code>load("@rules_cc//cc/toolchains:feature.bzl", "cc_feature") cc_feature( name = "opt", feature_name = "opt", args = [":size_optimized"], overrides = "@rules_cc//cc/toolchains/features:opt", )</code></pre> | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 250| <a id="cc_feature-requires_any_of"></a>requires_any_of | A list of feature sets that define toolchain compatibility.<br><br>If *at least one* of the listed [`cc_feature_set`](#cc_feature_set)s are fully satisfied (all features exist in the toolchain AND are currently enabled), this feature is deemed compatible and may be enabled.<br><br>Note: Even if `cc_feature.requires_any_of` is satisfied, a feature is not enabled unless another mechanism (e.g. command-line flags, `cc_feature.implies`, `cc_toolchain_config.enabled_features`) signals that the feature should actually be enabled. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 251 252 253<a id="cc_feature_constraint"></a> 254 255## cc_feature_constraint 256 257<pre> 258cc_feature_constraint(<a href="#cc_feature_constraint-name">name</a>, <a href="#cc_feature_constraint-all_of">all_of</a>, <a href="#cc_feature_constraint-none_of">none_of</a>) 259</pre> 260 261Defines a compound relationship between features. 262 263This rule can be used with [`cc_args.require_any_of`](#cc_args-require_any_of) to specify that a set 264of arguments are only enabled when a constraint is met. Both `all_of` and `none_of` must be 265satisfied simultaneously. 266 267This is basically a [`cc_feature_set`](#cc_feature_set) that supports `none_of` expressions. This extra flexibility 268is why this rule may only be used by [`cc_args.require_any_of`](#cc_args-require_any_of). 269 270Example: 271``` 272load("@rules_cc//cc/toolchains:feature_constraint.bzl", "cc_feature_constraint") 273 274# A constraint that requires a `linker_supports_thinlto` feature to be enabled, 275# AND a `no_optimization` to be disabled. 276cc_feature_constraint( 277 name = "thinlto_constraint", 278 all_of = [":linker_supports_thinlto"], 279 none_of = [":no_optimization"], 280) 281``` 282 283**ATTRIBUTES** 284 285 286| Name | Description | Type | Mandatory | Default | 287| :------------- | :------------- | :------------- | :------------- | :------------- | 288| <a id="cc_feature_constraint-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 289| <a id="cc_feature_constraint-all_of"></a>all_of | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 290| <a id="cc_feature_constraint-none_of"></a>none_of | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 291 292 293<a id="cc_feature_set"></a> 294 295## cc_feature_set 296 297<pre> 298cc_feature_set(<a href="#cc_feature_set-name">name</a>, <a href="#cc_feature_set-all_of">all_of</a>) 299</pre> 300 301Defines a set of features. 302 303This may be used by both [`cc_feature`](#cc_feature) and [`cc_args`](#cc_args) rules, and is effectively a way to express 304a logical `AND` operation across multiple required features. 305 306Example: 307``` 308load("@rules_cc//cc/toolchains:feature_set.bzl", "cc_feature_set") 309 310cc_feature_set( 311 name = "thin_lto_requirements", 312 all_of = [ 313 ":thin_lto", 314 ":opt", 315 ], 316) 317``` 318 319**ATTRIBUTES** 320 321 322| Name | Description | Type | Mandatory | Default | 323| :------------- | :------------- | :------------- | :------------- | :------------- | 324| <a id="cc_feature_set-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 325| <a id="cc_feature_set-all_of"></a>all_of | A set of features | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 326 327 328<a id="cc_mutually_exclusive_category"></a> 329 330## cc_mutually_exclusive_category 331 332<pre> 333cc_mutually_exclusive_category(<a href="#cc_mutually_exclusive_category-name">name</a>) 334</pre> 335 336A rule used to categorize [`cc_feature`](#cc_feature) definitions for which only one can be enabled. 337 338This is used by [`cc_feature.mutually_exclusive`](#cc_feature-mutually_exclusive) to express groups 339of [`cc_feature`](#cc_feature) definitions that are inherently incompatible with each other and must be treated as 340mutually exclusive. 341 342Warning: These groups are keyed by name, so two [`cc_mutually_exclusive_category`](#cc_mutually_exclusive_category) definitions of the 343same name in different packages will resolve to the same logical group. 344 345Example: 346``` 347load("@rules_cc//cc/toolchains:feature.bzl", "cc_feature") 348load("@rules_cc//cc/toolchains:mutually_exclusive_category.bzl", "cc_mutually_exclusive_category") 349 350cc_mutually_exclusive_category( 351 name = "opt_level", 352) 353 354cc_feature( 355 name = "speed_optimized", 356 mutually_exclusive = [":opt_level"], 357) 358 359cc_feature( 360 name = "size_optimized", 361 mutually_exclusive = [":opt_level"], 362) 363 364cc_feature( 365 name = "unoptimized", 366 mutually_exclusive = [":opt_level"], 367) 368``` 369 370**ATTRIBUTES** 371 372 373| Name | Description | Type | Mandatory | Default | 374| :------------- | :------------- | :------------- | :------------- | :------------- | 375| <a id="cc_mutually_exclusive_category-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 376 377 378<a id="cc_tool"></a> 379 380## cc_tool 381 382<pre> 383cc_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>, <a href="#cc_tool-capabilities">capabilities</a>) 384</pre> 385 386Declares a tool for use by toolchain actions. 387 388[`cc_tool`](#cc_tool) rules are used in a [`cc_tool_map`](#cc_tool_map) rule to ensure all files and 389metadata required to run a tool are available when constructing a [`cc_toolchain`](#cc_toolchain). 390 391In general, include all files that are always required to run a tool (e.g. libexec/** and 392cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only 393required when certain flags are passed to the tool, consider using a [`cc_args`](#cc_args) rule to 394bind the files to the flags that require them. This reduces the overhead required to properly 395enumerate a sandbox with all the files required to run a tool, and ensures that there isn't 396unintentional leakage across configurations and actions. 397 398Example: 399``` 400load("@rules_cc//cc/toolchains:tool.bzl", "cc_tool") 401 402cc_tool( 403 name = "clang_tool", 404 executable = "@llvm_toolchain//:bin/clang", 405 # Suppose clang needs libc to run. 406 data = ["@llvm_toolchain//:lib/x86_64-linux-gnu/libc.so.6"] 407 tags = ["requires-network"], 408 capabilities = ["@rules_cc//cc/toolchains/capabilities:supports_pic"], 409) 410``` 411 412**ATTRIBUTES** 413 414 415| Name | Description | Type | Mandatory | Default | 416| :------------- | :------------- | :------------- | :------------- | :------------- | 417| <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 | | 418| <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` | 419| <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 | `[]` | 420| <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 | `[]` | 421| <a id="cc_tool-capabilities"></a>capabilities | Declares that a tool is capable of doing something.<br><br>For example, `@rules_cc//cc/toolchains/capabilities:supports_pic`. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 422 423 424<a id="cc_tool_capability"></a> 425 426## cc_tool_capability 427 428<pre> 429cc_tool_capability(<a href="#cc_tool_capability-name">name</a>, <a href="#cc_tool_capability-feature_name">feature_name</a>) 430</pre> 431 432A capability is an optional feature that a tool supports. 433 434For example, not all compilers support PIC, so to handle this, we write: 435 436``` 437cc_tool( 438 name = "clang", 439 src = "@host_tools/bin/clang", 440 capabilities = [ 441 "@rules_cc//cc/toolchains/capabilities:supports_pic", 442 ], 443) 444 445cc_args( 446 name = "pic", 447 requires = [ 448 "@rules_cc//cc/toolchains/capabilities:supports_pic" 449 ], 450 args = ["-fPIC"], 451) 452``` 453 454This ensures that `-fPIC` is added to the command-line only when we are using a 455tool that supports PIC. 456 457**ATTRIBUTES** 458 459 460| Name | Description | Type | Mandatory | Default | 461| :------------- | :------------- | :------------- | :------------- | :------------- | 462| <a id="cc_tool_capability-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 463| <a id="cc_tool_capability-feature_name"></a>feature_name | The name of the feature to generate for this capability | String | optional | `""` | 464 465 466<a id="cc_args"></a> 467 468## cc_args 469 470<pre> 471cc_args(<a href="#cc_args-name">name</a>, <a href="#cc_args-actions">actions</a>, <a href="#cc_args-allowlist_include_directories">allowlist_include_directories</a>, <a href="#cc_args-args">args</a>, <a href="#cc_args-data">data</a>, <a href="#cc_args-env">env</a>, <a href="#cc_args-format">format</a>, <a href="#cc_args-iterate_over">iterate_over</a>, <a href="#cc_args-nested">nested</a>, 472 <a href="#cc_args-requires_not_none">requires_not_none</a>, <a href="#cc_args-requires_none">requires_none</a>, <a href="#cc_args-requires_true">requires_true</a>, <a href="#cc_args-requires_false">requires_false</a>, <a href="#cc_args-requires_equal">requires_equal</a>, 473 <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>) 474</pre> 475 476Action-specific arguments for use with a [`cc_toolchain`](#cc_toolchain). 477 478This rule is the fundamental building building block for every toolchain tool invocation. Each 479argument expressed in a toolchain tool invocation (e.g. `gcc`, `llvm-ar`) is declared in a 480[`cc_args`](#cc_args) rule that applies an ordered list of arguments to a set of toolchain 481actions. [`cc_args`](#cc_args) rules can be added unconditionally to a 482[`cc_toolchain`](#cc_toolchain), conditionally via `select()` statements, or dynamically via an 483intermediate [`cc_feature`](#cc_feature). 484 485Conceptually, this is similar to the old `CFLAGS`, `CPPFLAGS`, etc. environment variables that 486many build systems use to determine which flags to use for a given action. The significant 487difference is that [`cc_args`](#cc_args) rules are declared in a structured way that allows for 488significantly more powerful and sharable toolchain configurations. Also, due to Bazel's more 489granular action types, it's possible to bind flags to very specific actions (e.g. LTO indexing 490for an executable vs a dynamic library) multiple different actions (e.g. C++ compile and link 491simultaneously). 492 493Example usage: 494``` 495load("@rules_cc//cc/toolchains:args.bzl", "cc_args") 496 497# Basic usage: a trivial flag. 498# 499# An example of expressing `-Werror` as a [`cc_args`](#cc_args) rule. 500cc_args( 501 name = "warnings_as_errors", 502 actions = [ 503 # Applies to all C/C++ compile actions. 504 "@rules_cc//cc/toolchains/actions:compile_actions", 505 ], 506 args = ["-Werror"], 507) 508 509# Basic usage: ordered flags. 510# 511# An example of linking against libc++, which uses two flags that must be applied in order. 512cc_args( 513 name = "link_libcxx", 514 actions = [ 515 # Applies to all link actions. 516 "@rules_cc//cc/toolchains/actions:link_actions", 517 ], 518 # On tool invocation, this appears as `-Xlinker -lc++`. Nothing will ever end up between 519 # the two flags. 520 args = [ 521 "-Xlinker", 522 "-lc++", 523 ], 524) 525 526# Advanced usage: built-in variable expansions. 527# 528# Expands to `-L/path/to/search_dir` for each directory in the built-in variable 529# `library_search_directories`. This variable is managed internally by Bazel through inherent 530# behaviors of Bazel and the interactions between various C/C++ build rules. 531cc_args( 532 name = "library_search_directories", 533 actions = [ 534 "@rules_cc//cc/toolchains/actions:link_actions", 535 ], 536 args = ["-L{search_dir}"], 537 iterate_over = "@rules_cc//cc/toolchains/variables:library_search_directories", 538 requires_not_none = "@rules_cc//cc/toolchains/variables:library_search_directories", 539 format = { 540 "search_dir": "@rules_cc//cc/toolchains/variables:library_search_directories", 541 }, 542) 543``` 544 545For more extensive examples, see the usages here: 546 https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args 547 548 549**PARAMETERS** 550 551 552| Name | Description | Default Value | 553| :------------- | :------------- | :------------- | 554| <a id="cc_args-name"></a>name | (str) The name of the target. | none | 555| <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` | 556| <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` | 557| <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` | 558| <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` | 559| <a id="cc_args-env"></a>env | (Dict[str, str]) Environment variables that should be set when the tool is invoked. | `None` | 560| <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. | `{}` | 561| <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` | 562| <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` | 563| <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` | 564| <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` | 565| <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` | 566| <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` | 567| <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` | 568| <a id="cc_args-requires_equal_value"></a>requires_equal_value | (str) The value to compare (requires_equal)[#cc_args-requires_equal] against. | `None` | 569| <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` | 570| <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 | 571 572 573<a id="cc_nested_args"></a> 574 575## cc_nested_args 576 577<pre> 578cc_nested_args(<a href="#cc_nested_args-name">name</a>, <a href="#cc_nested_args-args">args</a>, <a href="#cc_nested_args-data">data</a>, <a href="#cc_nested_args-format">format</a>, <a href="#cc_nested_args-iterate_over">iterate_over</a>, <a href="#cc_nested_args-nested">nested</a>, <a href="#cc_nested_args-requires_not_none">requires_not_none</a>, <a href="#cc_nested_args-requires_none">requires_none</a>, 579 <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>) 580</pre> 581 582Nested arguments for use in more complex [`cc_args`](#cc_args) expansions. 583 584While this rule is very similar in shape to [`cc_args`](#cc_args), it is intended to be used as a 585dependency of [`cc_args`](#cc_args) to provide additional arguments that should be applied to the 586same actions as defined by the parent [`cc_args`](#cc_args) rule. The key motivation for this rule 587is to allow for more complex variable-based argument expensions. 588 589Prefer expressing collections of arguments as [`cc_args`](#cc_args) and 590[`cc_args_list`](#cc_args_list) rules when possible. 591 592For living examples of how this rule is used, see the usages here: 593 https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/runtime_library_search_directories/BUILD 594 https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/libraries_to_link/BUILD 595 596Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to 597use this rule. 598 599 600**PARAMETERS** 601 602 603| Name | Description | Default Value | 604| :------------- | :------------- | :------------- | 605| <a id="cc_nested_args-name"></a>name | (str) The name of the target. | none | 606| <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` | 607| <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` | 608| <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. | `{}` | 609| <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` | 610| <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` | 611| <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` | 612| <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` | 613| <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` | 614| <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` | 615| <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` | 616| <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` | 617| <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 | 618 619 620<a id="cc_tool_map"></a> 621 622## cc_tool_map 623 624<pre> 625cc_tool_map(<a href="#cc_tool_map-name">name</a>, <a href="#cc_tool_map-tools">tools</a>, <a href="#cc_tool_map-kwargs">kwargs</a>) 626</pre> 627 628A toolchain configuration rule that maps toolchain actions to tools. 629 630A [`cc_tool_map`](#cc_tool_map) aggregates all the tools that may be used for a given toolchain 631and maps them to their corresponding actions. Conceptually, this is similar to the 632`CXX=/path/to/clang++` environment variables that most build systems use to determine which 633tools to use for a given action. To simplify usage, some actions have been grouped together (for 634example, 635[@rules_cc//cc/toolchains/actions:cpp_compile_actions](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD)) to 636logically express "all the C++ compile actions". 637 638In Bazel, there is a little more granularity to the mapping, so the mapping doesn't follow the 639traditional `CXX`, `AR`, etc. naming scheme. For a comprehensive list of all the well-known 640actions, see @rules_cc//cc/toolchains/actions:BUILD. 641 642Example usage: 643``` 644load("@rules_cc//cc/toolchains:tool_map.bzl", "cc_tool_map") 645 646cc_tool_map( 647 name = "all_tools", 648 tools = { 649 "@rules_cc//cc/toolchains/actions:assembly_actions": ":asm", 650 "@rules_cc//cc/toolchains/actions:c_compile": ":clang", 651 "@rules_cc//cc/toolchains/actions:cpp_compile_actions": ":clang++", 652 "@rules_cc//cc/toolchains/actions:link_actions": ":lld", 653 "@rules_cc//cc/toolchains/actions:objcopy_embed_data": ":llvm-objcopy", 654 "@rules_cc//cc/toolchains/actions:strip": ":llvm-strip", 655 "@rules_cc//cc/toolchains/actions:ar_actions": ":llvm-ar", 656 }, 657) 658``` 659 660 661**PARAMETERS** 662 663 664| Name | Description | Default Value | 665| :------------- | :------------- | :------------- | 666| <a id="cc_tool_map-name"></a>name | (str) The name of the target. | none | 667| <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 | 668| <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 | 669 670 671<a id="cc_toolchain"></a> 672 673## cc_toolchain 674 675<pre> 676cc_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>, 677 <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>, 678 <a href="#cc_toolchain-kwargs">kwargs</a>) 679</pre> 680 681A C/C++ toolchain configuration. 682 683This rule is the core declaration of a complete C/C++ toolchain. It collects together 684tool configuration, which arguments to pass to each tool, and how 685[features](https://bazel.build/docs/cc-toolchain-config-reference#features) 686(dynamically-toggleable argument lists) interact. 687 688A single [`cc_toolchain`](#cc_toolchain) may support a wide variety of platforms and configurations through 689[configurable build attributes](https://bazel.build/docs/configurable-attributes) and 690[feature relationships](https://bazel.build/docs/cc-toolchain-config-reference#feature-relationships). 691 692Arguments are applied to commandline invocation of tools in the following order: 693 6941. Arguments in the order they are listed in listed in [`args`](#cc_toolchain-args). 6952. Any legacy/built-in features that have been implicitly or explicitly enabled. 6963. User-defined features in the order they are listed in 697 [`known_features`](#cc_toolchain-known_features). 698 699When building a [`cc_toolchain`](#cc_toolchain) configuration, it's important to understand how `select` 700statements will be evaluated: 701 702* Most attributes and dependencies of a [`cc_toolchain`](#cc_toolchain) are evaluated under the target platform. 703 This means that a `@platforms//os:linux` constraint will be satisfied when 704 the final compiled binaries are intended to be ran from a Linux machine. This means that 705 a different operating system (e.g. Windows) may be cross-compiling to linux. 706* The [`cc_tool_map`](#cc_tool_map) rule performs a transition to the exec platform when evaluating tools. This 707 means that a if a `@platforms//os:linux` constraint is satisfied in a 708 `select` statement on a [`cc_tool`](#cc_tool), that means the machine that will run the tool is a Linux 709 machine. This means that a Linux machine may be cross-compiling to a different OS 710 like Windows. 711 712Generated rules: 713 {name}: A [`cc_toolchain`](#cc_toolchain) for this toolchain. 714 _{name}_config: A `cc_toolchain_config` for this toolchain. 715 _{name}_*_files: Generated rules that group together files for 716 "ar_files", "as_files", "compiler_files", "coverage_files", 717 "dwp_files", "linker_files", "objcopy_files", and "strip_files" 718 normally enumerated as part of the [`cc_toolchain`](#cc_toolchain) rule. 719 720 721**PARAMETERS** 722 723 724| Name | Description | Default Value | 725| :------------- | :------------- | :------------- | 726| <a id="cc_toolchain-name"></a>name | (str) The name of the label for the toolchain. | none | 727| <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` | 728| <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. | `[]` | 729| <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. | `[]` | 730| <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. | `[]` | 731| <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` | 732| <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` | 733| <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` | 734| <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` | 735| <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. | `False` | 736| <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. | `False` | 737| <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 | 738 739 740<a id="cc_variable"></a> 741 742## cc_variable 743 744<pre> 745cc_variable(<a href="#cc_variable-name">name</a>, <a href="#cc_variable-type">type</a>, <a href="#cc_variable-kwargs">kwargs</a>) 746</pre> 747 748Exposes a toolchain variable to use in toolchain argument expansions. 749 750This internal rule exposes [toolchain variables](https://bazel.build/docs/cc-toolchain-config-reference#cctoolchainconfiginfo-build-variables) 751that may be expanded in [`cc_args`](#cc_args) or [`cc_nested_args`](#cc_nested_args) 752rules. Because these varaibles merely expose variables inherrent to Bazel, 753it's not possible to declare custom variables. 754 755For a full list of available variables, see 756[@rules_cc//cc/toolchains/varaibles:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD). 757 758Example: 759``` 760load("@rules_cc//cc/toolchains/impl:variables.bzl", "cc_variable") 761 762# Defines two targets, ":foo" and ":foo.bar" 763cc_variable( 764 name = "foo", 765 type = types.list(types.struct(bar = types.string)), 766) 767``` 768 769 770**PARAMETERS** 771 772 773| Name | Description | Default Value | 774| :------------- | :------------- | :------------- | 775| <a id="cc_variable-name"></a>name | (str) The name of the outer variable, and the rule. | none | 776| <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 | 777| <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 | 778 779 780