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

cc/toolchains/args.bzl

@@ -86,30 +86,18 @@ _cc_args = rule(
         "actions": attr.label_list(
             providers = [ActionTypeSetInfo],
             mandatory = True,
-            doc = """A list of action types that this flag set applies to.
+            doc = """See documentation for cc_args macro wrapper.""",
-
-See @rules_cc//cc/toolchains/actions:all for valid options.
-""",
         ),
         "allowlist_include_directories": attr.label_list(
             providers = [DirectoryInfo],
-            doc = """Include paths implied by using this rule.
+            doc = """See documentation for cc_args macro wrapper.""",
-
-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.
-""",
         ),
         "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.
+            doc = """See documentation for cc_args macro wrapper.""",
-
-If omitted, this flag set will be enabled unconditionally.
-""",
         ),
         "_variables": attr.label(
             default = "//cc/toolchains/variables:variables",
@@ -128,9 +116,161 @@ Examples:
 """,
 )
 
-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
     )

cc/toolchains/args_list.bzl

@@ -24,11 +24,49 @@ def _cc_args_list_impl(ctx):
 
 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],

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

cc/toolchains/nested_args.bzl

@@ -41,9 +41,85 @@ Examples:
 """,
 )
 
-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
     )

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