Skip to content

Commit

Permalink
Document args-related toolchain rules
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@copybara-github
Googler authored and copybara-github committed Sep 12, 2024
1 parent 0d5561b commit de86823
Show file tree
Hide file tree
Showing 5 changed files with 489 additions and 20 deletions.
174 changes: 157 additions & 17 deletions cc/toolchains/args.bzl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
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",
Expand All @@ -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
)
42 changes: 40 additions & 2 deletions cc/toolchains/args_list.bzl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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],
Expand Down
6 changes: 6 additions & 0 deletions cc/toolchains/impl/documented_api.bzl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
78 changes: 77 additions & 1 deletion cc/toolchains/nested_args.bzl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
Loading

0 comments on commit de86823

Please sign in to comment.