规则
alias
查看规则源代码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 ），但也有一些例外情况：
-
如果命令行中提到了测试的别名，则测试不会运行。如需定义用于运行所引用测试的别名，请使用
test_suite规则，并在其tests属性中添加一个目标。 -
定义环境组时，不支持
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 的任何 build（在命令行中显式设置，或通过 .bazelrc 文件隐式设置）：
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 文件）：
config_setting(
name = "my_custom_flag_is_set",
flag_values = { "//custom_flags:foo": "1" },
)
以下内容匹配任何以具有 x86_64 架构和 glibc 的平台为目标的 build
版本 2.25，假设存在带有标签的 constraint_value
//example:glibc_2_25。请注意，即使平台定义了除这两个值之外的其他限制条件值，也仍会匹配。
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
|
目标平台必须指定的最小 constraint_values 集
才能匹配此config_setting。（此处不考虑执行平台。）平台已忽略的所有其他限制条件值都会被忽略。请参阅
可配置的 build 属性了解详情。
两个 |
define_values
|
字典：字符串 -> 字符串；不可配置；默认为 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 ->String;不可配置；默认值为 values 相同，但适用于用户定义的 build 标志。
这是个独特的属性，因为用户定义的标志是作为标签引用的，而内置标志是作为任意字符串引用的。 |
values
|
字典：字符串 -> 字符串；不可配置；默认为 此规则会继承在 为方便起见，配置值以 build 标志的形式指定（不带前面的 如果未在命令行中明确设置标志，则系统会使用其默认值。
如果字典中某个键出现多次，则仅使用最后一个实例。
如果某个键引用了可以在命令行中多次设置的标志（例如
|
文件组
查看规则来源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 来 grovel 测试数据目录：
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
|
String;默认值为 “输出组”是目标输出工件的类别， 规则的实施。 |
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
|
String;必需 要执行的查询。与命令行和 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 则在构建期间在执行架构上执行（这两者可能不同）。如果您需要通用测试规则，请使用 sh_test。
交叉编译注意事项
请参阅用户手册，详细了解 进行交叉编译。
虽然 genrule 在构建期间运行，但其输出通常在构建后用于部署或测试。不妨考虑为微控制器编译 C 代码的示例：编译器接受 C 源文件，并生成在微控制器上运行的代码。生成的代码很明显 不能在用于构建它的 CPU 上运行，但可以在 C 编译器（如果从源代码编译）上运行 。
构建系统使用 exec 配置来描述运行 build 的机器 和目标配置，用于描述生成 build 输出的机器 投放时间它提供了用于配置上述各项的选项，并将 将对应的文件放到单独的目录中，以避免冲突。
对于 genrule，构建系统会确保正确构建依赖项：为 target 配置构建 srcs（如果需要），为 exec 配置构建 tools，并将输出视为适用于 target 配置。它还提供
“制作”变量。
Genrule 有意不定义 deps 属性：其他内置规则使用
在规则之间传递与语言的元信息，以自动确定如何
处理依赖的规则，但 Genrule 不可能实现这种级别的自动化。Genrule 仅在文件和 runfile 级别运行。
特殊情况
Exec-exec 编译：在某些情况下，构建系统需要运行 genrule，以便
也可以在构建期间执行输出例如，如果 Genrule 构建了一些自定义编译器
随后另一个 Genrule 会使用它，第一个 Genrule 必须为其生成输出
exec 配置，因为编译器将在另一个 genrule 中运行该配置。在此示例中
构建系统会自动执行正确的操作：构建 srcs 并
exec 配置（而非目标）的第一个 Genrule 的 outs
配置。如需了解详情，请参阅用户手册
信息。
JDK 和 C++ 工具：如需使用 JDK 或 C++ 编译器套件中的工具，构建系统提供了一组可供使用的变量。如需了解详情，请参阅“品牌”变量。
Genrule 环境
genrule 命令由 Bash shell 执行，Bash shell 配置为在运行命令时失败
或者流水线失败，请使用 set -e -o pipefail。
构建工具会在经过净化的进程环境中执行 Bash 命令，该环境仅定义 PATH、PWD、TMPDIR 等核心变量以及其他一些变量。
为确保 build 可重现，用户 shell 环境中定义的大多数变量都不会传递给 genrule 的命令。不过，Bazel（
Blaze）传递用户的 PATH 环境变量的值。
对 PATH 的值所做的任何更改都会导致 Bazel 重新执行该命令
下一个 build。
genrule 命令不应访问网络，除非连接 命令本身的子项（尽管目前未强制执行）。
构建系统会自动删除所有现有的输出文件，但会创建所有必要的父文件 然后再运行 Genrule。如果导出失败，此配置还会移除所有输出文件。
一般建议
- 请确保由 genrule 运行的工具是确定性的且密封的。用户不应写入 时间戳，并且应该对集和映射使用稳定的排序， 只写入输出的相对文件路径，不写入绝对路径。不遵守此规则会导致 导致意外的构建行为（Bazel 不会重新构建您想象的 Genrule），并且 会降低缓存性能
- 请广泛使用
$(location)，用于输出、工具和来源。由于输出文件会按不同的配置进行分隔，因此 genrule 不能依赖于硬编码的绝对路径。 - 请务必编写一个常见的 Starlark 宏，以防在 多个位置。如果 Genrule 比较复杂，请考虑在脚本中或以 星罗克法则。这可以提高可读性和可测试性。
- 请务必确保退出代码正确指示 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
|
String;默认值为 $(location)
和“品牌”的约束变量替换。
cmd_bash、cmd_ps 和 cmd_bat 的回退，
如果其中一条都不适用
如果命令行长度超出平台限制（Linux/macOS 上为 64K，Windows 上为 8K），
则 genrule 会将命令写入脚本并执行该脚本以解决问题。这个
适用于所有 cmd 属性（ |
cmd_bash
|
String;默认值为 此属性的优先级高于 |
cmd_bat
|
String;默认值为 此属性的优先级高于
|
cmd_ps
|
字符串；默认值为 此属性的优先级高于
为了让 Powershell 更易于使用且不易出错，我们会在 genrule 中执行 Powershell 命令之前，运行以下命令来设置环境。
|
executable
|
将输出声明为可执行文件。
将此标志设为 True 表示输出是可执行文件，可以使用 不支持为生成的可执行文件声明数据依赖项。 |
local
|
布尔值；默认值为
如果设置为 True，此选项会强制此
这相当于提供“本地”以标记 ( |
message
|
字符串；默认值为
执行此构建步骤时将输出的进度消息。默认情况下，
消息为“生成输出”（或者是同样平淡无奇的），但您可以提供
更具体的一个。在 |
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，如所定义
在
stardoc_output.proto
在 Bazel 源代码树中
隐式输出目标
name.binaryproto（默认输出）：ModuleInfo二进制 proto。name.textproto（仅在明确请求时构建）：name.binaryproto的文本 proto 版本。
警告：此规则的输出格式无法保证稳定。它主要供 Stardoc 在内部使用。
参数
| 属性 | |
|---|---|
name |
名称；必需 此目标的唯一名称。 |
deps
|
标签列表；默认值为 load()
src。在正常使用情况下，这些目标应为 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 发出）。
主代码库使用的名称是从 在为以下内容生成文档时，应将此属性设置为 |
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_suiteexpand”）），然后 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
|
任何语言的测试套件和测试目标的列表。
此处接受任何
如果 |