规则定义了一系列操作，Bazel 会对输入执行以生成一组输出，并以规则的实现函数返回的提供程序中引用这些输出。例如，C++ 二进制规则可以：
- 接受一组
.cpp源文件（输入）。 - 对源文件（操作）运行
g++。 - 返回包含可执行输出和其他文件的
DefaultInfo提供程序，以便在运行时可用。 - 返回
CcInfo提供程序，其中包含从目标及其依赖项收集的特定于 C++ 的信息。
从 Bazel 的角度来看，g++ 和标准 C++ 库也是此规则的输入。作为规则编写器，您不仅必须考虑用户为规则提供的输入，还要考虑执行操作所需的所有工具和库。
在创建或修改任何规则之前，请确保您熟悉 Bazel 的构建阶段。了解构建（加载、分析和执行）的三个阶段非常重要。了解宏也有助于理解规则与宏之间的不同。要开始使用，请先查看规则教程。然后，参考此页面。
一些规则内置在 Bazel 中。这些原生规则（如 cc_library 和 java_binary）为某些语言提供了一些核心支持。通过定义自己的规则，您可以为 Bazel 不提供原生支持的语言和工具添加类似的支持。
Bazel 提供了一个使用 Starlark 语言编写规则的可扩展模型。这些规则采用 .bzl 文件编写，并可直接从 BUILD 文件加载。
在定义自己的规则时，您需要确定它支持哪些属性以及其如何生成其输出。
规则的 implementation 函数定义其在分析阶段的确切行为。此函数不会运行任何外部命令。相反，它会注册执行操作，以供在执行阶段后续需要时用于构建规则的输出（如果需要）。
创建规则
在 .bzl 文件中，使用 rule 函数定义新规则，并将结果存储在全局变量中。调用 rule 可指定属性和实现函数：
example_library = rule(
implementation = _example_library_impl,
attrs = {
"deps": attr.label_list(),
...
},
)
这样可以定义一个名为 example_library 的规则种类。
对 rule 的调用还必须指定规则是创建可执行文件输出（使用 executable=True），还是专门指定测试可执行文件（使用 test=True）。如果规则是测试规则，并且规则的名称必须以 _test 结尾。
目标实例化
规则可以加载并在 BUILD 文件中调用：
load('//some/pkg:rules.bzl', 'example_library')
example_library(
name = "example_target",
deps = [":another_target"],
...
)
每次对构建规则进行调用都不会返回任何值，但这样做会对定义目标产生负面影响。这称为“实例化”规则。它会指定新目标的名称和目标属性的值。
还可以通过 Starlark 函数调用规则并将其加载到 .bzl 文件中。调用规则的 Starlark 函数称为 Starlark 宏。Starlark 宏最终必须从 BUILD 文件调用，并且只能在加载阶段调用，此时必须评估 BUILD 文件以实例化目标。
属性
属性是规则参数。特性可以为目标的实现提供特定值，也可以引用其他目标，从而创建依赖关系图。
如需定义规则专用的属性（例如 srcs 或 deps），需要将属性名称从映射映射到架构（使用 attr 模块创建）到 rule 的 attrs 参数。常见特性（例如 name 和 visibility）会隐式添加到所有规则中。具体来说，其他属性会隐式添加到可执行和测试规则中。隐式添加到规则的属性无法包含在传递给 attrs 的字典中。
依赖项属性
srcs指定由目标的操作处理的源文件。通常，属性架构会指定规则处理的源文件类型需要哪些文件扩展名。对于包含头文件的文件，语言通常会为由目标及其使用方处理的标头指定单独的hdrs属性。deps指定目标的代码依赖项。属性架构应指定这些依赖项必须提供哪些提供程序。（例如，cc_library提供CcInfo。）data会指定在运行时可供任何依赖于目标的文件使用的文件。这应该会允许指定任意文件。
example_library = rule(
implementation = _example_library_impl,
attrs = {
"srcs": attr.label_list(allow_files = [".example"]),
"hdrs": attr.label_list(allow_files = [".header"]),
"deps": attr.label_list(providers = [ExampleInfo]),
"data": attr.label_list(allow_files = True),
...
},
)
以下是依赖项属性的示例。任何指定输入标签的属性（使用 attr.label_list、attr.label 或 attr.label_keyed_string_dict 定义的属性）都指定目标与目标（其标签（或相应的 Label 对象）在定义目标时列在该属性中的目标之间的特定类型依赖项。系统将相对于定义的目标解析这些标签的代码库（可能还有路径）。
example_library(
name = "my_target",
deps = [":other_target"],
)
example_library(
name = "other_target",
...
)
在此示例中，other_target 是 my_target 的依赖项，因此首先会分析 other_target。如果目标的依赖关系图中存在循环，则会导致错误。
私有属性和隐式依赖项
具有默认值的依赖项属性会创建一个隐式依赖项。该变量是隐式的，因为它是用户在 BUILD 文件中未指定的目标图的一部分。隐式依赖项有助于对规则和工具（构建时依赖项，如编译器）之间的关系进行硬编码，因为在大多数情况下，用户都不想指定规则使用的工具。在规则的实现函数内，系统会将其视为与其他依赖项相同的方式。
如果您想提供隐式依赖项，但不允许用户替换该值，可以将属性设为下划线 (_) 作为名称的不公开属性。专用属性必须具有默认值。通常，仅对隐式依赖项使用私有属性才有意义。
example_library = rule(
implementation = _example_library_impl,
attrs = {
...
"_compiler": attr.label(
default = Label("//tools:example_compiler"),
allow_single_file = True,
executable = True,
cfg = "exec",
),
},
)
在此示例中，每个 example_library 类型的目标都依赖于编译器 //tools:example_compiler 。这样，即使用户没有将其标签作为输入传递，example_library 的实现函数也能生成调用编译器的操作。由于 _compiler 是私有属性，因此在此规则类型的所有目标中，ctx.attr._compiler 将始终指向 //tools:example_compiler。或者，您可以将属性命名为 compiler，不带下划线，并保留默认值。这样一来，用户可以在必要时替换其他编译器，但无需了解编译器的标签。
隐式依赖项通常用于与规则实现位于同一代码库的工具。如果该工具来自执行平台或其他代码库，该规则应从工具链获取该工具。
输出特性
输出属性（例如 attr.output 和 attr.output_list）用于声明目标生成的输出文件。它们与依赖项属性有两点不同：
- 它们定义了输出文件目标，而不是引用在其他位置定义的目标。
- 输出文件目标依赖于实例化规则目标，而不是相反。
通常，仅在规则需要使用用户定义的名称（不能基于目标名称）创建输出时使用输出特性。如果规则有一个输出特性，通常命名为 out 或 outs。
输出属性是创建预声明输出的首选方式，可以具体依赖于命令行。
实现函数
每条规则都需要一个 implementation 函数。这些函数严格执行分析阶段，并将加载阶段生成的目标图转换为要在执行阶段执行的操作图表。因此，实现函数实际上无法读取或写入文件。
规则实现函数通常是不公开的（以前导下划线命名）。这些测试的名称通常与规则相同，但以 _impl 为后缀。
实现函数只接受一个参数：规则上下文，通常命名为 ctx。它们会返回一个 providers 列表。
目标
依赖项在分析时表示为 Target 对象。这些对象包含执行目标的实现函数时生成的提供程序。
ctx.attr 包含与每个依赖项属性名称对应的字段，其中包含 Target 对象，这些对象表示通过该属性的每个直接依赖项。对于 label_list 特性，这是一个 Targets 列表。对于 label 属性，请使用单个 Target 或 None。
目标的实现函数会返回提供程序对象的列表：
return [ExampleInfo(headers = depset(...))]
这些索引可以使用索引表示法 ([]) 进行访问，其中提供程序的类型是键。这些提供商可以是 Starlark 中定义的自定义提供程序，或者是可作为 Starlark 全局变量使用的原生代码规则提供程序。
例如，如果规则通过 hdrs 属性接受头文件并将其提供给目标及其使用方的编译操作，则可以采用以下方式收集这些文件：
def _example_library_impl(ctx):
...
transitive_headers = [hdr[ExampleInfo].headers for hdr in ctx.attr.hdrs]
对于从目标的实现函数返回 struct 而不是提供程序对象的列表的旧样式：
return struct(example_info = struct(headers = depset(...)))
可以从 Target 对象的相应字段检索提供程序：
transitive_headers = [hdr.example_info.headers for hdr in ctx.attr.hdrs]
强烈建议不要使用此样式，应停止使用该样式。
文件
文件以 File 对象表示。由于 Bazel 不会在分析阶段执行文件 I/O，因此这些对象不能用于直接读取或写入文件内容。而是会将它们传递给操作发出函数（请参阅 ctx.actions），以构建操作图的各个部分。
File 可以是源文件或生成的文件。每个生成的文件必须是一个操作的输出。源文件不能是任何操作的输出。
对于每个依赖项属性，ctx.files 的相应字段包含通过该属性的所有依赖项的默认输出列表：
def _example_library_impl(ctx):
...
headers = depset(ctx.files.hdrs, transitive=transitive_headers)
srcs = ctx.files.srcs
...
ctx.file 包含规范设为 allow_single_file=True 的依赖项的单个 File 或 None。ctx.executable 的行为与 ctx.file 相同，但只包含规范设置为 executable=True 的依赖项属性的字段。
声明输出
在分析阶段，规则的实现函数可以创建输出。由于所有标签在加载阶段都必须已知，因此这些额外的输出没有标签。您可以使用 ctx.actions.declare_file 和 ctx.actions.declare_directory 创建用于输出的 File 对象。通常，输出的名称基于目标的名称 ctx.label.name：
def _example_library_impl(ctx):
...
output_file = ctx.actions.declare_file(ctx.label.name + ".output")
...
对于预声明的输出（例如为输出属性创建的输出），可以从 ctx.outputs 的相应字段中检索 File 对象。
操作
操作描述如何基于一组输入生成一组输出，例如“在 hello.c 上运行 gcc 并获取 hello.o”。创建操作后，Bazel 不会立即运行该命令。它会在依赖关系图中注册它，因为某项操作可能依赖于其他操作的输出。例如，在 C 中，必须在编译器之后调用链接器。
ctx.actions 中定义了用于创建操作的通用函数：
ctx.actions.run，运行可执行文件。ctx.actions.run_shell，运行 shell 命令。ctx.actions.write，用于将字符串写入文件。ctx.actions.expand_template，用于通过模板生成文件。
ctx.actions.args 可用于高效地累积操作参数。它避免在执行时间之前扁平化依赖项：
def _example_library_impl(ctx):
...
transitive_headers = [dep[ExampleInfo].headers for dep in ctx.attr.deps]
headers = depset(ctx.files.hdrs, transitive=transitive_headers)
srcs = ctx.files.srcs
inputs = depset(srcs, transitive=[headers])
output_file = ctx.actions.declare_file(ctx.label.name + ".output")
args = ctx.actions.args()
args.add_joined("-h", headers, join_with=",")
args.add_joined("-s", srcs, join_with=",")
args.add("-o", output_file)
ctx.actions.run(
mnemonic = "ExampleCompile",
executable = ctx.executable._compiler,
arguments = [args],
inputs = inputs,
outputs = [output_file],
)
...
操作接受输入文件的列表或依赖项，并生成输出文件的列表（非空）。该输入和输出文件组必须在分析阶段已知。它可能依赖于属性的值，包括来自依赖项的提供程序，但不能依赖于执行结果。例如，如果您的操作运行的是解压缩命令，则必须指定预计会膨胀的文件（在运行解压缩之前）。可在内部创建可变数量的文件的操作可以将这些文件封装为一个文件（例如 zip、tar 或其他归档格式）。
操作必须列出其所有输入。允许输入未使用的输入，但效率并不高。
操作必须创建其所有输出。它们可以写入其他文件，但输出中不会包含任何内容。所有声明的输出都必须通过某项操作写入。
操作与纯函数相当：它们应仅依赖于所提供的输入，且避免访问计算机信息、用户名、时钟、网络或 I/O 设备（读取输入和写入输出除外）。这一点很重要，因为输出将缓存并重复使用。
依赖项由 Bazel 解析，Bazel 将决定要执行哪些操作。如果依赖关系图中有循环，则表示存在错误。创建操作并不能保证它会执行，具体取决于 build 是否需要其输出。
提供方
提供方是规则向依赖它的其他规则公开的信息。这些数据可能包含输出文件、库、要在工具的命令行中传递的参数或目标使用方应了解的任何其他信息。
由于规则的实现函数只能从实例化的目标的即时依赖项中读取提供程序，因此规则需要将目标依赖项中需要由目标使用方知道的任何信息转发给它们，通常通过将它们累积到 depset 中。
目标的提供程序由实现函数返回的 Provider 对象列表指定。
旧版实现也可以采用旧版样式编写，其中实现函数会返回 struct 而非提供程序对象列表。强烈建议不要使用此样式，应停止使用该样式。
默认输出
目标的“默认输出”是指在命令行上请求构建目标时默认请求的输出。例如，java_library 目标 //pkg:foo 会将 foo.jar 作为默认输出，因此将通过命令 bazel build //pkg:foo 进行构建。
默认输出由 DefaultInfo 的 files 参数指定：
def _example_library_impl(ctx):
...
return [
DefaultInfo(files = depset([output_file]), ...),
...
]
如果规则实现未返回 DefaultInfo 或 files 参数未指定，则 DefaultInfo.files 默认为所有预先声明的输出（通常是由输出属性创建的输出）。
执行操作的规则应提供默认输出，即使这些输出不应直接使用。系统会剪除请求的输出图表以外的操作。如果输出仅由目标的使用方使用，则在单独构建目标时将不会执行这些操作。这会增加调试的难度，因为仅重新构建失败的目标不会重现失败的情况。
运行文件
运行时文件是目标在运行时使用的一组文件（而不是构建时）。在执行阶段，Bazel 会创建一个目录树，其中包含指向运行文件的符号链接。这会为二进制文件暂存环境，以便它可以在运行时访问运行文件。
您可以在创建规则期间手动添加运行文件。runfiles 对象可以由 runfiles 方法基于规则上下文 ctx.runfiles 创建，并传递给 DefaultInfo 上的 runfiles 参数。可执行规则的可执行输出会隐式添加到运行文件中。
某些规则指定了属性（通常名为 data），其输出会添加到目标的运行文件中。运行的文件还应从 data 以及任何可能为最终执行提供代码的属性合并，通常是 srcs（可能包含关联 data 的 filegroup 目标）和 deps。
def _example_library_impl(ctx):
...
runfiles = ctx.runfiles(files = ctx.files.data)
transitive_runfiles = []
for runfiles_attr in (
ctx.attr.srcs,
ctx.attr.hdrs,
ctx.attr.deps,
ctx.attr.data,
):
for target in runfiles_attr:
transitive_runfiles.append(target[DefaultInfo].default_runfiles)
runfiles = runfiles.merge_all(transitive_runfiles)
return [
DefaultInfo(..., runfiles = runfiles),
...
]
自定义提供程序
您可以使用 provider 函数定义提供程序，以传达特定于规则的信息：
ExampleInfo = provider(
"Info needed to compile/link Example code.",
fields={
"headers": "depset of header Files from transitive dependencies.",
"files_to_link": "depset of Files from compilation.",
})
然后，规则实现函数可以构建并返回提供程序实例：
def _example_library_impl(ctx):
...
return [
...
ExampleInfo(
headers = headers,
files_to_link = depset(
[output_file],
transitive = [
dep[ExampleInfo].files_to_link for dep in ctx.attr.deps
],
),
)
]
自定义提供程序初始化
通过自定义预处理和验证逻辑可以保护提供程序的实例化。这可用于确保所有提供程序实例都遵循某些不变的变体，或者为用户提供更简洁的 API 来获取实例。
将 init 回调传递给 provider 函数，即可完成此操作。如果给出此回调，provider() 的返回类型会变为两个值的元组：未使用 init 时普通返回值的提供程序符号，以及“原始构造函数”。
在这种情况下，调用提供程序符号时，它会将参数沿着 init 回调进行转发，而不是直接返回新实例。回调的返回值必须是将字段名称（字符串）映射到值的字典；此字段用于初始化新实例的字段。请注意，回调可能具有任何签名；如果参数与签名不匹配，则系统会报告错误，就像直接调用回调一样。
相比之下，原始构造函数则会绕过 init 回调。
以下示例使用 init 预处理并验证其参数：
# //pkg:exampleinfo.bzl
_core_headers = [...] # private constant representing standard library files
# It's possible to define an init accepting positional arguments, but
# keyword-only arguments are preferred.
def _exampleinfo_init(*, files_to_link, headers = None, allow_empty_files_to_link = False):
if not files_to_link and not allow_empty_files_to_link:
fail("files_to_link may not be empty")
all_headers = depset(_core_headers, transitive = headers)
return {'files_to_link': files_to_link, 'headers': all_headers}
ExampleInfo, _new_exampleinfo = provider(
...
init = _exampleinfo_init)
export ExampleInfo
然后，规则实现可能会按以下方式实例化提供程序：
ExampleInfo(
files_to_link=my_files_to_link, # may not be empty
headers = my_headers, # will automatically include the core headers
)
原始构造函数可用于定义不通过 init 逻辑的备用公共工厂函数。例如，在 exampleinfo.bzl 中，我们可以定义：
def make_barebones_exampleinfo(headers):
"""Returns an ExampleInfo with no files_to_link and only the specified headers."""
return _new_exampleinfo(files_to_link = depset(), headers = all_headers)
通常，原始构造函数会绑定一个名称以下划线 (_new_exampleinfo) 开头的变量，因此用户代码无法加载该变量并生成任意提供程序实例。
init 的另一个用途是，彻底阻止用户调用提供程序符号，并强制他们改用工厂函数：
def _exampleinfo_init_banned(*args, **kwargs):
fail("Do not call ExampleInfo(). Use make_exampleinfo() instead.")
ExampleInfo, _new_exampleinfo = provider(
...
init = _exampleinfo_init_banned)
def make_exampleinfo(...):
...
return _new_exampleinfo(...)
可执行规则和测试规则
可执行规则定义了可通过 bazel run 命令调用的目标。
测试规则是一种特殊的可执行规则，其目标也可通过 bazel test 命令调用。通过在对 rule 的调用中将相应的 executable 或 test 参数设置为 True，创建了可执行和测试规则：
example_binary = rule(
implementation = _example_binary_impl,
executable = True,
...
)
example_test = rule(
implementation = _example_binary_impl,
test = True,
...
)
测试规则的名称必须以 _test 结尾。（按照惯例，测试目标名称通常也以 _test 结尾，但这不是必需的。）非测试规则不得包含此后缀。
这两种规则必须生成可执行输出文件（不一定会预先声明），这些文件将由 run 或 test 命令调用。如需告知 Bazel 将哪个规则的输出用作此可执行文件，请将其作为返回的 DefaultInfo 提供程序的 executable 参数传递。该 executable 将添加到规则的默认输出中（因此您无需将其传递给 executable 和 files）。它还隐式添加到 runfiles：
def _example_binary_impl(ctx):
executable = ctx.actions.declare_file(ctx.label.name)
...
return [
DefaultInfo(executable = executable, ...),
...
]
生成此文件的操作必须设置该文件上的可执行位。对于 ctx.actions.run 或 ctx.actions.run_shell 操作，操作应由该操作调用的底层工具来完成。对于 ctx.actions.write 操作，请传递 is_executable=True。
作为旧版行为，可执行规则具有一个特殊的 ctx.outputs.executable 预声明输出。如果您不使用 DefaultInfo 指定某个文件，则此文件将用作默认可执行文件；否则，不能使用该文件。此输出机制已弃用，因为它不支持在分析时自定义可执行文件的名称。
可执行文件规则和测试规则除了为所有规则添加的属性外，还隐式定义了其他属性。隐式添加的默认值无法更改，但可以通过将私有规则封装在会更改默认值的 Starlark 宏中来解决此问题：
def example_test(size="small", **kwargs):
_example_test(size=size, **kwargs)
_example_test = rule(
...
)
运行文件位置
当使用 bazel run（或 test）运行可执行文件目标时，runfiles 目录的根目录靠近可执行文件。路径如下：
# Given launcher_path and runfile_file:
runfiles_root = launcher_path.path + ".runfiles"
workspace_name = ctx.workspace_name
runfile_path = runfile_file.short_path
execution_root_relative_path = "%s/%s/%s" % (
runfiles_root, workspace_name, runfile_path)
runfiles 目录下的 File 路径对应于 File.short_path。
由 bazel 直接执行的二进制文件毗邻 runfiles 目录的根目录。但是，从运行文件调用的二进制文件无法做出相同的假设。为了缓解此问题，每个二进制文件都应提供一种方法来使用环境或命令行参数/标志将其 runfiles 根作为参数接受。这样，二进制文件就可以将正确的规范运行文件根传递给它调用的二进制文件。如果未设置，二进制文件可以推测它是第一个调用的二进制文件，并查找相邻的 runfiles 目录。
高级主题
请求输出文件
一个目标可以有多个输出文件。运行 bazel build 命令时，为该命令指定的目标的某些输出会被视为请求。Bazel 仅构建这些请求的文件和它们直接或间接依赖的文件。（在操作图中，Bazel 仅执行可通过所请求文件的传递依赖项到达的操作。）
除了默认输出之外，您也可以在命令行中明确请求任何预声明的输出。规则可以通过输出属性指定预输出。在这种情况下，用户可以在实例化规则时明确选择输出标签。如需获取输出属性的 File 对象，请使用 ctx.outputs 的相应属性。规则也可以根据目标名称隐式定义预声明的输出，但此功能已废弃。
除了默认输出之外，还有输出组，即可一起请求的输出文件的集合。您可以使用 --output_groups 请求这些凭据。例如，如果目标 //pkg:mytarget 所属的规则类型具有 debug_files 输出组，则可以通过运行 bazel build //pkg:mytarget
--output_groups=debug_files 构建这些文件。由于未预先声明的输出没有标签，因此只能通过出现在默认输出或输出组中进行请求。
您可以使用 OutputGroupInfo 提供程序指定输出组。请注意，与许多内置提供程序不同，OutputGroupInfo 可以接受具有任意名称的参数来定义该名称的输出组：
def _example_library_impl(ctx):
...
debug_file = ctx.actions.declare_file(name + ".pdb")
...
return [
DefaultInfo(files = depset([output_file]), ...),
OutputGroupInfo(
debug_files = depset([debug_file]),
all_files = depset([output_file, debug_file]),
),
...
]
此外，与大多数提供程序不同，OutputGroupInfo 可由符合该方面的规则及目标平台返回，但前提是它们不能定义相同的输出组。在这种情况下，系统会合并生成的提供程序。
请注意，OutputGroupInfo 通常不应用来将特定类型的文件从目标传递给其使用方的操作。而应定义特定于规则的提供程序。
配置
假设您想为其他架构构建 C++ 二进制文件。此 build 可能很复杂并且涉及多个步骤。一些中间二进制文件（如编译器和代码生成器）必须在执行平台（可以是您的主机或远程执行程序）上运行。某些二进制文件（例如最终输出）必须为目标架构构建。
因此，Bazel 具有“配置”和过渡的概念。最顶层的目标（在命令行中请求的目标）构建于“目标”配置中，而应在执行平台上运行的工具则构建于“执行”配置中。规则可以根据配置生成不同的操作，例如，更改传递给编译器的 CPU 架构。在某些情况下，不同的配置可能需要使用相同的库。如果发生这种情况，系统会对其进行分析并可能会多次构建。
默认情况下，Bazel 会在与目标本身相同的配置中构建目标的依赖项，即不使用转换。当依赖项是帮助构建目标所需的工具时，相应属性应指定转换为执行配置。这会使该工具及其所有依赖项都会针对执行平台进行构建。
对于每个依赖项特性，您都可以使用 cfg 来决定依赖项应采用相同的配置进行构建，还是应转换为执行配置。如果依赖项特性具有 executable=True 标志，则必须明确设置 cfg。这是为了防止意外为错误的配置构建工具。查看示例
一般来说，运行时需要的源代码、依赖库和可执行文件可以使用相同的配置。
作为构建的一部分执行的工具（例如编译器或代码生成器）应该用于执行。在这种情况下，请在特性中指定 cfg="exec"。
否则，应在运行时为目标配置构建可执行文件（例如测试的一部分）。在这种情况下，请在特性中指定 cfg="target"。
实际上，cfg="target" 不会执行任何操作：它只是一条便捷值，旨在帮助规则设计人员明确说明自己的意图。如果 executable=False 表示 cfg 是可选的，则只有在真正有助于提高可读性时才设置此参数。
您还可以使用 cfg=my_transition 来使用用户定义的转换，这使得规则作者在更改配置时具有很高的灵活性，但缺点是使构建图增大了且更易于理解。
注意：过去，Bazel 没有执行平台的概念，因此所有构建操作都被视为在主机上运行。6.0 之前的 Bazel 版本创建了一个不同的“主机”配置来表示这一点。如果您在代码或旧文档中看到对“host”的引用，这指的是引用。我们建议使用 Bazel 6.0 或更高版本，以避免这种额外的概念性开销。
配置 fragment
规则可以访问配置 fragment，如 cpp、java 和 jvm。但是，必须声明所有必需的 fragment 以避免访问错误：
def _impl(ctx):
# Using ctx.fragments.cpp leads to an error since it was not declared.
x = ctx.fragments.java
...
my_rule = rule(
implementation = _impl,
fragments = ["java"], # Required fragments of the target configuration
host_fragments = ["java"], # Required fragments of the host configuration
...
)
运行文件符号链接
通常，runfiles 树中文件的相对路径与该文件在源代码树或生成的输出树中的相对路径相同。如果出于某种原因需要不同，可以指定 root_symlinks 或 symlinks 参数。root_symlinks 是映射到路径的字典路径，其中路径是相对于 runfiles 目录的根目录。symlinks 字典是相同的，但路径隐式带有主工作区的名称（而不是包含当前目标的代码库的名称）。
...
runfiles = ctx.runfiles(
root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2}
symlinks = {"some/path/here.bar": ctx.file.some_data_file3}
)
# Creates something like:
# sometarget.runfiles/
# some/
# path/
# here.foo -> some_data_file2
# <workspace_name>/
# some/
# path/
# here.bar -> some_data_file3
如果使用 symlinks 或 root_symlinks，请注意不要将两个不同的文件映射到 runfiles 树中的同一路径。这会导致构建失败，并显示描述冲突的错误。如需修复此冲突，您需要修改 ctx.runfiles 参数以移除冲突。系统将针对使用规则的任何目标以及依赖于这些目标的任何类型的目标进行这项检查。如果您的工具可能被另一个工具以传递方式使用，则风险极高；符号链接名称在工具的运行时文件及其所有依赖项中必须是唯一的。
代码覆盖率
运行 coverage 命令时，build 可能需要为特定目标添加覆盖率插桩。该 build 还会收集已进行插桩的源文件列表。所考虑的目标的子集由标志 --instrumentation_filter 控制。除非指定了 --instrument_test_targets，否则会排除测试目标。
如果规则实现在构建时添加覆盖率插桩，则需要在实现函数中考虑到这一点。如果应针对目标的来源进行插桩，ctx.coverage_instrumented 便会在覆盖率模式下返回 true：
# Are this rule's sources instrumented?
if ctx.coverage_instrumented():
# Do something to turn on coverage for this compile action
需要始终在覆盖率模式下开启的逻辑（无论目标的来源是否经过插桩）可以在 ctx.configuration.coverage_enabled 上进行调整。
如果规则在编译之前直接包含其依赖项中的源代码（例如头文件），那么在依赖项的来源进行插桩时，可能还需要启用编译时插桩：
# Are this rule's sources or any of the sources for its direct dependencies
# in deps instrumented?
if (ctx.configuration.coverage_enabled and
(ctx.coverage_instrumented() or
any([ctx.coverage_instrumented(dep) for dep in ctx.attr.deps]))):
# Do something to turn on coverage for this compile action
规则还应提供有关哪些属性与 InstrumentedFilesInfo 提供方的覆盖率相关的信息（使用 coverage_common.instrumented_files_info 进行构建）。instrumented_files_info 的 dependency_attributes 参数应列出所有运行时依赖项属性，包括 deps 等代码依赖项以及 data 等数据依赖项。如果可以添加覆盖率插桩，source_attributes 参数应列出规则的源文件属性：
def _example_library_impl(ctx):
...
return [
...
coverage_common.instrumented_files_info(
ctx,
dependency_attributes = ["deps", "data"],
# Omitted if coverage is not supported for this rule:
source_attributes = ["srcs", "hdrs"],
)
...
]
如果未返回 InstrumentedFilesInfo，系统会使用 dependency_attributes 中未将 cfg 设置为 "host" 或 "exec" 的每个非工具依赖项属性创建默认属性。（这并不是理想的行为，因为它在 dependency_attributes 中放入了 srcs 等属性，而不是 source_attributes，但避免了对依赖项链中的所有规则进行显式覆盖率配置。）
验证操作
有时您需要验证关于 build 的某些信息，而验证所需的信息仅在工件（源文件或生成的文件）中提供。由于此信息位于工件中，因此规则无法在分析时执行此验证，因为规则无法读取文件。相反，操作必须在执行时执行此验证。如果验证失败，操作将失败，因此构建也会失败。
可以运行的验证示例包括静态分析、lint 检查、依赖项和一致性检查以及样式检查。
此外，验证操作还可以将构建工件不需要的部分操作移至单独的操作，从而有助于提升构建性能。例如，如果将进行编译和 lint 的单个操作拆分为编译操作和 lint 操作，则可以将 lint 操作作为验证操作运行，并与其他操作并行运行。
这些“验证操作”通常不会生成 build 中其他地方使用的任何内容，因为它们只需要断言输入的内容。但这会带来一个问题：如果验证操作未生成 build 中其他位置使用的任何内容，规则如何让该操作运行？过去，这种方法是让验证操作输出空文件，并人为地将构建输出添加到 build 中其他重要操作的输入：
之所以行得通，是因为 Bazel 始终会在运行编译操作时运行验证操作，但这样做有很大的缺点：
验证操作位于 build 的关键路径中。由于 Bazel 认为运行编译操作需要空白输出，因此它会首先运行验证操作，即使编译操作会忽略输入也是如此。这样可以减少并行性并减慢构建速度。
如果 build 中的其他操作可以代替编译操作运行，则需要将验证操作的空输出也添加到这些操作（例如，
java_library的源 jar 输出）中。如果在以后添加了可能会运行的新编译操作（而不是编译操作），并且意外删除了空的验证输出，也会出现此问题。
这些问题的解决方法是使用验证输出组。
验证输出组
验证输出组是一个输出组，用于保存以其他方式使用的验证操作输出，因此无需人为地添加到其他操作的输入中。
这个组非常特殊，因为它始终请求其输出，无论 --output_groups 标志的值是什么，也不管目标如何依赖（例如，通过命令行、作为依赖项或通过目标的隐式输出）。请注意，正常的缓存和增量仍然适用：如果验证操作的输入未更改，而验证操作之前成功，则验证操作将不会运行。
使用此输出组时，验证操作仍会输出一些文件，即使空文件也是如此。这可能需要封装一些通常不会创建输出的工具，以便创建文件。
在三种情况下，系统不会运行目标的验证操作：
- 目标作为工具依赖的时间
- 当目标作为隐式依赖项依赖时（例如，以“_”开头的属性）
- 当目标在主机或执行配置中构建时。
这些目标有自己的构建和测试，它们可以发现任何验证失败问题。
使用 Validations 输出组
验证输出组名为 _validation，并且像使用任何其他输出组一样使用：
def _rule_with_validation_impl(ctx):
ctx.actions.write(ctx.outputs.main, "main output\n")
ctx.actions.write(ctx.outputs.implicit, "implicit output\n")
validation_output = ctx.actions.declare_file(ctx.attr.name + ".validation")
ctx.actions.run(
outputs = [validation_output],
executable = ctx.executable._validation_tool,
arguments = [validation_output.path])
return [
DefaultInfo(files = depset([ctx.outputs.main])),
OutputGroupInfo(_validation = depset([validation_output])),
]
rule_with_validation = rule(
implementation = _rule_with_validation_impl,
outputs = {
"main": "%{name}.main",
"implicit": "%{name}.implicit",
},
attrs = {
"_validation_tool": attr.label(
default = Label("//validation_actions:validation_tool"),
executable = True,
cfg = "exec"),
}
)
请注意，验证输出文件不会添加到 DefaultInfo 中，也不会添加到任何其他操作的输入中。如果目标按标签依赖，或者目标的任何隐式输出直接或间接依赖于，则此规则类型的目标验证操作仍将运行。
通常情况下，请务必将验证操作的输出仅输入验证输出组，而不添加到其他操作的输入中，否则可能会破坏并行性。但请注意，Bazel 目前没有执行任何特殊检查。因此，您应测试验证操作输出是否不会添加到 Starlark 规则测试的任何操作的输入中。例如：
load("@bazel_skylib//lib:unittest.bzl", "analysistest")
def _validation_outputs_test_impl(ctx):
env = analysistest.begin(ctx)
actions = analysistest.target_actions(env)
target = analysistest.target_under_test(env)
validation_outputs = target.output_groups._validation.to_list()
for action in actions:
for validation_output in validation_outputs:
if validation_output in action.inputs.to_list():
analysistest.fail(env,
"%s is a validation action output, but is an input to action %s" % (
validation_output, action))
return analysistest.end(env)
validation_outputs_test = analysistest.make(_validation_outputs_test_impl)
验证操作标志
运行验证操作由 --run_validations 命令行标志（默认为 true）控制。
已弃用的功能
已废弃预声明的输出
使用预声明输出的方法有两种已弃用：
rule的outputs参数指定输出属性名称与字符串模板之间的映射，用于生成预先声明的输出标签。首选使用非预先声明的输出，并将输出明确添加到DefaultInfo.files。请使用规则目标的标签，作为使用输出（而非预先声明的输出的标签）的规则的输入。对于可执行规则，
ctx.outputs.executable是指与规则目标同名的预声明可执行输出。最好明确声明输出（例如使用ctx.actions.declare_file(ctx.label.name)），并确保生成可执行文件的命令将设置其权限以允许执行。将可执行输出显式传递给DefaultInfo的executable参数。
要运行的 Runfile 功能
ctx.runfiles 和 runfiles 类型具有一组复杂的功能，其中许多功能都是出于旧版原因保留的。以下建议有助于降低复杂性：
避免使用
ctx.runfiles的collect_data和collect_default模式。这些模式会以难以理解的方式隐式收集某些硬编码的依赖项边缘的运行文件。相反，您可以使用ctx.runfiles的files或transitive_files参数，或通过使用runfiles = runfiles.merge(dep[DefaultInfo].default_runfiles)从依赖项合并运行文件来添加文件。避免使用
DefaultInfo构造函数的data_runfiles和default_runfiles。改为指定DefaultInfo(runfiles = ...)。出于默认原因，系统会保留“default”和“data”运行文件之间的区别。例如，某些规则将其默认输出置于data_runfiles中，而非default_runfiles中。规则应既包含默认输出，也从提供运行文件的属性（通常是data）中合并到default_runfiles。data_runfiles从
DefaultInfo检索runfiles（通常仅用于合并当前规则及其依赖项之间的运行文件）时，请使用DefaultInfo.default_runfiles，而不是DefaultInfo.data_runfiles。
从旧版提供商迁移
过去，Bazel 提供程序是 Target 对象上的简单字段。可以使用点运算符访问这些字段，它们是通过将字段放入由规则的实现函数返回的结构体创建的。
此样式已废弃，请勿在新代码中使用；请参阅下文，了解可能有助于您迁移的信息。新的提供程序机制可避免名称冲突。此外，它还支持数据隐藏，即要求访问提供程序实例的任何代码均可使用提供程序符号进行检索。
目前，旧版提供商仍然受支持。规则可以返回旧版提供方和现代提供方，如下所示：
def _old_rule_impl(ctx):
...
legacy_data = struct(x="foo", ...)
modern_data = MyInfo(y="bar", ...)
# When any legacy providers are returned, the top-level returned value is a
# struct.
return struct(
# One key = value entry for each legacy provider.
legacy_info = legacy_data,
...
# Additional modern providers:
providers = [modern_data, ...])
如果 dep 是此规则的实例生成的 Target 对象，提供程序及其内容可检索为 dep.legacy_info.x 和 dep[MyInfo].y。
除了 providers 之外，返回的结构体还可以采用几个具有特殊含义的字段（因此不会创建相应的旧版提供程序）：
字段
files、runfiles、data_runfiles、default_runfiles和executable对应于DefaultInfo的同名字段。在返回DefaultInfo提供程序时，不允许指定其中任何字段。output_groups字段接受结构体值，并对应于OutputGroupInfo。
在规则的 provides 声明和 providers 依赖项声明中，旧版提供程序会作为字符串传入，而现代提供程序则通过 *Info 符号传入。迁移时，请务必从字符串更改为符号。对于难以以原子方式更新所有规则的复杂或大型规则集，遵循以下一系列步骤可能会更容易：
使用上述语法修改生成旧版提供程序的规则，以生成旧版提供程序和现代提供程序。对于声明返回旧版提供程序的规则，请更新该声明，使之包含旧版提供程序和现代提供程序。
修改使用旧版提供程序的规则，以改用现代提供程序。如果任何属性声明需要旧版提供程序，也请更新它们以需要现代提供程序。或者，您可以通过让使用方接受/要求使用任一提供方来交替执行第 1 步：使用
hasattr(target, 'foo')测试是否存在旧版提供方，或使用FooInfo in target测试新提供方是否存在。从所有规则中完全移除旧版提供商。