规则
- <ph type="x-smartling-placeholder"></ph> 别名
- <ph type="x-smartling-placeholder"></ph> config_setting
- <ph type="x-smartling-placeholder"></ph> 文件组
- <ph type="x-smartling-placeholder"></ph> Genquery
- <ph type="x-smartling-placeholder"></ph> Genrule
- <ph type="x-smartling-placeholder"></ph> test_suite
别名
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias
规则会创建另一个可以在规则中引用的名称。
混叠仅适用于“常规”目标。具体而言,package_group
和 test_suite
不能别名。
别名规则有自己的可见性声明。在所有其他方面 与其引用的规则相同(例如 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
(在命令行中明确指定,或从 .bazelrc 文件中隐式指定):
config_setting( name = "simple", values = {"compilation_mode": "opt"} )
以下内容与以 ARM 并应用自定义定义的任何 build 匹配
FOO=bar
(例如 bazel build --cpu=arm --define FOO=bar ...
):
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
与顶级命令行标志不匹配,它可能仍然匹配
一些构建目标。
备注
- 请参阅 select,了解
config_setting
与当前配置状态匹配。 - 对于支持简写形式的标志(例如
--compilation_mode
与-c
),values
定义必须使用完整形式。这些 使用任一形式匹配调用。 -
如果标志接受多个值(如
--copt=-Da --copt=-Db
或列表类型值) <ph type="x-smartling-placeholder"></ph> Starlark flag),如果"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"]
。检查标志定义并测试 请仔细判断是否确实符合预期。 - 如果您需要定义未通过内置构建标志建模的条件,请使用
<ph type="x-smartling-placeholder"></ph>
Starlark 定义的标志。您也可以使用
--define
,但这种方式效果更好 支持,不推荐使用。请参阅 此处。 - 避免在不同软件包中重复相同的
config_setting
定义。 请改为引用规范软件包中定义的常用config_setting
。 values
、define_values
和constraint_values
可在同一config_setting
中任意组合使用,但必须至少提供一个 为任何给定的config_setting
设置。
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
constraint_values
|
constraint_values 集
才能匹配此config_setting 。(执行平台不是
)。平台已忽略的所有其他限制条件值都会被忽略。请参阅
<ph type="x-smartling-placeholder"></ph>
可配置的 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
|
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
|
“输出组”是目标输出工件的类别, 规则的实施。 |
Genquery
genquery(name, deps, data, compatible_with, 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 的输出使用 --order_output=full
以便强制执行确定性输出。
输出文件的名称就是规则的名称。
示例
此示例将标签列表写入 指定目标。
genquery( name = "kiwi-deps", expression = "deps(//kiwi:kiwi_lib)", scope = ["//kiwi:kiwi_lib"], )
参数
属性 | |
---|---|
name |
此目标的唯一名称。 |
expression
|
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, exec_tools, 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 来运行测试。测试和测试有特殊的方案
包括缓存政策和环境变量。通常需要运行测试
构建完成后在目标架构上执行,而 Genrule 在
build 和主机架构上的相同(两者可能不同)。如果您需要通用型
测试规则,请使用 sh_test
。
交叉编译注意事项
请参阅用户手册,详细了解 交叉编译。
虽然 Genrule 在构建期间运行,但其输出通常在构建之后用于部署或 测试。请考虑为微控制器编译 C 代码的示例:编译器接受 C 源文件,并生成在微控制器上运行的代码。生成的代码很明显 不能在用于构建它的 CPU 上运行,但可以在 C 编译器(如果从源代码编译)上运行 。
构建系统使用主机配置来描述运行 build 的机器 和目标配置,用于描述生成 build 输出的机器 投放时间它提供了用于配置上述各项的选项,并将 将对应的文件放入单独的目录中,以避免冲突。
对于 Genrule,构建系统可确保正确构建依赖项:
srcs
是为 target 配置构建的(如有必要),
tools
是针对 host 配置构建的,并且输出被视为
适用于 target 配置。它还提供
“制作”变量。
Genrule 有意不定义 deps
属性:其他内置规则使用
在规则之间传递与语言的元信息,以自动确定如何
处理依赖的规则,但 Genrule 无法实现这种级别的自动化。Genrule 的工作原理
而不是在命令行和 Runfile 级别运行。
特殊情况
主机-主机编译:在某些情况下,构建系统需要运行 genrule,以便
也可以在构建期间执行输出例如,如果 Genrule 构建了一些自定义编译器
随后另一个 Genrule 会使用它,第一个 Genrule 必须为其生成输出
主机配置,因为编译器将在另一个 genrule 中运行它。在此示例中
构建系统会自动执行正确的操作:构建 srcs
并
用于主机配置(而非目标)的第一代规则的 outs
配置。如需了解详情,请参阅用户手册
信息。
JDK 和C++ 工具:如需使用 JDK 或 C++ 编译器套件中的工具,构建系统 提供一组要使用的变量。请参阅“创作”变量 。
Genrule 环境
genrule 命令由 Bash shell 执行,Bash shell 配置为在运行命令时失败
或者流水线失败,请使用 set -e -o pipefail
。
构建工具会在经过清理的进程环境中执行 Bash 命令,
仅定义了核心变量,例如 PATH
、PWD
TMPDIR
和其他一些人。
为了确保构建可重现,用户 shell 中定义的大多数变量
不会将环境传递给 genrule 的命令。不过,Bazel(
Blaze)传递用户的 PATH
环境变量的值。
对 PATH
的值所做的任何更改都会导致 Bazel 重新执行该命令
下一个 build。
genrule 命令不应访问网络,除非连接 命令本身的子项(尽管目前尚未强制执行)。
构建系统会自动删除所有现有的输出文件,但会创建所有必要的父文件 然后再运行 Genrule。如果测试失败,此 API 还会移除所有输出文件。
一般建议
- 确保由 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 命令应在预定位置创建每个输出文件。
该位置通过 genrule 专用的“Make”在 |
cmd
|
$(location)
和“品牌”的约束变量替换。
cmd_bash 、cmd_ps 和 cmd_bat 的回退,
如果所有信息都不适用。
如果命令行长度超出平台限制(Linux/macOS 上为 64K,Windows 上为 8K),
则 genrule 会将命令写入脚本并执行该脚本以解决问题。这个
适用于所有 cmd 属性( |
cmd_bash
|
此属性的优先级高于 |
cmd_bat
|
此属性的优先级高于
|
cmd_ps
|
此属性的优先级高于
为了使 Powershell 更易于使用并且不容易出错,我们运行以下命令 命令设置环境,然后再在 genrule 中执行 Powershell 命令。
|
exec_tools
|
tools 属性,不同之处在于这些依赖项
将针对规则的执行平台(而非主机配置)进行配置。
这意味着,exec_tools 中的依赖项不同
限制将完全限定为 tools 中的依赖项。具体而言,我们不要求他们
将主机配置用于自己的传递依赖项。请参阅
tools 了解更多详情。
Blaze 团队正在将“ |
executable
|
将此标志设置为 True 表示输出是可执行文件,可以使用
不支持为生成的可执行文件声明数据依赖项。 |
local
|
如果设置为 True,此选项会强制此
这相当于提供“本地”以标记 ( |
message
|
执行此构建步骤时将输出的进度消息。默认情况下,
消息为“生成输出”(或者是同样平淡无奇的),但您可以提供
更具体的一个。请使用此属性,而不要使用 |
output_licenses
|
common attributes
|
output_to_bindir
|
如果设置为 True,此选项会将输出文件写入 |
tools
|
构建系统确保在运行 genrule 命令之前已构建这些前提条件;
它们是使用 host 构建的,
配置,因为这些工具是作为构建的一部分执行的。一个
单个
任何要由 |
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”与测试的“small”匹配。系统会将所有其他代码 肯定标记。 (可选)为使正面标记更加明确,还可以以 “+”字符,因此系统不会将其作为代码文本的一部分进行评估。它 只是使正面和负面的区别更易于阅读。 仅测试与所有肯定标记且不匹配任何否定标记的规则 代码将包含在测试套件中请注意,这并不意味着 会跳过对过滤掉的测试的依赖项;跳过的依赖项 测试仍然需要合法(例如,不会被可见性限制阻止)。
请注意,测试的
如果您需要一个包含具有互斥标记的测试的 |
tests
|
此处接受任何
如果 |