本部分定义了许多函数或构建规则通用的各种术语和概念。
目录
- Bourne shell shell tokenization
- 标签扩展
- 大多数构建规则定义的典型属性
- 所有 build 规则通用的属性
- 所有测试规则通用的属性 (*_test)
- 所有二进制规则通用的属性 (*_binary)
- 可配置属性
- 隐式输出目标
Bourne shell 令牌化
某些规则的某些字符串特性根据 Bourne shell 的标记化规则被拆分为多个字词:不带英文引号的空格分隔不同的字词,而单引号和双引号字符和反斜杠则用来防止进行词元化处理。
在本文档中,这些令牌化的属性在它们的定义中进行了明确指示。
受“Make”变量扩展和 Bourne shell 令牌化处理的属性通常用于将任意选项传递给编译器和其他工具。此类属性的示例包括 cc_library.copts
和 java_library.javacopts
。
通过这些替换,可以将单个字符串变量扩展为特定于配置的选项字词列表。
标签扩展
极少数规则的某些字符串属性会受标签扩展影响:如果这些字符串包含作为子字符串的有效标签(如 //mypkg:target
),且该标签是当前规则声明的先决条件,则它会扩展为由 target
//mypkg:target
表示的文件的路径。
属性示例包括 genrule.cmd
和 cc_binary.linkopts
。在各种情况下,细节可能会略有不同,例如:相对标签是否展开;展开至多个文件的标签的处理方式等。如需了解详情,请参阅规则属性文档。
大多数构建规则定义的典型属性
本部分将介绍由许多 build 规则(而非全部)定义的属性。
属性 | 说明 |
---|---|
data |
此规则在运行时需要的文件。可以列出文件或规则目标。通常允许任何目标。
如果新规则会处理可能在运行时使用其他输入的输入,则应定义 |
deps |
此目标的依赖项。一般情况下,应仅列出规则目标。(虽然某些规则允许直接将文件列在 针对特定语言的规则通常将所列目标限制为具有特定提供程序的规则。
对于使用
通常, |
licenses |
用于此特定目标的许可类型字符串列表。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用此 ID。 |
srcs |
此规则处理或包含的文件。通常直接列出文件,但也可以列出规则目标(如 针对特定语言的规则通常要求所列文件具有特定的文件扩展名。 |
所有构建规则通用的属性
本部分介绍了隐式添加到所有构建规则的属性。
属性 | 说明 |
---|---|
compatible_with |
此环境可用于构建此环境的列表,以及默认支持的环境。 这是 Bazel 的约束系统的一部分,通过该系统,用户可以声明哪些目标可以/不可以相互依赖。例如,可外部部署的二进制文件不应依赖于包含公司密钥代码的库。如需了解详情,请参阅 ConstraintSemantics。 |
deprecation |
与此目标关联的说明性警告消息。 这通常用于通知用户目标已过时、被其他规则取代、仅对软件包可见,或出于某种原因被视为有害。最好添加一些引用(例如网页、bug 编号或示例迁移 CL),以便用户轻松了解需要做出哪些更改才能避免该消息。如果有可以用作替换掉数的新目标,则最好只迁移旧目标的所有用户。
此属性不会影响内容的构建方式,但可能会影响构建工具的诊断输出。当具有 例如,软件包内依赖项不受此警告的影响,因此在构建已弃用的规则的测试时不会遇到警告。 如果已弃用的目标依赖于另一个已弃用的目标,则不会发出任何警告消息。 用户停止使用目标后,即可将其移除。 |
distribs |
用于此特定目标的分布方法字符串列表。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用此 ID。 |
exec_compatible_with |
此目标的执行平台中必须存在的 |
exec_properties |
将添加到为此目标选择的平台的 如果某个键同时存在于平台级和目标级媒体资源中,则相应值将从目标中获取。 |
features |
功能是可在目标上启用或停用的字符串标记。功能的含义取决于规则本身。 此 |
restricted_to |
此目标可以构建的环境的列表,而不是默认支持的环境。
这是 Bazel 的约束系统的一部分。如需了解详情,请参阅 |
tags |
代码可用于任何规则。对测试和
如果 Bazel 在任何测试或
测试中的标记通常用于为测试在调试和发布流程中的作用添加注解。通常,标记对于缺少运行时注解功能的 C++ 和 Python 测试最为有用。使用标记和大小元素可让您根据代码库签入政策灵活地组合测试套件。
如果 Bazel 在测试规则的
|
target_compatible_with |
目标平台中必须包含的一系列 间接依赖于不兼容目标的目标本身被视为不兼容。系统还会跳过构建和测试步骤。 空列表(默认列表)表示目标与所有平台兼容。
除工作区规则之外的所有规则均支持此属性。对于某些规则,此属性无效。例如,为
如需详细了解不兼容的目标跳过,请参阅平台页面。 |
testonly |
如果为 True,则只有测试目标(例如测试)才能依赖于此目标。
同样,不允许非
测试( 此属性旨在意味着目标不应包含在已发布到生产环境的二进制文件中。 由于 testonly 是在构建时强制执行的,而不是在运行时强制执行的,并且通过依赖项树进行广泛传播,因此应谨慎应用。例如,对于单元测试来说,有用的桩和虚假项也适用于涉及将发布到生产环境的相同二进制文件的集成测试,因此可能不应标记为仅测试。反过来说,甚至可能不安全的关联规则(或许是无条件地替换正常行为)应该标记为仅测试。 |
toolchains |
该目标允许访问其 Make 变量的一组目标。这些目标可以是提供
请注意,这与规则实现在实现依赖于平台的配置时使用的工具链解析的概念不同。您不能使用此属性确定目标将使用的具体 |
visibility |
|
所有测试规则通用的属性 (*_test)
本部分介绍所有测试规则通用的属性。
属性 | 说明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
Bazel 在通过
这些参数会在 |
||||||||||||||||||||
env |
指定在
此属性仅适用于原生规则,例如 |
||||||||||||||||||||
env_inherit |
指定当
此属性仅适用于原生规则,例如 |
||||||||||||||||||||
size |
指定测试目标的“执行能力”:即测试需要运行的时间/资源。 单元测试被视为“小型”测试、集成测试“中型”测试、端到端测试“大型”测试或“大型”测试。Bazel 会根据该大小确定默认超时,该超时可使用 测试大小对应于以下默认超时并假设本地资源峰值用量:
在生成测试时,环境变量 |
||||||||||||||||||||
timeout |
测试预计要持续多长时间才能返回。
虽然测试的大小属性可控制资源估算,但可以单独设置测试的超时。如果未明确指定,则超时将根据测试的大小决定。可以使用
对于上述时间之外的测试超时,可以使用 生成测试时,环境变量 |
||||||||||||||||||||
flaky |
将测试标记为不稳定。 如果设置了此标记,则最多执行三次测试,仅在每次失败时将其标记为失败。默认情况下,此属性会设置为 False,并且测试仅执行一次。请注意,通常不建议使用此属性 - 在坚持断言时,应可靠地通过测试。 |
||||||||||||||||||||
shard_count |
指定用于运行测试的并行分片数量。 此值将替换任何启发法,以确定用于运行测试的并行分片数。请注意,对于某些测试规则,您可能需要先提供此参数才能启用分片。另请参阅 如果启用了测试分片,系统会在生成测试时将环境变量 分片要求测试运行程序支持测试分片协议。否则,它很可能会在每个分片中运行每个测试,这并不是您想要的。 如需详细了解分片,请参阅《测试百科全书》中的测试分片。 |
||||||||||||||||||||
local |
强制在不使用沙盒的情况下在本地运行测试。 将其设置为 True 等同于提供“local”作为标记 ( |
所有二进制规则通用的属性 (*_binary)
本部分介绍所有二进制规则通用的属性。
属性 | 说明 |
---|---|
args |
Bazel 通过
注意:在 Bazel 之外运行目标时(例如,在 |
env |
指定在由
此属性仅适用于原生规则,例如
注意:在 Bazel 之外运行目标时(例如,通过手动执行 |
output_licenses |
此二进制文件生成的输出文件的许可。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用此 ID。 |
可配置的属性
大多数属性都是“可配置”的,这意味着当目标以不同方式构建时,它们的值可能会更改。具体而言,可配置的属性可能会根据传递到 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 文件或命令行引用。
这样一来,构建工具可能会隐藏有关其工作方式的某些实现细节。构建概念参考对这一点进行了更详细的说明。