本部分定义了许多函数或构建规则通用的各种术语和概念。
目录
- 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 |
标签列表;默认值为
此目标的依赖项。通常,应仅列出规则目标。(虽然某些规则允许文件直接列在 特定于语言的规则通常将列出的目标限制为具有特定 provider 的目标。
对于目标使用
大多数情况下, |
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 在构建时(而不是运行时)强制执行,并且通过依赖项树以病毒方式传播,因此应谨慎应用测试。例如,对单元测试有用的存根和虚假对象可能对涉及将发布到生产环境的相同二进制文件的集成测试也很有用,因此可能不应该标记为 testonly。反过来,有些规则甚至很危险(可能是由于它们会无条件地替换正常行为),因此请务必将其标记为 testonly。 |
toolchains |
此目标可以访问其 Make 变量的一组目标。这些目标可以是提供
请注意,这与工具链解析的概念不同,工具链解析是基于平台的配置的规则实现所使用的概念。您无法使用此属性来确定目标将使用哪个特定的 |
visibility |
标签列表;不可配置;如果指定,则默认为 package 中的
目标上的 |
所有测试规则的通用属性 (*_test)
本部分介绍了所有测试规则共有的属性。
属性 | 说明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
字符串列表;可以使用 $(location) 和 "Make variable" 替换,以及 Bourne shell 标记化;默认值为 使用
这些参数会在 |
||||||||||||||||||||
env |
字符串字典;值可以替换 $(location) 和 "Make variable";默认值为
指定由
此属性仅适用于原生规则,如 |
||||||||||||||||||||
env_inherit |
字符串列表;默认值为 指定在
此属性仅适用于原生规则,如 |
||||||||||||||||||||
size |
字符串 指定测试目标的“承重性”:测试需要运行的时间/资源。 单元测试被视为“小型”,集成测试“中”,端到端测试被视为“大型”或“超大”。Bazel 会根据大小来确定默认超时,您可以使用 测试大小对应于以下默认超时时间和假定峰值本地资源使用量:
生成测试时,环境变量 |
||||||||||||||||||||
timeout |
字符串 在返回之前,测试预期运行多长时间。
虽然测试的大小属性用于控制资源估算,但测试的超时可以单独设置。如果未明确指定,则超时取决于测试的大小。测试超时可以使用
对于除上述情况之外的时间,可以使用
生成测试时,环境变量 |
||||||||||||||||||||
flaky |
布尔值;不可配置;默认值为 将测试标记为不稳定。 如果设置了此字段,则最多执行 3 次测试,仅当每次失败时才会将测试标记为失败。默认情况下,此属性设置为 False,并且测试仅执行一次。请注意,通常不建议使用此属性,如果测试的断言得到支持,测试应能可靠地通过。 |
||||||||||||||||||||
shard_count |
小于或等于 50 的非负整数;默认值为 指定用于运行测试的并行分片数量。 如果设置了此值,则此值将覆盖用于确定用于运行测试的并行分片数量的任何启发式方法。请注意,对于某些测试规则,首先可能需要使用此参数才能启用分片。另请参阅 如果启用了测试分片,则在生成测试时,环境变量 分片要求测试运行程序支持测试分片协议。否则,它很可能在每个分片中运行每个测试,但这不是您想要的结果。 如需详细了解分片,请参阅《测试百科全书》中的测试分片。 |
||||||||||||||||||||
local |
布尔值;不可配置;默认值为 强制在本地运行,而不使用沙盒。 将此属性设置为 True 相当于以标记 ( |
所有二元规则通用的属性 (*_binary)
本部分介绍了所有二进制规则共有的属性。
属性 | 说明 |
---|---|
args |
字符串列表;可以使用 $(location) 和“创建变量”替换项,以及 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
进行检查;这些就是目标命名空间。每个文件目标对应于磁盘上的一个实际文件(“文件系统命名空间”);每个规则目标可以对应于磁盘上的零个、一个或多个实际文件。磁盘上可能有没有对应目标的文件;例如,无法在 BUILD 文件中或从命令行引用在 C++ 编译期间生成的 .o
对象文件。
这样,构建工具可能会隐藏有关其工作方式的某些实现细节。如需了解详细说明,请参阅构建概念参考。