本部分定义了许多函数或构建规则中通用的各种术语和概念。
目录
- 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 |
功能是可对目标启用或停用的字符串标记。特征的含义取决于规则本身。 此 |
restricted_to |
可构建此目标的环境列表,而不是支持的默认环境。
这是 Bazel 约束系统的一部分。如需了解详情,请参阅 |
tags |
标记可以用于任何规则。测试上的标记和
如果 Bazel 在任何测试或
测试上的标记通常用于为测试在调试和发布流程中的作用添加注解。通常,标记最适合缺少任何运行时注释功能的 C++ 和 Python 测试。通过使用标记和大小元素,您可以根据代码库签入政策灵活地组合测试套件。
如果 Bazel 在测试规则的
|
target_compatible_with |
目标平台中必须存在的 以传递方式依赖于不兼容目标的目标本身会被视为不兼容。构建和测试也会跳过这些测试。 空列表(这是默认列表)表示目标与所有平台兼容。
除工作区规则之外的所有规则都支持此属性。对于某些规则,此属性无效。例如,为
如需详细了解不兼容的目标跳过,请参阅平台页面。 |
testonly |
如果为 True,则只有 testonly 目标(例如测试)可以依赖于此目标。
同理,不为
默认情况下,测试( 此属性旨在表示目标不应包含在已发布到生产环境的二进制文件中。 由于 testonly 在构建时(而不是运行时)强制执行,并且通过依赖项树病毒式传播,因此应谨慎应用。例如,对单元测试有用的桩和虚假对象也可能对涉及将发布到生产环境的相同二进制文件的集成测试有用,因此可能不应该标记为测试专用。反之,有些规则连入有危险,原因可能是它们无条件地替换正常行为,也应明确标记为测试。 |
toolchains |
允许此目标访问其 Make 变量 的一组目标。这些目标可以是提供
请注意,这不同于规则实现用于实现依赖于平台的配置的工具链解析概念。您无法使用此属性来确定目标将使用哪个特定的 |
visibility |
目标的 |
所有测试规则通用的属性 (*_test)
本部分介绍了所有测试规则通用的属性。
属性 | 说明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
使用
这些参数会在 |
||||||||||||||||||||
env |
指定在由
此属性仅适用于原生规则,如 |
||||||||||||||||||||
env_inherit |
指定在由
此属性仅适用于原生规则,如 |
||||||||||||||||||||
size |
指定测试目标的“重量”:测试需要运行的时间/资源量。 单元测试称为“小型”测试,集成测试称为“中型测试”,端到端测试称为“大型”测试或“大型”测试。Bazel 会根据大小来确定默认超时时间,您可以使用 测试大小与以下默认超时时间相对应,而且假定是本地资源用量峰值:
生成测试时,环境变量 |
||||||||||||||||||||
timeout |
在返回之前,测试的预期运行时长。
虽然测试的大小属性控制资源估算,但测试的超时可以单独设置。如果未明确指定,则超时取决于测试的大小。您可以使用
对于上述时间之外的其他时间,可以使用 生成测试时,环境变量 |
||||||||||||||||||||
flaky |
将测试标记为不稳定。 如果设置了此字段,则最多执行 3 次测试,仅当每次测试失败时才将其标记为失败。默认情况下,此属性设置为 False,并且只执行一次测试。请注意,通常不建议使用此属性 - 如果测试的断言得到支持,测试应该会可靠地通过。 |
||||||||||||||||||||
shard_count |
指定用于运行测试的并行分片数。 此值将替换用于确定运行测试所用并行分片数的任何启发法。请注意,对于某些测试规则,首先可能需要使用此参数才能启用分片。另请参阅 如果启用测试分片,则在生成测试时,环境变量 分片要求测试运行程序支持测试分片协议。否则,它很可能会在每个分片中运行每个测试,而这并不是您想要的结果。 如需详细了解分片,请参阅《测试百科全书》中的测试分片。 |
||||||||||||||||||||
local |
强制在本地运行测试,不使用沙盒。 将此标志设置为 True 相当于以标记 ( |
所有二元规则通用的属性 (*_binary)
本部分介绍所有二进制规则通用的属性。
属性 | 说明 |
---|---|
args |
当目标由
注意:在 Bazel 之外运行目标时(例如,通过在 |
env |
指定在由
此属性仅适用于原生规则,如
注意:在 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 概念参考中对此有详细说明。