mirror of https://github.com/bazelbuild/rules_cc
Add cc_action_type and cc_tool documentation
BEGIN_PUBLIC Add cc_action_type and cc_tool documentation Extends the toolchain API documentation to include docs for cc_action_type, cc_action_type_set, cc_variable, and cc_tool. Also improves cross-reference links and copybara behavior for docs. END_PUBLIC PiperOrigin-RevId: 680601617 Change-Id: Idbbdfbcb2c5a1c3598b6a7e7ba985ed14f871099
This commit is contained in:
Googler
Copybara-Service
parent
9cb80cfc32
commit
b06d2f7d53
|
|
@ -16,6 +16,8 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
|
|||
load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
|
||||
load("@bazel_skylib//rules:expand_template.bzl", "expand_template")
|
||||
load("@stardoc//stardoc:stardoc.bzl", "stardoc")
|
||||
load("//cc/toolchains/impl:documented_api.bzl", "DOCUMENTED_TOOLCHAIN_RULES")
|
||||
load("//cc/toolchains/impl:markdown_helpers.bzl", "xref_substitutions")
|
||||
|
||||
bzl_library(
|
||||
name = "toolchain_rules",
|
||||
|
|
@ -48,13 +50,22 @@ stardoc(
|
|||
deps = [":toolchain_rules"],
|
||||
)
|
||||
|
||||
# In GitHub, we prefer to clarify all the labels that come from rules_cc.
|
||||
expand_template(
|
||||
name = "toolchain_api_md",
|
||||
out = "generated_toolchain_api.md",
|
||||
# Dictionary order 100% matters here!
|
||||
# buildifier: disable=unsorted-dict-items
|
||||
substitutions = {
|
||||
"\"//cc": "\"@rules_cc//cc",
|
||||
},
|
||||
# Strip @rules_cc to prevent instances of @rules_cc@rules_cc//cc.
|
||||
"@rules_cc//cc": "//cc",
|
||||
# In GitHub, we prefer to clarify all the labels that come from
|
||||
# rules_cc.
|
||||
"//cc": "@rules_cc//cc",
|
||||
} | xref_substitutions({
|
||||
"`{}`".format(rule_name): "#{}".format(rule_name)
|
||||
for rule_name in DOCUMENTED_TOOLCHAIN_RULES
|
||||
}),
|
||||
# buildifier: enable=unsorted-dict-items
|
||||
template = ":raw_generated_toolchain_api.md",
|
||||
)
|
||||
|
||||
|
|
|
|||
|
|
@ -37,14 +37,26 @@ cc_action_type = rule(
|
|||
},
|
||||
doc = """A type of action (eg. c_compile, assemble, strip).
|
||||
|
||||
Example:
|
||||
`cc_action_type` rules are used to associate arguments and tools together to
|
||||
perform a specific action. Bazel prescribes a set of known action types that are used to drive
|
||||
typical C/C++/ObjC actions like compiling, linking, and archiving. The set of well-known action
|
||||
types can be found in [//cc/toolchains/actions:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD).
|
||||
|
||||
load("@rules_cc//cc:action_names.bzl", "ACTION_NAMES")
|
||||
It's possible to create project-specific action types for use in toolchains. Be careful when
|
||||
doing this, because every toolchain that encounters the action will need to be configured to
|
||||
support the custom action type. If your project is a library, avoid creating new action types as
|
||||
it will reduce compatibility with existing toolchains and increase setup complexity for users.
|
||||
|
||||
Example:
|
||||
```
|
||||
load("//cc:action_names.bzl", "ACTION_NAMES")
|
||||
load("//cc/toolchains:actions.bzl", "cc_action_type")
|
||||
|
||||
cc_action_type(
|
||||
name = "cpp_compile",
|
||||
action_name = = ACTION_NAMES.cpp_compile,
|
||||
)
|
||||
```
|
||||
""",
|
||||
provides = [ActionTypeInfo, ActionTypeSetInfo],
|
||||
)
|
||||
|
|
@ -60,15 +72,21 @@ def _cc_action_type_set_impl(ctx):
|
|||
cc_action_type_set = rule(
|
||||
doc = """Represents a set of actions.
|
||||
|
||||
This is a convenience rule to allow for more compact representation of a group of action types.
|
||||
Use this anywhere a `cc_action_type` is accepted.
|
||||
|
||||
Example:
|
||||
```
|
||||
load("//cc/toolchains:actions.bzl", "cc_action_type_set")
|
||||
|
||||
cc_action_type_set(
|
||||
name = "link_executable_actions",
|
||||
actions = [
|
||||
":cpp_link_executable",
|
||||
":lto_index_for_executable",
|
||||
"//cc/toolchains/actions:cpp_link_executable",
|
||||
"//cc/toolchains/actions:lto_index_for_executable",
|
||||
],
|
||||
)
|
||||
```
|
||||
""",
|
||||
implementation = _cc_action_type_set_impl,
|
||||
attrs = {
|
||||
|
|
|
|||
|
|
@ -139,9 +139,10 @@ def cc_args(
|
|||
|
||||
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`.
|
||||
`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
|
||||
|
|
@ -208,49 +209,62 @@ def cc_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.
|
||||
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.
|
||||
[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.
|
||||
|
||||
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.
|
||||
|
||||
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)`.
|
||||
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.
|
||||
`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.
|
||||
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
|
||||
nested: (List[Label]) A list of `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
|
||||
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_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.
|
||||
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.
|
||||
**kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
|
||||
"""
|
||||
return _cc_args(
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ cc_args_list = rule(
|
|||
implementation = _cc_args_list_impl,
|
||||
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
|
||||
This is a convenience rule to allow you to group a set of multiple `cc_args` into a
|
||||
single list. This particularly useful for toolchain behaviors that require different flags for
|
||||
different actions.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,12 +13,33 @@
|
|||
# limitations under the License.
|
||||
"""This is a list of rules/macros that should be exported as documentation."""
|
||||
|
||||
load("//cc/toolchains:actions.bzl", _cc_action_type = "cc_action_type", _cc_action_type_set = "cc_action_type_set")
|
||||
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.bzl", _cc_tool = "cc_tool")
|
||||
load("//cc/toolchains:tool_map.bzl", _cc_tool_map = "cc_tool_map")
|
||||
load("//cc/toolchains/impl:variables.bzl", _cc_variable = "cc_variable")
|
||||
|
||||
cc_tool_map = _cc_tool_map
|
||||
cc_tool = _cc_tool
|
||||
cc_args = _cc_args
|
||||
cc_nested_args = _cc_nested_args
|
||||
cc_args_list = _cc_args_list
|
||||
cc_action_type = _cc_action_type
|
||||
cc_action_type_set = _cc_action_type_set
|
||||
cc_variable = _cc_variable
|
||||
|
||||
# This list is used to automatically remap instances of `foo` to [`foo`](#foo)
|
||||
# links in the generated documentation so that maintainers don't need to manually
|
||||
# ensure every reference to a rule is properly linked.
|
||||
DOCUMENTED_TOOLCHAIN_RULES = [
|
||||
"cc_tool_map",
|
||||
"cc_tool",
|
||||
"cc_args",
|
||||
"cc_nested_args",
|
||||
"cc_args_list",
|
||||
"cc_action_type",
|
||||
"cc_action_type_set",
|
||||
"cc_variable",
|
||||
]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,53 @@
|
|||
# Copyright 2024 The Bazel Authors. All rights reserved.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
"""A few small helpers for working with Markdown."""
|
||||
|
||||
def markdown_link(link_text, href):
|
||||
"""Creates a markdown link.
|
||||
|
||||
Args:
|
||||
link_text: The text to display for the link.
|
||||
href: The href for the link.
|
||||
|
||||
Returns:
|
||||
A markdown link.
|
||||
"""
|
||||
return "[" + link_text + "](" + href + ")"
|
||||
|
||||
def xref_substitutions(match_text_patterns):
|
||||
"""Creates a dictionary of substitutions for use for linkification of text.
|
||||
|
||||
Example:
|
||||
```
|
||||
# Produces a dictionary containing:
|
||||
# {
|
||||
# "foo": "[foo](http://foo.com)"
|
||||
# "bar": "[bar](http://bar.com)"
|
||||
# }
|
||||
substitutions = xref_substitutions({
|
||||
"foo": "http://foo.com",
|
||||
"bar": "http://bar.com",
|
||||
})
|
||||
```
|
||||
|
||||
Args:
|
||||
match_text_patterns: A dictionary mapping string literals to the links they should point to.
|
||||
|
||||
Returns:
|
||||
A dictionary of string literals mapped to their linkified substitutions.
|
||||
"""
|
||||
return {
|
||||
match_text: markdown_link(match_text, href)
|
||||
for match_text, href in match_text_patterns.items()
|
||||
}
|
||||
|
|
@ -67,19 +67,32 @@ _cc_variable = rule(
|
|||
)
|
||||
|
||||
def cc_variable(name, type, **kwargs):
|
||||
"""Defines a variable for both the specified variable, and all nested ones.
|
||||
"""Exposes a toolchain variable to use in toolchain argument expansions.
|
||||
|
||||
Eg. cc_variable(
|
||||
This internal rule exposes [toolchain variables](https://bazel.build/docs/cc-toolchain-config-reference#cctoolchainconfiginfo-build-variables)
|
||||
that may be expanded in `cc_args` or `cc_nested_args`
|
||||
rules. Because these varaibles merely expose variables inherrent to Bazel,
|
||||
it's not possible to declare custom variables.
|
||||
|
||||
For a full list of available variables, see
|
||||
[//cc/toolchains/varaibles:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD).
|
||||
|
||||
Example:
|
||||
```
|
||||
load("//cc/toolchains/impl:variables.bzl", "cc_variable")
|
||||
|
||||
# Defines two targets, ":foo" and ":foo.bar"
|
||||
cc_variable(
|
||||
name = "foo",
|
||||
type = types.list(types.struct(bar = types.string))
|
||||
type = types.list(types.struct(bar = types.string)),
|
||||
)
|
||||
|
||||
would define two targets, ":foo" and ":foo.bar"
|
||||
```
|
||||
|
||||
Args:
|
||||
name: (str) The name of the outer variable, and the rule.
|
||||
type: The type of the variable, constructed using types above.
|
||||
**kwargs: kwargs to pass to _cc_variable.
|
||||
type: The type of the variable, constructed using `types` factory in
|
||||
[//cc/toolchains/impl:variables.bzl](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/impl/variables.bzl).
|
||||
**kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
|
||||
"""
|
||||
_cc_variable(name = name, type = json.encode(type), **kwargs)
|
||||
|
||||
|
|
|
|||
|
|
@ -56,19 +56,19 @@ def cc_nested_args(
|
|||
requires_equal = None,
|
||||
requires_equal_value = None,
|
||||
**kwargs):
|
||||
"""Nested arguments for use in more complex cc_args expansions.
|
||||
"""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
|
||||
While this rule is very similar in shape to `cc_args`, it is intended to be used as a
|
||||
dependency of `cc_args` to provide additional arguments that should be applied to the
|
||||
same actions as defined by the parent `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.
|
||||
Prefer expressing collections of arguments as `cc_args` and
|
||||
`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
|
||||
https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/runtime_library_search_directories/BUILD
|
||||
https://github.com/bazelbuild/rules_cc/tree/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.
|
||||
|
|
@ -80,27 +80,30 @@ def cc_nested_args(
|
|||
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
|
||||
`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.
|
||||
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` 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
|
||||
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_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.
|
||||
|
|
|
|||
|
|
@ -66,13 +66,17 @@ cc_tool = rule(
|
|||
cfg = "exec",
|
||||
doc = """The underlying binary that this tool represents.
|
||||
|
||||
Usually just a single prebuilt (eg. @sysroot//:bin/clang), but may be any
|
||||
Usually just a single prebuilt (eg. @toolchain//:bin/clang), but may be any
|
||||
executable label.
|
||||
""",
|
||||
),
|
||||
"data": attr.label_list(
|
||||
allow_files = True,
|
||||
doc = "Additional files that are required for this tool to run.",
|
||||
doc = """Additional files that are required for this tool to run.
|
||||
|
||||
Frequently, clang and gcc require additional files to execute as they often shell out to
|
||||
other binaries (e.g. `cc1`).
|
||||
""",
|
||||
),
|
||||
"allowlist_include_directories": attr.label_list(
|
||||
providers = [DirectoryInfo],
|
||||
|
|
@ -82,17 +86,34 @@ 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.
|
||||
|
||||
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.
|
||||
|
||||
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)`.
|
||||
""",
|
||||
),
|
||||
},
|
||||
provides = [ToolInfo],
|
||||
doc = """Declares a tool that can be bound to action configs.
|
||||
doc = """Declares a tool for use by toolchain actions.
|
||||
|
||||
A tool is a binary with extra metadata for the action config rule to consume
|
||||
(eg. execution_requirements).
|
||||
`cc_tool` rules are used in a `cc_tool_map` rule to ensure all files and
|
||||
metadata required to run a tool are available when constructing a `cc_toolchain`.
|
||||
|
||||
In general, include all files that are always required to run a tool (e.g. libexec/** and
|
||||
cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
|
||||
required when certain flags are passed to the tool, consider using a `cc_args` rule to
|
||||
bind the files to the flags that require them. This reduces the overhead required to properly
|
||||
enumerate a sandbox with all the files required to run a tool, and ensures that there isn't
|
||||
unintentional leakage across configurations and actions.
|
||||
|
||||
Example:
|
||||
```
|
||||
load("//cc/toolchains:tool.bzl", "cc_tool")
|
||||
|
||||
cc_tool(
|
||||
name = "clang_tool",
|
||||
executable = "@llvm_toolchain//:bin/clang",
|
||||
|
|
|
|||
|
|
@ -70,11 +70,12 @@ The tool may be a `cc_tool` or other executable rule.
|
|||
def cc_tool_map(name, tools, **kwargs):
|
||||
"""A toolchain configuration rule that maps toolchain actions to tools.
|
||||
|
||||
A cc_tool_map aggregates all the tools that may be used for a given toolchain and maps them to
|
||||
their corresponding actions. Conceptually, this is similar to the `CXX=/path/to/clang++`
|
||||
environment variables that most build systems use to determine which tools to use for a given
|
||||
action. To simplify usage, some actions have been grouped together (for example,
|
||||
//cc/toolchains/actions:cpp_compile_actions) to
|
||||
A `cc_tool_map` aggregates all the tools that may be used for a given toolchain
|
||||
and maps them to their corresponding actions. Conceptually, this is similar to the
|
||||
`CXX=/path/to/clang++` environment variables that most build systems use to determine which
|
||||
tools to use for a given action. To simplify usage, some actions have been grouped together (for
|
||||
example,
|
||||
[//cc/toolchains/actions:cpp_compile_actions](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD)) to
|
||||
logically express "all the C++ compile actions".
|
||||
|
||||
In Bazel, there is a little more granularity to the mapping, so the mapping doesn't follow the
|
||||
|
|
@ -106,7 +107,8 @@ def cc_tool_map(name, tools, **kwargs):
|
|||
|
||||
Args:
|
||||
name: (str) The name of the target.
|
||||
tools: (Dict[target providing ActionTypeSetInfo, Executable target]) A mapping between `cc_action_type` targets
|
||||
tools: (Dict[Label, Label]) A mapping between
|
||||
`cc_action_type`/`cc_action_type_set` targets
|
||||
and the `cc_tool` or executable target that implements that action.
|
||||
**kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.
|
||||
"""
|
||||
|
|
|
|||
|
|
@ -2,6 +2,82 @@
|
|||
|
||||
This is a list of rules/macros that should be exported as documentation.
|
||||
|
||||
<a id="cc_action_type"></a>
|
||||
|
||||
## cc_action_type
|
||||
|
||||
<pre>
|
||||
cc_action_type(<a href="#cc_action_type-name">name</a>, <a href="#cc_action_type-action_name">action_name</a>)
|
||||
</pre>
|
||||
|
||||
A type of action (eg. c_compile, assemble, strip).
|
||||
|
||||
[`cc_action_type`](#cc_action_type) rules are used to associate arguments and tools together to
|
||||
perform a specific action. Bazel prescribes a set of known action types that are used to drive
|
||||
typical C/C++/ObjC actions like compiling, linking, and archiving. The set of well-known action
|
||||
types can be found in [@rules_cc//cc/toolchains/actions:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD).
|
||||
|
||||
It's possible to create project-specific action types for use in toolchains. Be careful when
|
||||
doing this, because every toolchain that encounters the action will need to be configured to
|
||||
support the custom action type. If your project is a library, avoid creating new action types as
|
||||
it will reduce compatibility with existing toolchains and increase setup complexity for users.
|
||||
|
||||
Example:
|
||||
```
|
||||
load("@rules_cc//cc:action_names.bzl", "ACTION_NAMES")
|
||||
load("@rules_cc//cc/toolchains:actions.bzl", "cc_action_type")
|
||||
|
||||
cc_action_type(
|
||||
name = "cpp_compile",
|
||||
action_name = = ACTION_NAMES.cpp_compile,
|
||||
)
|
||||
```
|
||||
|
||||
**ATTRIBUTES**
|
||||
|
||||
|
||||
| Name | Description | Type | Mandatory | Default |
|
||||
| :------------- | :------------- | :------------- | :------------- | :------------- |
|
||||
| <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 | |
|
||||
| <a id="cc_action_type-action_name"></a>action_name | - | String | required | |
|
||||
|
||||
|
||||
<a id="cc_action_type_set"></a>
|
||||
|
||||
## cc_action_type_set
|
||||
|
||||
<pre>
|
||||
cc_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>)
|
||||
</pre>
|
||||
|
||||
Represents a set of actions.
|
||||
|
||||
This is a convenience rule to allow for more compact representation of a group of action types.
|
||||
Use this anywhere a [`cc_action_type`](#cc_action_type) is accepted.
|
||||
|
||||
Example:
|
||||
```
|
||||
load("@rules_cc//cc/toolchains:actions.bzl", "cc_action_type_set")
|
||||
|
||||
cc_action_type_set(
|
||||
name = "link_executable_actions",
|
||||
actions = [
|
||||
"@rules_cc//cc/toolchains/actions:cpp_link_executable",
|
||||
"@rules_cc//cc/toolchains/actions:lto_index_for_executable",
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
**ATTRIBUTES**
|
||||
|
||||
|
||||
| Name | Description | Type | Mandatory | Default |
|
||||
| :------------- | :------------- | :------------- | :------------- | :------------- |
|
||||
| <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 | |
|
||||
| <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 | |
|
||||
| <a id="cc_action_type_set-allow_empty"></a>allow_empty | - | Boolean | optional | `False` |
|
||||
|
||||
|
||||
<a id="cc_args_list"></a>
|
||||
|
||||
## cc_args_list
|
||||
|
|
@ -12,7 +88,7 @@ cc_args_list(<a href="#cc_args_list-name">name</a>, <a href="#cc_args_list-args"
|
|||
|
||||
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
|
||||
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.
|
||||
|
||||
|
|
@ -58,6 +134,50 @@ cc_args_list(
|
|||
| <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_tool"></a>
|
||||
|
||||
## cc_tool
|
||||
|
||||
<pre>
|
||||
cc_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>)
|
||||
</pre>
|
||||
|
||||
Declares a tool for use by toolchain actions.
|
||||
|
||||
[`cc_tool`](#cc_tool) rules are used in a [`cc_tool_map`](#cc_tool_map) rule to ensure all files and
|
||||
metadata required to run a tool are available when constructing a `cc_toolchain`.
|
||||
|
||||
In general, include all files that are always required to run a tool (e.g. libexec/** and
|
||||
cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
|
||||
required when certain flags are passed to the tool, consider using a [`cc_args`](#cc_args) rule to
|
||||
bind the files to the flags that require them. This reduces the overhead required to properly
|
||||
enumerate a sandbox with all the files required to run a tool, and ensures that there isn't
|
||||
unintentional leakage across configurations and actions.
|
||||
|
||||
Example:
|
||||
```
|
||||
load("@rules_cc//cc/toolchains:tool.bzl", "cc_tool")
|
||||
|
||||
cc_tool(
|
||||
name = "clang_tool",
|
||||
executable = "@llvm_toolchain//:bin/clang",
|
||||
# Suppose clang needs libc to run.
|
||||
data = ["@llvm_toolchain//:lib/x86_64-linux-gnu/libc.so.6"]
|
||||
tags = ["requires-network"],
|
||||
)
|
||||
```
|
||||
|
||||
**ATTRIBUTES**
|
||||
|
||||
|
||||
| Name | Description | Type | Mandatory | Default |
|
||||
| :------------- | :------------- | :------------- | :------------- | :------------- |
|
||||
| <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 | |
|
||||
| <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` |
|
||||
| <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 | `[]` |
|
||||
| <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 | `[]` |
|
||||
|
||||
|
||||
<a id="cc_args"></a>
|
||||
|
||||
## cc_args
|
||||
|
|
@ -72,13 +192,14 @@ 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`.
|
||||
[`cc_args`](#cc_args) rule that applies an ordered list of arguments to a set of toolchain
|
||||
actions. [`cc_args`](#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
|
||||
difference is that [`cc_args`](#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
|
||||
|
|
@ -90,7 +211,7 @@ load("@rules_cc//cc/toolchains:args.bzl", "cc_args")
|
|||
|
||||
# Basic usage: a trivial flag.
|
||||
#
|
||||
# An example of expressing `-Werror` as a `cc_args` rule.
|
||||
# An example of expressing `-Werror` as a [`cc_args`](#cc_args) rule.
|
||||
cc_args(
|
||||
name = "warnings_as_errors",
|
||||
actions = [
|
||||
|
|
@ -146,21 +267,21 @@ For more extensive examples, see the usages here:
|
|||
| 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-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` |
|
||||
| <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` |
|
||||
| <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-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. | `{}` |
|
||||
| <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` |
|
||||
| <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`](#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`](#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`](#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`](#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`](#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-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` |
|
||||
| <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 |
|
||||
|
||||
|
||||
|
|
@ -173,19 +294,19 @@ cc_nested_args(<a href="#cc_nested_args-name">name</a>, <a href="#cc_nested_args
|
|||
<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.
|
||||
Nested arguments for use in more complex [`cc_args`](#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
|
||||
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.
|
||||
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
|
||||
https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/args/runtime_library_search_directories/BUILD
|
||||
https://github.com/bazelbuild/rules_cc/tree/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.
|
||||
|
|
@ -199,14 +320,14 @@ use this rule.
|
|||
| <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-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. | `{}` |
|
||||
| <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` |
|
||||
| <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`](#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`](#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`](#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`](#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`](#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 |
|
||||
|
||||
|
|
@ -221,11 +342,12 @@ cc_tool_map(<a href="#cc_tool_map-name">name</a>, <a href="#cc_tool_map-tools">t
|
|||
|
||||
A toolchain configuration rule that maps toolchain actions to tools.
|
||||
|
||||
A cc_tool_map aggregates all the tools that may be used for a given toolchain and maps them to
|
||||
their corresponding actions. Conceptually, this is similar to the `CXX=/path/to/clang++`
|
||||
environment variables that most build systems use to determine which tools to use for a given
|
||||
action. To simplify usage, some actions have been grouped together (for example,
|
||||
@rules_cc//cc/toolchains/actions:cpp_compile_actions) to
|
||||
A [`cc_tool_map`](#cc_tool_map) aggregates all the tools that may be used for a given toolchain
|
||||
and maps them to their corresponding actions. Conceptually, this is similar to the
|
||||
`CXX=/path/to/clang++` environment variables that most build systems use to determine which
|
||||
tools to use for a given action. To simplify usage, some actions have been grouped together (for
|
||||
example,
|
||||
[@rules_cc//cc/toolchains/actions:cpp_compile_actions](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/actions/BUILD)) to
|
||||
logically express "all the C++ compile actions".
|
||||
|
||||
In Bazel, there is a little more granularity to the mapping, so the mapping doesn't follow the
|
||||
|
|
@ -262,7 +384,47 @@ Note:
|
|||
| Name | Description | Default Value |
|
||||
| :------------- | :------------- | :------------- |
|
||||
| <a id="cc_tool_map-name"></a>name | (str) The name of the target. | none |
|
||||
| <a id="cc_tool_map-tools"></a>tools | (Dict[target providing ActionTypeSetInfo, Executable target]) A mapping between `cc_action_type` targets and the `cc_tool` or executable target that implements that action. | none |
|
||||
| <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 |
|
||||
| <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 |
|
||||
|
||||
|
||||
<a id="cc_variable"></a>
|
||||
|
||||
## cc_variable
|
||||
|
||||
<pre>
|
||||
cc_variable(<a href="#cc_variable-name">name</a>, <a href="#cc_variable-type">type</a>, <a href="#cc_variable-kwargs">kwargs</a>)
|
||||
</pre>
|
||||
|
||||
Exposes a toolchain variable to use in toolchain argument expansions.
|
||||
|
||||
This internal rule exposes [toolchain variables](https://bazel.build/docs/cc-toolchain-config-reference#cctoolchainconfiginfo-build-variables)
|
||||
that may be expanded in [`cc_args`](#cc_args) or [`cc_nested_args`](#cc_nested_args)
|
||||
rules. Because these varaibles merely expose variables inherrent to Bazel,
|
||||
it's not possible to declare custom variables.
|
||||
|
||||
For a full list of available variables, see
|
||||
[@rules_cc//cc/toolchains/varaibles:BUILD](https://github.com/bazelbuild/rules_cc/tree/main/cc/toolchains/variables/BUILD).
|
||||
|
||||
Example:
|
||||
```
|
||||
load("@rules_cc//cc/toolchains/impl:variables.bzl", "cc_variable")
|
||||
|
||||
# Defines two targets, ":foo" and ":foo.bar"
|
||||
cc_variable(
|
||||
name = "foo",
|
||||
type = types.list(types.struct(bar = types.string)),
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
**PARAMETERS**
|
||||
|
||||
|
||||
| Name | Description | Default Value |
|
||||
| :------------- | :------------- | :------------- |
|
||||
| <a id="cc_variable-name"></a>name | (str) The name of the outer variable, and the rule. | none |
|
||||
| <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 |
|
||||
| <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 |
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue