本部分定义了许多函数或构建规则中常见的各种术语和概念。
目录
- Bourne shell 令牌化
- 标签展开
- 大多数构建规则定义的典型属性
- 所有构建规则通用的属性
- 所有测试规则通用的属性 (*_test)
- 所有二元规则通用的属性 (*_binary)
- 可配置的属性
- 隐式输出目标
Bourne shell 令牌化
某些规则的某些字符串属性根据 Bourne shell 的标记化规则拆分为多个单词:不带英文引号的空格分隔单独的单词,使用单引号和双引号字符以及反斜杠来防止标记化。
需要遵循此标记化处理的属性在本文档中的定义中进行了明确说明。
受“Make”变量扩展和 Bourne shell 标记化影响的属性通常用于将任意选项传递给编译器和其他工具。此类属性的示例包括 cc_library.copts
和 java_library.javacopts
。
这些替代变量共同允许单个字符串变量扩展为特定于配置的选项字词列表。
标签展开
极少数规则的某些字符串属性会受标签扩展:如果这些字符串包含子字符串形式的有效标签(例如 //mypkg:target
),且该标签是当前规则的声明先决条件,则会扩展为由目标
//mypkg:target
表示的文件的路径名。
例如,genrule.cmd
和 cc_binary.linkopts
等属性。每种情况下的细节可能差别很大,例如存在相对标签是否展开、如何处理扩展到多个文件的标签等。有关详细信息,请参阅规则属性文档。
大多数构建规则定义的典型属性
本部分介绍了由许多(但非全部)构建规则定义的属性。
属性 | 说明 |
---|---|
data |
标签列表;默认值为 此规则在运行时所需的文件。可以列出文件或规则目标。通常允许任何目标。
如果新规则处理可能在运行时使用其他输入的输入,则应定义 |
deps |
标签列表;默认值为
此目标的依赖项。通常,应仅列出规则目标。(虽然某些规则允许将文件直接列在 特定于语言的规则通常将列出的目标限制为具有特定提供程序的目标。
使用
大多数情况下, |
licenses |
字符串列表;不可配置;默认值为 要用于此特定目标的许可类型字符串列表。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用。 |
srcs |
标签列表;默认值为
此规则处理或包含的文件。通常直接列出文件,但也可以列出规则目标(如 特定于语言的规则通常要求列出的文件具有特定的文件扩展名。 |
所有构建规则通用的属性
本部分介绍了隐式添加到所有构建规则的属性。
属性 | 说明 |
---|---|
compatible_with |
此目标可以为其构建的列表,以及默认支持的环境。 这是 Bazel 限制条件系统的一部分,可让用户声明哪些目标可以相互依赖,哪些不可以。例如,可在外部部署的二进制文件不应依赖于包含公司密钥代码的库。如需了解详情,请参阅 ConstraintSemantics。 |
deprecation |
字符串;不可配置;默认值为 与此目标相关的说明性警告消息。 通常用于通知用户目标已过时、已被另一条规则取代、仅供软件包专用或可能因某种原因而被视为有害。建议您添加一些参考资料(例如网页、bug 编号或迁移 CL 示例),以便用户轻松了解需要做出哪些更改才能避免此消息。 如果有可用作替代目标的新目标,最好只迁移旧目标的所有用户。
此属性对构建方式没有影响,但可能会影响构建工具的诊断输出。当具有 软件包内依赖项不受此警告的约束,例如,在构建已弃用的规则的测试时不会遇到警告。 如果已弃用的目标依赖于其他已弃用的目标,系统不会发出警告消息。 用户停止使用后,即可移除目标。 |
distribs |
字符串列表;不可配置;默认值为 要用于此特定目标的分发方法字符串列表。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用。 |
exec_compatible_with |
对于此目标,执行平台中必须存在的 |
exec_properties |
字符串字典;默认值为 一个字符串字典,将添加到为此目标选择的平台的 如果某个键同时存在于平台级属性和目标级属性中,则系统将从目标中获取其值。 |
features |
feature 字符串列表;默认值为 功能是可以在目标上启用或停用的字符串标记。特征的含义取决于规则本身。 此 |
restricted_to |
可以构建此目标的环境列表,而不是默认支持的环境。
这是 Bazel 限制条件系统的一部分。如需了解详情,请参阅 |
tags |
字符串列表;不可配置;默认值为
标记可以用于任何规则。测试和
如果 Bazel 在任何测试或
测试上的标记通常用于标注测试在调试和发布流程中的作用。通常,标记对 C++ 和 Python 测试最为有用,因为它们缺少任何运行时注解功能。使用标记和大小元素可让您根据代码库签入政策灵活地组建测试套件。
如果 Bazel 在测试规则的
|
target_compatible_with |
标签列表;默认值为
目标平台中必须存在的 间接依赖于不兼容的目标的目标本身会被视为不兼容。构建和测试时会跳过这些测试。 空列表(这是默认值)表示目标与所有平台兼容。
除工作区规则之外的所有规则都支持此属性。对于某些规则,此属性无效。例如,为
如需详细了解不兼容的目标跳过功能,请参阅平台页面。 |
testonly |
布尔值;不可配置;默认值为
如果为
同样,不为
默认情况下,测试( 此属性旨在表示目标不应包含在已发布为正式版的二进制文件中。 由于 testonly 在构建时强制执行,而不是在运行时强制执行,并且会在依赖项树中病毒式传播,因此应用时应谨慎。例如,对单元测试有用的存根和虚构实现对涉及将要发布到生产环境的相同二进制文件的集成测试也很有用,因此可能不应标记为仅测试。反之,如果规则甚至有可能链接起来(或许是因为它们无条件地覆盖正常行为),则应将其标记为仅供测试。 |
toolchains |
允许此目标访问其 Make 变量的一组目标。这些目标要么是提供
请注意,这与工具链解析的概念不同,工具链解析用于实现依赖于平台的配置的规则。您无法使用此属性来确定目标将使用哪个特定 |
visibility |
标签列表;不可配置;如果指定,则默认为来自软件包的
目标上的 |
所有测试规则通用的属性 (*_test)
本部分介绍了所有测试规则共有的属性。
属性 | 说明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
字符串列表;受限于 $(location) 和 "Make variable" 替换以及 Bourne shell 令牌化;默认值为 在使用
这些参数在 |
||||||||||||||||||||
env |
字符串字典;值可被替换为 $(location) 和 "Make variable";默认值为
指定在
此属性仅适用于原生规则,例如 |
||||||||||||||||||||
env_inherit |
字符串列表;默认值为 指定在
此属性仅适用于原生规则,例如 |
||||||||||||||||||||
size |
字符串 指定测试目标的“重量”:测试需要运行多长时间/资源。 单元测试被视为“小型”测试,集成测试“中”测试,端到端测试被视为“大型”或“巨大”。Bazel 使用该大小来确定默认超时,可以使用 测试大小对应于以下默认超时和假设的本地资源使用量峰值:
生成测试时,环境变量 |
||||||||||||||||||||
timeout |
字符串 测试在返回之前预计会运行多长时间。
虽然测试的大小属性控制资源估算,但可以单独设置测试的超时。如果未明确指定,超时将取决于测试的大小。测试超时可以使用
对于上述时间之外的时间,可以使用
生成测试时,环境变量 |
||||||||||||||||||||
flaky |
布尔值;不可配置;默认值为 将测试标记为不稳定。 如果设置了此字段,则最多执行测试三次,仅在每次失败时才会将其标记为失败。默认情况下,此属性设置为 False,且仅执行一次测试。请注意,通常不建议使用此属性,因为如果测试的断言得到支持,测试应能可靠地通过测试。 |
||||||||||||||||||||
shard_count |
小于或等于 50 的非负整数;默认值为 指定用于运行测试的并行分片数。 如果设置此值,则此值将替换用于确定运行测试的并行分片数量的任何启发法。请注意,对于某些测试规则,可能需要从一开始就启用分片。另请参阅 如果已启用测试分片,则在生成测试时,环境变量 分片要求测试运行程序支持测试分片协议。否则,它很可能会在每个分片中运行每个测试,这不是您想要的结果。 如需详细了解分片,请参阅测试百科全书中的测试分片。 |
||||||||||||||||||||
local |
布尔值;不可配置;默认值为 强制测试在本地运行,而不采用沙盒机制。 将此属性设为 True 等同于提供“local”作为标记 ( |
所有二元规则通用的属性 (*_binary)
本部分介绍了所有二元规则共有的属性。
属性 | 说明 |
---|---|
args |
字符串列表;具体取决于使用 $(location) 和 "Make variable" 替换值以及 Bourne shell 标记化;不可配置;默认值为
Bazel 将在通过
注意:在 Bazel 外部运行目标时(例如,通过手动执行 |
env |
字符串字典;值可被替换为 $(location) 和 "Make variable";默认值为 指定在
此属性仅适用于原生规则,例如
注意:在 Bazel 外部运行目标时(例如,通过手动执行 |
output_licenses |
字符串列表;默认值为 此二进制文件生成的输出文件的许可。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用。 |
可配置的属性
大多数属性都是“可配置的”,这意味着,当以不同方式构建目标时,它们的值可能会发生变化。具体而言,可配置属性可能会因传递给 Bazel 命令行的标志或请求目标的下游依赖项而异。例如,它可用于针对多个平台或编译模式自定义目标。
以下示例为不同的目标架构声明了不同的源代码。运行 bazel build :multiplatform_lib --cpu x86
将使用 x86_impl.cc
构建目标,而替换 --cpu arm
将使其使用 arm_impl.cc
。
cc_library( name = "multiplatform_lib", srcs = select({ ":x86_mode": ["x86_impl.cc"], ":arm_mode": ["arm_impl.cc"] }) ) config_setting( name = "x86_mode", values = { "cpu": "x86" } ) config_setting( name = "arm_mode", values = { "cpu": "arm" } )
select()
函数会根据目标配置满足的 config_setting
或 constraint_value
条件,为可配置属性的不同备用值选择值。
在处理宏之后,在处理规则之前(从技术上讲,在
加载和分析阶段之间),Bazel 会评估可配置的属性。在 select()
计算之前进行的任何处理都不知道 select()
选择哪个分支。例如,宏无法根据所选分支更改其行为,而 bazel query
只能对目标的可配置依赖项进行保守推测。如需详细了解如何结合使用 select()
和规则和宏,请参阅
此常见问题解答。
文档中标有 nonconfigurable
的属性无法使用此功能。通常属性是不可配置的,因为 Bazel 内部需要先知道其值,然后才能确定如何解析 select()
。
如需详细了解,请参阅 可配置的 build 属性。
隐式输出目标
C++ 中的隐式输出已被弃用。请尽可能不要以其他语言使用它。我们还没有弃用路径,但它们最终也会被弃用。
在 BUILD 文件中定义构建规则时,您在软件包中明确声明新的已命名规则目标。许多构建规则函数还隐式具有一个或多个输出文件目标,其内容和含义取决于规则。
例如,当您显式声明 java_binary(name='foo', ...)
规则时,您也隐式将输出文件目标 foo_deploy.jar
声明为同一软件包的成员。
(此特定目标是一个适合部署的独立 Java 归档。)
隐式输出目标是全局目标图的一级成员。与其他目标一样,它们是按需构建的,可以在顶级构建命令中指定,或者当它们是其他构建目标的先决条件时。它们可以在 BUILD 文件中作为依赖项引用,并且可以在 bazel query
等分析工具的输出中观察到。
对于每种构建规则,规则的文档都包含一个特殊的部分,详细说明该类型规则声明所需的任何隐式输出的名称和内容。
构建系统使用的两个命名空间之间有一个重要但有点细微的区别:标签用于标识目标,该目标可能是规则或文件,文件目标可以分为源(或输入)文件目标和派生(或输出)文件目标。这些都是您可以在 BUILD 文件中提及、从命令行构建或使用 bazel query
进行检查的内容;这就是目标命名空间。每个文件目标对应于磁盘上的一个实际文件(“文件系统命名空间”);每个规则目标可能对应于磁盘上的零个、一个或多个实际文件。
磁盘上的文件可能没有相应的目标;例如,在 C++ 编译期间生成的 .o
对象文件无法从 BUILD 文件或命令行中引用。
这样一来,构建工具可能会隐藏有关其工作方式的某些实现细节。如需了解详情,请参阅 BUILD 概念参考。