规则
别名
查看规则来源alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias 规则会创建另一个可以在规则中引用的名称。
混叠仅适用于“常规”目标。特别是，package_group 和 test_suite 不能别名。
在大型代码库中，如果重命名目标，将需要更改大量文件，因此采用别名可能会有所帮助。如果您想对多个目标重复使用该逻辑，还可以使用别名规则来存储 select 函数调用。
别名规则有自己的可见性声明。在所有其他方面，它的行为与其引用的规则类似（例如，“testonly on the alias”会被忽略；系统会改用所引用规则的 testonly-ness），但也有一些例外情况：
-
如果命令行中提到了测试的别名，则测试不会运行。如需定义运行所引用测试的别名，请使用
tests属性中具有单个目标的test_suite规则。 -
定义环境组时，不支持
environment规则的别名。它们在--target_environment命令行选项中也不受支持。
示例
filegroup(
name = "data",
srcs = ["data.txt"],
)
alias(
name = "other",
actual = ":data",
)
参数
| 属性 | |
|---|---|
name |
名称（必需） 此目标的唯一名称。 |
actual
|
标签（必需） 此别名所指的目标。它不必是规则，也可以是输入文件。 |
config_setting
查看规则来源config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)
为触发可配置属性而匹配预期的配置状态（以 build 标志或平台限制条件的形式表示）。如需简要了解一般功能，请参阅 select 了解如何使用此规则和 可配置属性。
示例
以下命令与设置了 --compilation_mode=opt 或 -c opt（在命令行中以显式方式或从 .bazelrc 文件中隐式）的任何 build 匹配：
config_setting(
name = "simple",
values = {"compilation_mode": "opt"}
)
以下命令会匹配以 ARM 为目标平台并应用自定义 FOO=bar（例如 bazel build --cpu=arm --define FOO=bar ...）的任何 build：
config_setting(
name = "two_conditions",
values = {
"cpu": "arm",
"define": "FOO=bar"
}
)
以下命令与设置了用户定义的标志
--//custom_flags:foo=1（在命令行中明确显示或从 .bazelrc 文件中隐式设置）的任何 build 匹配：
config_setting(
name = "my_custom_flag_is_set",
flag_values = { "//custom_flags:foo": "1" },
)
以下代码与针对具有 x86_64 架构和 glibc 版本 2.25 的平台的任何 build 匹配（假设存在带有标签 //example:glibc_2_25 的 constraint_value）。请注意，如果平台定义了超出这两个值的额外约束值，则平台仍然匹配。
config_setting(
name = "64bit_glibc_2_25",
constraint_values = [
"@platforms//cpu:x86_64",
"//example:glibc_2_25",
]
)
在所有这些情况下，配置可能会在 build 中发生变化（例如，如果需要为与其依赖项不同的平台构建目标）。这意味着，即使 config_setting 与顶级命令行标志不匹配，它仍可能与某些构建目标匹配。
备注
- 如需了解当多个
config_setting与当前配置状态匹配时会发生什么情况，请参阅 select。 - 对于支持简写形式（例如
--compilation_mode与-c）的标志，values定义必须使用完整形式。它们会自动使用任一形式匹配调用。 -
如果某个标志接受多个值（如
--copt=-Da --copt=-Db或列表类型的 Starlark 标志），则当"a"存在于实际列表中的任意位置时，values = { "flag": "a" }会匹配。values = { "myflag": "a,b" }的工作原理相同：这匹配--myflag=a --myflag=b、--myflag=a --myflag=b --myflag=c、--myflag=a,b和--myflag=c,b,a。标记的确切语义有所不同。例如，--copt不支持在同一实例中使用多个值：--copt=a,b会生成["a,b"]，而--copt=a --copt=b会生成["a", "b"]（因此values = { "copt": "a,b" }与前一个匹配，而不匹配后一个）。但--ios_multi_cpus（适用于 Apple 规则）会：-ios_multi_cpus=a,b和ios_multi_cpus=a --ios_multi_cpus=b都会生成["a", "b"]。请检查标志定义并仔细检查您的条件，以验证确切的预期结果。 - 如果您需要定义并非由内置构建标志建模的条件，请使用
Starlark 定义的标志。您也可以使用
--define，但这提供的支持功能较差，因此不推荐使用。如需查看更多讨论，请点击此处。 - 避免在不同软件包中重复相同的
config_setting定义。请改为引用规范软件包中定义的常用config_setting。 values、define_values和constraint_values可以在同一个config_setting中以任意组合使用，但必须至少为任何给定的config_setting设置一个组合。
参数
| 属性 | |
|---|---|
name |
名称（必需） 此目标的唯一名称。 |
constraint_values
|
目标平台为了匹配此 config_setting 而必须指定的最小 constraint_values 集。（此处未考虑执行平台。）平台已忽略的所有其他限制条件值都会被忽略。如需了解详情，请参阅
可配置的 build 属性。
如果两个 |
define_values
|
字典：String -> String；不可配置；默认值为 values 相同，但专门用于 --define 标志。
这意味着：
config_setting(
name = "a_and_b",
values = {
"define": "a=1",
"define": "b=2",
})
不起作用，因为相同的键 (
config_setting(
name = "a_and_b",
define_values = {
"a": "1",
"b": "2",
})
与
|
flag_values
|
字典：label -> 字符串；不可配置；默认值为 values 相同，但用于
用户定义的构建标志。
这是一个不同的属性，因为用户定义的标志作为标签引用，而内置标志作为任意字符串引用。 |
values
|
字典：String -> String；不可配置；默认值为 此规则会继承在 为方便起见，将配置值指定为构建标记（不带前面的 如果未在命令行中明确设置标志，则使用其默认值。如果某个键在字典中多次出现，则仅使用最后一个实例。
如果密钥引用可在命令行中多次设置的标志（例如
|
文件组
查看规则来源filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)
使用 filegroup 为目标集合指定一个方便的名称。然后，可以从其他规则引用这些规则。
建议使用 filegroup，而不是直接引用目录。后一种方式不可靠，因为编译系统并不完全了解目录下的所有文件，因此在这些文件发生更改时可能不会重新编译。与 glob 结合使用时，filegroup 可确保编译系统明确知道所有文件。
示例
如需创建由两个源文件组成的 filegroup，请执行以下操作：
filegroup(
name = "mygroup",
srcs = [
"a_file.txt",
"some/subdirectory/another_file.txt",
],
)
或者，使用 glob 调整 testdata 目录：
filegroup(
name = "exported_testdata",
srcs = glob([
"testdata/*.dat",
"testdata/logs/**/*.log",
]),
)
如需使用这些定义，请使用任意规则中的标签引用 filegroup：
cc_library(
name = "my_library",
srcs = ["foo.cc"],
data = [
"//my_package:exported_testdata",
"//my_package:mygroup",
],
)
参数
| 属性 | |
|---|---|
name |
名称（必需） 此目标的唯一名称。 |
srcs
|
标签列表；默认值为
通常使用 glob 表达式的结果作为 |
data
|
标签列表；默认值为
|
output_group
|
字符串；默认值为 “输出组”是目标的输出工件类别，在该规则的实现中指定。 |
Genquery
查看规则来源genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)
genquery() 运行以 Blaze 查询语言指定的查询，并将结果转储到一个文件中。
为了确保 build 的一致性，查询只允许访问 scope 属性中指定的目标的传递闭包。如果 strict 未指定或 true，则违反此规则的查询将在执行期间失败（如果 strict 为 false，系统会跳过超出范围的目标，并发出警告）。若要避免发生这种情况，最简单的方法是在范围中提及与查询表达式相同的标签。
此处允许的查询与命令行上允许的查询之间的唯一区别是，此处不允许使用包含通配符目标规范（例如 //pkg:* 或 //pkg:all）的查询。原因有两个：首先，genquery 必须指定一个范围来防止查询的传递闭包之外的目标影响其输出；其次，因为 BUILD 文件不支持通配符依赖项（例如，不允许使用 deps=["//a/..."]）。
genquery 的输出按字典顺序排序，以强制执行确定性输出，--output=graph|minrank|maxrank 或 somepath 用作顶级函数时除外。
输出文件的名称就是规则的名称。
示例
此示例将指定目标的传递闭包中的标签列表写入一个文件中。
genquery(
name = "kiwi-deps",
expression = "deps(//kiwi:kiwi_lib)",
scope = ["//kiwi:kiwi_lib"],
)
参数
| 属性 | |
|---|---|
name |
名称（必需） 此目标的唯一名称。 |
compressed_output
|
布尔值；默认值为 True，则查询输出将以 GZIP 文件格式编写。当查询输出预计会很大时，此设置可用于避免 Bazel 的内存使用量激增。无论此设置的值如何，Bazel 已在内部压缩超过 220 个字节的查询输出，因此，将其设置为 True 可能不会减少保留的堆。但是，它允许 Bazel 在写入输出文件时跳过解压缩，压缩过程可能会占用大量内存。 |
expression
|
字符串；必需 要执行的查询。与命令行和 BUILD 文件中的其他位置不同，此处的标签相对于工作区的根目录进行解析。例如，文件a/BUILD 中此属性中的标签 :b 将引用目标 //:b。
|
opts
|
字符串列表；默认值为 bazel query 的命令行选项。此处不允许使用某些查询选项：--keep_going、--query_file、--universe_scope、--order_results 和 --order_output。未在此处指定的选项将使用其默认值，与 bazel query 命令行上的值类似。
|
scope
|
标签列表（必需） 查询的范围。不允许查询轻触这些目标的传递闭合范围之外的目标。 |
strict
|
布尔值；默认值为 |
Genrule
查看规则来源genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)
genrule 使用用户定义的 Bash 命令生成一个或多个文件。
Genrule 是通用构建规则，如果没有适用于相应任务的特定规则，则可以使用它们。例如，您可以运行 Bash 一行代码。不过，如果您需要编译 C++ 文件，请遵循现有的 cc_* 规则，因为所有繁杂的工作已经为您完成。
请注意，genrule 需要 shell 来解释命令参数。引用 PATH 上提供的任意程序也很容易，但这会使命令非封闭，并且可能无法重现。 如果您只需运行单个工具，请考虑使用 run_binary。
请勿使用 Genrule 来运行测试。针对测试和测试结果（包括缓存政策和环境变量）有一些特殊限制。测试通常需要在构建完成后在目标架构上运行，而 genrule 是在构建期间以及在 exec 架构上执行的（两者可能不同）。如果您需要通用测试规则，请使用 sh_test。
交叉编译注意事项
如需详细了解交叉编译，请参阅用户手册。
虽然 Genrule 在构建期间运行，但其输出通常在构建之后用于部署或测试。请考虑为微控制器编译 C 代码的示例：编译器接受 C 源文件并生成在微控制器上运行的代码。生成的代码显然无法在用于构建代码的 CPU 上运行，但 C 编译器（如果从源代码编译的话）本身必须运行。
构建系统使用 exec 配置来描述运行 build 的机器，使用目标配置来描述应运行 build 输出的计算机。它提供了用于配置上述各项的选项，并将相应的文件隔离到单独的目录中以避免冲突。
对于 Genrule，构建系统可确保正确构建依赖项：针对 target 配置构建 srcs（如有必要），tools 针对 exec 配置构建，输出被视为针对 target 配置。此外，它还提供
“Make”变量，genrule 命令可将其传递给相应工具。
Genrule 有意不定义任何 deps 属性：其他内置规则使用规则之间传递的与语言相关的元信息自动确定如何处理从属规则，但这种级别的自动化不适用于 Genrule。Genrule 仅在文件级别和 runfile 级别工作。
特殊情况
Exec-exec 编译：在某些情况下，编译系统需要运行 genrule，以便也可在编译期间执行输出。例如，如果某个 genrule 构建了一个自定义编译器，随后又被另一个 genrule 使用，则第一个 genrule 必须为 exec 配置生成其输出，因为编译器将在另一个 genrule 中运行该编译器。在这种情况下，构建系统会自动执行正确的操作：为 exec 配置（而不是目标配置）构建第一代规则的 srcs 和 outs。如需了解详情，请参阅用户手册。
JDK 和 C++ 工具：如需使用 JDK 或 C++ 编译器套件中的工具，构建系统提供一组要使用的变量。如需了解详情，请参阅“Make”变量。
Genrule 环境
genrule 命令由使用 set -e -o pipefail 配置为在命令或流水线失败时失败的 Bash shell 执行。
构建工具会在已清理的进程环境中执行 Bash 命令，该环境仅定义了核心变量，如 PATH、PWD、TMPDIR 以及其他一些变量。为了确保构建可重现，用户 shell 环境中定义的大多数变量都不会传递到 genrule 的命令。但是，Bazel（而不是 Blaze）会传递用户的 PATH 环境变量的值。对 PATH 的值所做的任何更改都会导致 Bazel 在下一次构建时重新执行该命令。
除了连接属于该命令本身的子进程的进程外，genrule 命令不应访问网络（尽管目前未强制执行）。
构建系统会自动删除所有现有的输出文件，但会在运行 Genrule 之前创建所有必要的父目录。如果失败了，此配置还会移除所有输出文件。
一般建议
- 确保由 Genrule 运行的工具具有确定性和封闭性。它们不应将时间戳写入其输出，而应为集和映射使用稳定的排序，并且只写入输出的相对文件路径（不写入绝对路径）。不遵循此规则将导致意外的构建行为（Bazel 不会重新构建您原本认为会的 genrule），并降低缓存性能。
- 对于输出、工具和源代码，广泛使用
$(location)。由于为不同配置隔离输出文件，genrule 不能依赖于硬编码和/或绝对路径。 - 请务必编写一个常见的 Starlark 宏，以防在多个位置使用相同或非常相似的 Genrule。如果 Genrule 很复杂，请考虑通过脚本或 Starlark 规则来实现。这可以提高可读性和可测试性。
- 确保退出代码正确指示 Genrule 是成功还是失败。
- 请勿将信息性消息写入 stdout 或 stderr。虽然这对于调试很有用，但很容易变成噪音；成功的 Genrule 应该是静音的。另一方面，失败的 Genrule 应发出良好的错误消息。
$$evaluates to a$, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such asls $(dirname $x), one must escape it thus:ls $$(dirname $$x).- 避免创建符号链接和目录。Bazel 不会复制 genrule 创建的目录/符号链接结构，并且其目录依赖项检查不可靠。
- 在其他规则中引用 Genrule 时，您可以使用 genrule 的标签或各个输出文件的标签。有时，一种方法更具可读性，有时另一种方法则是：在使用方规则的
srcs中按名称引用输出可以避免无意中提取 genrule 的其他输出，但如果 genrule 会生成许多输出，则可能会很繁琐。
示例
此示例生成 foo.h。没有任何来源，因为该命令不接受任何输入。该命令运行的“二进制文件”是 genrule 所在软件包中的 perl 脚本。
genrule(
name = "foo",
srcs = [],
outs = ["foo.h"],
cmd = "./$(location create_foo.pl) > \"$@\"",
tools = ["create_foo.pl"],
)
以下示例展示了如何使用 filegroup
以及另一个 genrule 的输出。请注意，使用 $(SRCS)（而非显式 $(location) 指令）也可正常运作；本示例使用后者是为了进行演示。
genrule(
name = "concat_all_files",
srcs = [
"//some:files", # a filegroup with multiple files in it ==> $(locations)
"//other:gen", # a genrule with a single output ==> $(location)
],
outs = ["concatenated.txt"],
cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)
参数
| 属性 | |
|---|---|
name |
名称（必需） 此目标的唯一名称。 您可以在其他 BUILD 规则的 srcs 或 deps 部分中通过名称引用此规则。如果规则生成源文件，则应使用 srcs 属性。
|
srcs
|
标签列表；默认值为
此属性不适合列出由
构建系统可确保在运行 genrule 命令之前构建这些前提条件；它们使用与原始构建请求相同的配置构建。满足这些前提条件的文件的名称在 |
outs
|
此规则生成的文件的列表。
输出文件不得跨越软件包边界。输出文件名被解释为相对于软件包的名称。
如果设置了
genrule 命令应在预定位置创建每个输出文件。在 |
cmd
|
字符串；默认值为 $(location)
和 “Make”变量。
cmd_bash、cmd_ps 和 cmd_bat 都不适用，这就是回退。
如果命令行长度超出平台限制（Linux/macOS 上为 64K，Windows 上为 8K），genrule 会将命令写入脚本并执行该脚本来解决问题。这适用于所有 cmd 属性（ |
cmd_bash
|
字符串；默认值为 此属性的优先级高于 |
cmd_bat
|
字符串；默认值为 此属性的优先级高于
|
cmd_ps
|
字符串；默认值为 此属性的优先级高于
为了使 Powershell 更易于使用并且不容易出错，我们先运行以下命令来设置环境，然后再在 genrule 中执行 Powershell 命令。
|
executable
|
布尔值；不可配置；默认值为
将此标志设为 True 表示输出是可执行文件，可以使用 不支持为生成的可执行文件声明数据依赖项。 |
local
|
布尔值；默认值为
如果设置为 True，此选项会强制使用“本地”策略运行此
这相当于提供“local”作为标记 ( |
message
|
字符串；默认值为
执行此构建步骤时将输出的进度消息。默认情况下，消息为“Generate output”（正在生成输出）或同样平淡无奇的消息，但您也可以提供更具体的消息。在 |
output_licenses
|
许可类型；默认值为 common attributes
|
output_to_bindir
|
布尔值；不可配置；默认值为
如果设置为 True，则此选项会将输出文件写入 |
tools
|
标签列表；默认值为
构建系统可确保在运行 genrule 命令之前构建这些前提条件；它们是使用 exec 配置构建的，因为这些工具是作为构建的一部分执行的。您可以使用
要由 |
starlark_doc_extract
查看规则来源starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)
starlark_doc_extract() 可提取有关在给定 .bzl 或 .scl 文件中定义或重新导出的规则、函数（包括宏）、切面和提供程序的文档。此规则的输出是一个 ModuleInfo 二进制 proto，如 Bazel 源代码树的 stardoc_output.proto 所定义。
隐式输出目标
name.binaryproto（默认输出）：一个ModuleInfo二进制 proto。name.textproto（仅在明确请求时构建）：name.binaryproto的文本 proto 版本。
警告：此规则的输出格式不能保证稳定。它主要供 Stardoc 内部使用。
参数
| 属性 | |
|---|---|
name |
名称（必需） 此目标的唯一名称。 |
deps
|
标签列表；默认值为 src 进行 load() 处理。在正常使用的情况下，这些目标应该为 bzl_library 目标，但 starlark_doc_extract 规则不会强制执行该目标，而是接受在其 DefaultInfo 中提供 Starlark 文件的任何目标。
请注意，封装的 Starlark 文件必须是源代码树中的文件；Bazel 无法 |
src
|
标签（必需） 要从中提取文档的 Starlark 文件。请注意，此文件必须是源代码树中的文件；Bazel 无法 |
render_main_repo_name
|
布尔值；默认值为 //foo:bar.bzl 将作为 @main_repo_name//foo:bar.bzl 发出）。主代码库使用的名称是从主代码库的 如果为仅在同一代码库中使用的 Starlark 文件生成文档，则应将此属性设置为 |
symbol_names
|
字符串列表；默认值为 当且仅当满足以下条件时，
|
test_suite
查看规则来源test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)
test_suite 定义了一组对人类“有用”的测试。这样一来，项目可以定义测试集，例如“签入前必须运行的测试”、“我们项目的压力测试”或“所有小型测试”。blaze test 命令遵循这种组织方式：对于像 blaze test //some/test:suite 这样的调用，Blaze 会先枚举 //some/test:suite 目标以传递方式包含的所有测试目标（我们称之为“test_suite 扩展”），然后 Blaze 会构建并测试这些目标。
示例
一个测试套件，用于运行当前软件包中的所有小测试。
test_suite(
name = "small_tests",
tags = ["small"],
)
运行一组指定测试的测试套件：
test_suite(
name = "smoke_tests",
tests = [
"system_unittest",
"public_api_unittest",
],
)
一个测试套件，用于运行当前软件包中所有不稳定的测试。
test_suite(
name = "non_flaky_test",
tags = ["-flaky"],
)
参数
| 属性 | |
|---|---|
name |
名称（必需） 此目标的唯一名称。 |
tags
|
文本标记列表，例如“small”“database”或“-flaky”。标记可以是任何有效字符串。 以“-”字符开头的标签会被视为否定关键字。前面的“-”字符不被视为标记的一部分，因此套件标记“-small”与测试的“small”大小匹配。所有其他标记均被视为肯定标记。 （可选）为使肯定标记更加明确，标记也可以以“+”字符开头，该字符不会作为标记文本的一部分进行评估。它只是让正面和负面的区别更易于阅读。 测试套件中仅包含与所有肯定标记和所有否定标记都匹配的测试规则。请注意，这并不意味着系统会跳过对过滤掉的测试的依赖项的错误检查；跳过的测试的依赖项仍然需要合法（例如，未被可见性限制屏蔽）。
请注意，测试的
如果您需要一个包含互斥标记的测试（例如，所有中小型测试）的 |
tests
|
任意语言的测试套件和测试目标的列表。
此处接受任何
如果 |