Document args-related toolchain rules
BEGIN_PUBLIC
Document args-related toolchain rules
Adds comprehensive documentation for cc_args, cc_nested_args, and cc_args_list.
END_PUBLIC
PiperOrigin-RevId: 673921558
Change-Id: I1c9c0731925a03dedec983083072f52c6d4c270f
diff --git a/cc/toolchains/args.bzl b/cc/toolchains/args.bzl
index 4f71986..eb3833e 100644
--- a/cc/toolchains/args.bzl
+++ b/cc/toolchains/args.bzl
@@ -86,30 +86,18 @@
"actions": attr.label_list(
providers = [ActionTypeSetInfo],
mandatory = True,
- doc = """A list of action types that this flag set applies to.
-
-See @rules_cc//cc/toolchains/actions:all for valid options.
-""",
+ doc = """See documentation for cc_args macro wrapper.""",
),
"allowlist_include_directories": attr.label_list(
providers = [DirectoryInfo],
- doc = """Include paths implied by using this 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.
-""",
+ doc = """See documentation for cc_args macro wrapper.""",
),
"env": attr.string_dict(
- doc = "Environment variables to be added to the command-line.",
+ doc = """See documentation for cc_args macro wrapper.""",
),
"requires_any_of": attr.label_list(
providers = [FeatureConstraintInfo],
- doc = """This will be enabled when any of the constraints are met.
-
-If omitted, this flag set will be enabled unconditionally.
-""",
+ doc = """See documentation for cc_args macro wrapper.""",
),
"_variables": attr.label(
default = "//cc/toolchains/variables:variables",
@@ -128,9 +116,161 @@
""",
)
-def cc_args(name, format = {}, **kwargs):
+def cc_args(
+ *,
+ name,
+ actions = None,
+ allowlist_include_directories = None,
+ args = None,
+ data = None,
+ env = None,
+ format = {},
+ iterate_over = None,
+ nested = None,
+ requires_not_none = None,
+ requires_none = None,
+ requires_true = None,
+ requires_false = None,
+ requires_equal = None,
+ requires_equal_value = None,
+ requires_any_of = None,
+ **kwargs):
+ """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
+ `cc_args` rule that applies an ordered list of arguments to a set of toolchain actions.
+ `cc_args` rules can be added unconditionally to a `cc_toolchain`, conditionally via `select()`
+ statements, or dynamically via an intermediate `cc_feature`.
+
+ Conceptually, this is similar to the old `CFLAGS`, `CPPFLAGS`, etc. environment variables that
+ many build systems use to determine which flags to use for a given action. The significant
+ difference is that `cc_args` rules are declared in a structured way that allows for
+ significantly more powerful and sharable toolchain configurations. Also, due to Bazel's more
+ granular action types, it's possible to bind flags to very specific actions (e.g. LTO indexing
+ for an executable vs a dynamic library) multiple different actions (e.g. C++ compile and link
+ simultaneously).
+
+ Example usage:
+ ```
+ load("//cc/toolchains:args.bzl", "cc_args")
+
+ # Basic usage: a trivial flag.
+ #
+ # An example of expressing `-Werror` as a `cc_args` rule.
+ cc_args(
+ name = "warnings_as_errors",
+ actions = [
+ # Applies to all C/C++ compile actions.
+ "//cc/toolchains/actions:compile_actions",
+ ],
+ args = ["-Werror"],
+ )
+
+ # Basic usage: ordered flags.
+ #
+ # An example of linking against libc++, which uses two flags that must be applied in order.
+ cc_args(
+ name = "link_libcxx",
+ actions = [
+ # Applies to all link actions.
+ "//cc/toolchains/actions:link_actions",
+ ],
+ # On tool invocation, this appears as `-Xlinker -lc++`. Nothing will ever end up between
+ # the two flags.
+ args = [
+ "-Xlinker",
+ "-lc++",
+ ],
+ )
+
+ # Advanced usage: built-in variable expansions.
+ #
+ # Expands to `-L/path/to/search_dir` for each directory in the built-in variable
+ # `library_search_directories`. This variable is managed internally by Bazel through inherent
+ # behaviors of Bazel and the interactions between various C/C++ build rules.
+ cc_args(
+ name = "library_search_directories",
+ actions = [
+ "//cc/toolchains/actions:link_actions",
+ ],
+ args = ["-L{search_dir}"],
+ iterate_over = "//cc/toolchains/variables:library_search_directories",
+ requires_not_none = "//cc/toolchains/variables:library_search_directories",
+ format = {
+ "search_dir": "//cc/toolchains/variables:library_search_directories",
+ },
+ )
+ ```
+
+ For more extensive examples, see the usages here:
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args
+
+ Args:
+ name: (str) The name of the target.
+ actions: (List[Label]) A list of labels of `cc_action_type` or `cc_action_type_set` rules
+ that dictate which actions these arguments should be applied to.
+ allowlist_include_directories: (List[Label]) A list of include paths that are implied by
+ using this rule. These must point to a skylib
+ [directory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_doc.md#directory)
+ or [subdirectory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_subdirectory_doc.md#subdirectory) rule.
+ Some flags (e.g. --sysroot) imply certain include paths are available despite
+ not explicitly specifying a normal include path flag (`-I`, `-isystem`, etc.).
+ Bazel checks that all included headers are properly provided by a dependency or
+ allowlisted through this mechanism.
+ args: (List[str]) The command-line arguments that are applied by using this rule. This is
+ mutually exclusive with [nested](#cc_args-nested).
+ data: (List[Label]) A list of runtime data dependencies that are required for these
+ arguments to work as intended.
+ env: (Dict[str, str]) Environment variables that should be set when the tool is invoked.
+ format: (Dict[str, Label]) A mapping of format strings to the label of the corresponding
+ `cc_variable` that the value should be pulled from. All instances of `{variable_name}`
+ will be replaced with the expanded value of `variable_name` in this dictionary. The
+ complete list of possible variables can be found in
+ https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is
+ not possible to declare custom variables--these are inherent to Bazel itself.
+ iterate_over: (Label) The label of a `cc_variable` that should be iterated over. This is
+ intended for use with built-in variables that are lists.
+ 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).
+ requires_not_none: (Label) The label of a `cc_variable` that should be checked for
+ existence before expanding this rule. If the variable is None, this rule will be
+ ignored.
+ requires_none: (Label) The label of a `cc_variable` that should be checked for non-existence
+ before expanding this rule. If the variable is not None, this rule will be ignored.
+ requires_true: (Label) The label of a `cc_variable` that should be checked for truthiness
+ before expanding this rule. If the variable is false, this rule will be ignored.
+ requires_false: (Label) The label of a `cc_variable` that should be checked for falsiness
+ before expanding this rule. If the variable is true, this rule will be ignored.
+ requires_equal: (Label) The label of a `cc_variable` that should be checked for equality
+ before expanding this rule. If the variable is not equal to
+ (requires_equal_value)[#cc_args-requires_equal_value], this rule will be ignored.
+ requires_equal_value: (str) The value to compare (requires_equal)[#cc_args-requires_equal]
+ against.
+ requires_any_of: (List[Label]) These arguments will be used
+ in a tool invocation when at least one of the `cc_feature_constraint` entries in this
+ list are satisfied. If omitted, this flag set will be enabled unconditionally.
+ **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
+ """
return _cc_args(
name = name,
+ actions = actions,
+ allowlist_include_directories = allowlist_include_directories,
+ args = args,
+ data = data,
+ env = env,
+ # We flip the key/value pairs in the dictionary here because Bazel doesn't have a
+ # string-keyed label dict attribute type.
format = {k: v for v, k in format.items()},
+ iterate_over = iterate_over,
+ nested = nested,
+ requires_not_none = requires_not_none,
+ requires_none = requires_none,
+ requires_true = requires_true,
+ requires_false = requires_false,
+ requires_equal = requires_equal,
+ requires_equal_value = requires_equal_value,
+ requires_any_of = requires_any_of,
**kwargs
)
diff --git a/cc/toolchains/args_list.bzl b/cc/toolchains/args_list.bzl
index fbbaad5..1f93a84 100644
--- a/cc/toolchains/args_list.bzl
+++ b/cc/toolchains/args_list.bzl
@@ -24,11 +24,49 @@
cc_args_list = rule(
implementation = _cc_args_list_impl,
- doc = "A list of cc_args",
+ doc = """An ordered list of cc_args.
+
+ This is a convenience rule to allow you to group a set of multiple [cc_args](#cc_args) into a
+ single list. This particularly useful for toolchain behaviors that require different flags for
+ different actions.
+
+ Note: The order of the arguments in `args` is preserved to support order-sensitive flags.
+
+ Example usage:
+ ```
+ load("//cc/toolchains:cc_args.bzl", "cc_args")
+ load("//cc/toolchains:args_list.bzl", "cc_args_list")
+
+ cc_args(
+ name = "gc_sections",
+ actions = [
+ "//cc/toolchains/actions:link_actions",
+ ],
+ args = ["-Wl,--gc-sections"],
+ )
+
+ cc_args(
+ name = "function_sections",
+ actions = [
+ "//cc/toolchains/actions:compile_actions",
+ "//cc/toolchains/actions:link_actions",
+ ],
+ args = ["-ffunction-sections"],
+ )
+
+ cc_args_list(
+ name = "gc_functions",
+ args = [
+ ":function_sections",
+ ":gc_sections",
+ ],
+ )
+ ```
+ """,
attrs = {
"args": attr.label_list(
providers = [ArgsListInfo],
- doc = "The cc_args to include",
+ doc = "(ordered) cc_args to include in this list.",
),
},
provides = [ArgsListInfo],
diff --git a/cc/toolchains/impl/documented_api.bzl b/cc/toolchains/impl/documented_api.bzl
index d840b7e..b2ca091 100644
--- a/cc/toolchains/impl/documented_api.bzl
+++ b/cc/toolchains/impl/documented_api.bzl
@@ -13,6 +13,12 @@
# limitations under the License.
"""This is a list of rules/macros that should be exported as documentation."""
+load("//cc/toolchains:args.bzl", _cc_args = "cc_args")
+load("//cc/toolchains:args_list.bzl", _cc_args_list = "cc_args_list")
+load("//cc/toolchains:nested_args.bzl", _cc_nested_args = "cc_nested_args")
load("//cc/toolchains:tool_map.bzl", _cc_tool_map = "cc_tool_map")
cc_tool_map = _cc_tool_map
+cc_args = _cc_args
+cc_nested_args = _cc_nested_args
+cc_args_list = _cc_args_list
diff --git a/cc/toolchains/nested_args.bzl b/cc/toolchains/nested_args.bzl
index 1d31275..0f27a0f 100644
--- a/cc/toolchains/nested_args.bzl
+++ b/cc/toolchains/nested_args.bzl
@@ -41,9 +41,85 @@
""",
)
-def cc_nested_args(name, format = {}, **kwargs):
+def cc_nested_args(
+ *,
+ name,
+ args = None,
+ data = None,
+ format = {},
+ iterate_over = None,
+ nested = None,
+ requires_not_none = None,
+ requires_none = None,
+ requires_true = None,
+ requires_false = None,
+ requires_equal = None,
+ requires_equal_value = None,
+ **kwargs):
+ """Nested arguments for use in more complex cc_args expansions.
+
+ While this rule is very similar in shape to [cc_args](#cc_args), it is intended to be used as a
+ dependency of [cc_args](#cc_args) to provide additional arguments that should be applied to the
+ same actions as defined by the parent [cc_args](#cc_args) rule. The key motivation for this rule
+ is to allow for more complex variable-based argument expensions.
+
+ Prefer expressing collections of arguments as [cc_args](#cc_args) and
+ [cc_args_list](#cc_args_list) rules when possible.
+
+ For living examples of how this rule is used, see the usages here:
+ https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/runtime_library_search_directories/BUILD
+ https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/libraries_to_link/BUILD
+
+ Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to
+ use this rule.
+
+ Args:
+ name: (str) The name of the target.
+ args: (List[str]) The command-line arguments that are applied by using this rule. This is
+ mutually exclusive with [nested](#cc_nested_args-nested).
+ data: (List[Label]) A list of runtime data dependencies that are required for these
+ arguments to work as intended.
+ format: (Dict[str, Label]) A mapping of format strings to the label of the corresponding
+ `cc_variable` that the value should be pulled from. All instances of `{variable_name}`
+ will be replaced with the expanded value of `variable_name` in this dictionary. The
+ complete list of possible variables can be found in
+ https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is
+ not possible to declare custom variables--these are inherent to Bazel itself.
+ iterate_over: (Label) The label of a `cc_variable` that should be iterated over. This is
+ intended for use with built-in variables that are lists.
+ 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).
+ requires_not_none: (Label) The label of a `cc_variable` that should be checked for
+ existence before expanding this rule. If the variable is None, this rule will be
+ ignored.
+ requires_none: (Label) The label of a `cc_variable` that should be checked for non-existence
+ before expanding this rule. If the variable is not None, this rule will be ignored.
+ requires_true: (Label) The label of a `cc_variable` that should be checked for truthiness
+ before expanding this rule. If the variable is false, this rule will be ignored.
+ requires_false: (Label) The label of a `cc_variable` that should be checked for falsiness
+ before expanding this rule. If the variable is true, this rule will be ignored.
+ requires_equal: (Label) The label of a `cc_variable` that should be checked for equality
+ before expanding this rule. If the variable is not equal to
+ (requires_equal_value)[#cc_nested_args-requires_equal_value], this rule will be ignored.
+ requires_equal_value: (str) The value to compare
+ (requires_equal)[#cc_nested_args-requires_equal] against.
+ **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
+ """
return _cc_nested_args(
name = name,
+ args = args,
+ data = data,
+ # We flip the key/value pairs in the dictionary here because Bazel doesn't have a
+ # string-keyed label dict attribute type.
format = {k: v for v, k in format.items()},
+ iterate_over = iterate_over,
+ nested = nested,
+ requires_not_none = requires_not_none,
+ requires_none = requires_none,
+ requires_true = requires_true,
+ requires_false = requires_false,
+ requires_equal = requires_equal,
+ requires_equal_value = requires_equal_value,
**kwargs
)
diff --git a/cc/toolchains/toolchain_api.md b/cc/toolchains/toolchain_api.md
index 3a4a490..ae92f14 100644
--- a/cc/toolchains/toolchain_api.md
+++ b/cc/toolchains/toolchain_api.md
@@ -2,6 +2,215 @@
This is a list of rules/macros that should be exported as documentation.
+<a id="cc_args_list"></a>
+
+## cc_args_list
+
+<pre>
+cc_args_list(<a href="#cc_args_list-name">name</a>, <a href="#cc_args_list-args">args</a>)
+</pre>
+
+An ordered list of cc_args.
+
+This is a convenience rule to allow you to group a set of multiple [cc_args](#cc_args) into a
+single list. This particularly useful for toolchain behaviors that require different flags for
+different actions.
+
+Note: The order of the arguments in `args` is preserved to support order-sensitive flags.
+
+Example usage:
+```
+load("//third_party/bazel_rules/rules_cc/cc/toolchains:cc_args.bzl", "cc_args")
+load("//third_party/bazel_rules/rules_cc/cc/toolchains:args_list.bzl", "cc_args_list")
+
+cc_args(
+ name = "gc_sections",
+ actions = [
+ "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:link_actions",
+ ],
+ args = ["-Wl,--gc-sections"],
+)
+
+cc_args(
+ name = "function_sections",
+ actions = [
+ "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:compile_actions",
+ "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:link_actions",
+ ],
+ args = ["-ffunction-sections"],
+)
+
+cc_args_list(
+ name = "gc_functions",
+ args = [
+ ":function_sections",
+ ":gc_sections",
+ ],
+)
+```
+
+**ATTRIBUTES**
+
+
+| Name | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <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 | |
+| <a id="cc_args_list-args"></a>args | (ordered) cc_args to include in this list. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` |
+
+
+<a id="cc_args"></a>
+
+## cc_args
+
+<pre>
+cc_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>,
+ <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>,
+ <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.
+
+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` rule that applies an ordered list of arguments to a set of toolchain actions.
+`cc_args` rules can be added unconditionally to a `cc_toolchain`, conditionally via `select()`
+statements, or dynamically via an intermediate `cc_feature`.
+
+Conceptually, this is similar to the old `CFLAGS`, `CPPFLAGS`, etc. environment variables that
+many build systems use to determine which flags to use for a given action. The significant
+difference is that `cc_args` rules are declared in a structured way that allows for
+significantly more powerful and sharable toolchain configurations. Also, due to Bazel's more
+granular action types, it's possible to bind flags to very specific actions (e.g. LTO indexing
+for an executable vs a dynamic library) multiple different actions (e.g. C++ compile and link
+simultaneously).
+
+Example usage:
+```
+load("//third_party/bazel_rules/rules_cc/cc/toolchains:args.bzl", "cc_args")
+
+# Basic usage: a trivial flag.
+#
+# An example of expressing `-Werror` as a `cc_args` rule.
+cc_args(
+ name = "warnings_as_errors",
+ actions = [
+ # Applies to all C/C++ compile actions.
+ "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:compile_actions",
+ ],
+ args = ["-Werror"],
+)
+
+# Basic usage: ordered flags.
+#
+# An example of linking against libc++, which uses two flags that must be applied in order.
+cc_args(
+ name = "link_libcxx",
+ actions = [
+ # Applies to all link actions.
+ "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:link_actions",
+ ],
+ # On tool invocation, this appears as `-Xlinker -lc++`. Nothing will ever end up between
+ # the two flags.
+ args = [
+ "-Xlinker",
+ "-lc++",
+ ],
+)
+
+# Advanced usage: built-in variable expansions.
+#
+# Expands to `-L/path/to/search_dir` for each directory in the built-in variable
+# `library_search_directories`. This variable is managed internally by Bazel through inherent
+# behaviors of Bazel and the interactions between various C/C++ build rules.
+cc_args(
+ name = "library_search_directories",
+ actions = [
+ "//third_party/bazel_rules/rules_cc/cc/toolchains/actions:link_actions",
+ ],
+ args = ["-L{search_dir}"],
+ iterate_over = "//third_party/bazel_rules/rules_cc/cc/toolchains/variables:library_search_directories",
+ requires_not_none = "//third_party/bazel_rules/rules_cc/cc/toolchains/variables:library_search_directories",
+ format = {
+ "search_dir": "//third_party/bazel_rules/rules_cc/cc/toolchains/variables:library_search_directories",
+ },
+)
+```
+
+For more extensive examples, see the usages here:
+ https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args
+
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="cc_args-name"></a>name | (str) The name of the target. | none |
+| <a id="cc_args-actions"></a>actions | (List[Label]) A list of labels of `cc_action_type` or `cc_action_type_set` rules that dictate which actions these arguments should be applied to. | `None` |
+| <a id="cc_args-allowlist_include_directories"></a>allowlist_include_directories | (List[Label]) A list of include paths that are implied by using this rule. These must point to a skylib [directory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_doc.md#directory) or [subdirectory](https://github.com/bazelbuild/bazel-skylib/blob/main/docs/directory_subdirectory_doc.md#subdirectory) rule. Some flags (e.g. --sysroot) imply certain include paths are available despite not explicitly specifying a normal include path flag (`-I`, `-isystem`, etc.). Bazel checks that all included headers are properly provided by a dependency or allowlisted through this mechanism. | `None` |
+| <a id="cc_args-args"></a>args | (List[str]) The command-line arguments that are applied by using this rule. This is mutually exclusive with [nested](#cc_args-nested). | `None` |
+| <a id="cc_args-data"></a>data | (List[Label]) A list of runtime data dependencies that are required for these arguments to work as intended. | `None` |
+| <a id="cc_args-env"></a>env | (Dict[str, str]) Environment variables that should be set when the tool is invoked. | `None` |
+| <a id="cc_args-format"></a>format | (Dict[str, Label]) A mapping of format strings to the label of the corresponding `cc_variable` that the value should be pulled from. All instances of `{variable_name}` will be replaced with the expanded value of `variable_name` in this dictionary. The complete list of possible variables can be found in https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is not possible to declare custom variables--these are inherent to Bazel itself. | `{}` |
+| <a id="cc_args-iterate_over"></a>iterate_over | (Label) The label of a `cc_variable` that should be iterated over. This is intended for use with built-in variables that are lists. | `None` |
+| <a id="cc_args-nested"></a>nested | (List[Label]) A list of [cc_nested_args](#cc_nested_args) rules that should be expanded to command-line arguments when this rule is used. This is mutually exclusive with [args](#cc_args-args). | `None` |
+| <a id="cc_args-requires_not_none"></a>requires_not_none | (Label) The label of a `cc_variable` that should be checked for existence before expanding this rule. If the variable is None, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_none"></a>requires_none | (Label) The label of a `cc_variable` that should be checked for non-existence before expanding this rule. If the variable is not None, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_true"></a>requires_true | (Label) The label of a `cc_variable` that should be checked for truthiness before expanding this rule. If the variable is false, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_false"></a>requires_false | (Label) The label of a `cc_variable` that should be checked for falsiness before expanding this rule. If the variable is true, this rule will be ignored. | `None` |
+| <a id="cc_args-requires_equal"></a>requires_equal | (Label) The label of a `cc_variable` that should be checked for equality before expanding this rule. If the variable is not equal to (requires_equal_value)[#cc_args-requires_equal_value], this rule will be ignored. | `None` |
+| <a id="cc_args-requires_equal_value"></a>requires_equal_value | (str) The value to compare (requires_equal)[#cc_args-requires_equal] against. | `None` |
+| <a id="cc_args-requires_any_of"></a>requires_any_of | (List[Label]) These arguments will be used in a tool invocation when at least one of the `cc_feature_constraint` entries in this list are satisfied. If omitted, this flag set will be enabled unconditionally. | `None` |
+| <a id="cc_args-kwargs"></a>kwargs | [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule. | none |
+
+
+<a id="cc_nested_args"></a>
+
+## cc_nested_args
+
+<pre>
+cc_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>,
+ <a href="#cc_nested_args-requires_true">requires_true</a>, <a href="#cc_nested_args-requires_false">requires_false</a>, <a href="#cc_nested_args-requires_equal">requires_equal</a>, <a href="#cc_nested_args-requires_equal_value">requires_equal_value</a>, <a href="#cc_nested_args-kwargs">kwargs</a>)
+</pre>
+
+Nested arguments for use in more complex cc_args expansions.
+
+While this rule is very similar in shape to [cc_args](#cc_args), it is intended to be used as a
+dependency of [cc_args](#cc_args) to provide additional arguments that should be applied to the
+same actions as defined by the parent [cc_args](#cc_args) rule. The key motivation for this rule
+is to allow for more complex variable-based argument expensions.
+
+Prefer expressing collections of arguments as [cc_args](#cc_args) and
+[cc_args_list](#cc_args_list) rules when possible.
+
+For living examples of how this rule is used, see the usages here:
+ https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/runtime_library_search_directories/BUILD
+ https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/args/libraries_to_link/BUILD
+
+Note: These examples are non-trivial, but they illustrate when it is absolutely necessary to
+use this rule.
+
+
+**PARAMETERS**
+
+
+| Name | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="cc_nested_args-name"></a>name | (str) The name of the target. | none |
+| <a id="cc_nested_args-args"></a>args | (List[str]) The command-line arguments that are applied by using this rule. This is mutually exclusive with [nested](#cc_nested_args-nested). | `None` |
+| <a id="cc_nested_args-data"></a>data | (List[Label]) A list of runtime data dependencies that are required for these arguments to work as intended. | `None` |
+| <a id="cc_nested_args-format"></a>format | (Dict[str, Label]) A mapping of format strings to the label of the corresponding `cc_variable` that the value should be pulled from. All instances of `{variable_name}` will be replaced with the expanded value of `variable_name` in this dictionary. The complete list of possible variables can be found in https://github.com/bazelbuild/rules_cc/blob/main/cc/toolchains/variables/BUILD. it is not possible to declare custom variables--these are inherent to Bazel itself. | `{}` |
+| <a id="cc_nested_args-iterate_over"></a>iterate_over | (Label) The label of a `cc_variable` that should be iterated over. This is intended for use with built-in variables that are lists. | `None` |
+| <a id="cc_nested_args-nested"></a>nested | (List[Label]) A list of [cc_nested_args](#cc_nested_args) rules that should be expanded to command-line arguments when this rule is used. This is mutually exclusive with [args](#cc_nested_args-args). | `None` |
+| <a id="cc_nested_args-requires_not_none"></a>requires_not_none | (Label) The label of a `cc_variable` that should be checked for existence before expanding this rule. If the variable is None, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_none"></a>requires_none | (Label) The label of a `cc_variable` that should be checked for non-existence before expanding this rule. If the variable is not None, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_true"></a>requires_true | (Label) The label of a `cc_variable` that should be checked for truthiness before expanding this rule. If the variable is false, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_false"></a>requires_false | (Label) The label of a `cc_variable` that should be checked for falsiness before expanding this rule. If the variable is true, this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_equal"></a>requires_equal | (Label) The label of a `cc_variable` that should be checked for equality before expanding this rule. If the variable is not equal to (requires_equal_value)[#cc_nested_args-requires_equal_value], this rule will be ignored. | `None` |
+| <a id="cc_nested_args-requires_equal_value"></a>requires_equal_value | (str) The value to compare (requires_equal)[#cc_nested_args-requires_equal] against. | `None` |
+| <a id="cc_nested_args-kwargs"></a>kwargs | [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule. | none |
+
+
<a id="cc_tool_map"></a>
## cc_tool_map
