常见定义

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本部分定义了许多函数或构建规则通用的各种术语和概念。

目录

Bourne shell 令牌化

根据 Bourne shell 的标记化规则,某些规则的某些字符串属性会拆分为多个字词:不带英文引号的空格分隔单独的字词,单引号和双引号字符和反斜杠用于防止词法单元化。

受此令牌化处理的属性在本文档中的定义中进行了相应说明。

受“扩展”变量扩展和 Bourne shell 令牌化处理的属性通常用于将任意选项传递给编译器和其他工具。此类属性的示例包括 cc_library.coptsjava_library.javacopts。 通过这些替换,单个字符串变量可以扩展为特定于配置的选项字词列表。

标签展开

极少数规则的某些字符串属性会受到标签扩展的影响:如果这些字符串包含作为子字符串的有效标签(例如 //mypkg:target),并且该标签是当前规则的声明的先决条件,则它会扩展为由 target //mypkg:target 表示的文件的路径。

示例属性包括 genrule.cmdcc_binary.linkopts。由于各种问题(例如相对标签是否展开、如何处理扩展到多个文件的标签等),详细信息可能会有所不同。请参阅规则属性文档,了解详情。

大多数构建规则定义的典型属性

本部分介绍了由许多(而非全部)构建规则定义的属性。

属性 说明
data

List of labels ; optional

此规则在运行时需要的文件。可以列出文件或规则目标。通常允许任何目标。

data 属性中目标的默认输出和运行文件应显示在由此输出输出或具有此目标的运行时依赖项的 *.runfiles 区域中。这可能包括执行此目标的 srcs 时使用的数据文件或二进制文件。如需详细了解如何依赖和使用数据文件,请参阅数据依赖项部分。

如果新规则处理可能在运行时使用其他输入的输入,则应定义 data 属性。实现函数还必须从任何 data 属性的输出和运行文件以及任何提供源代码或运行时依赖项的依赖项属性填充目标的运行文件

deps

List of labels ; optional

此目标的依赖项。一般情况下,应仅列出规则目标。(虽然有些规则允许将文件直接列在 deps 中,但应尽可能避免。)

针对特定语言的规则通常将所列目标限制为具有特定 provider 的目标。

使用 deps 时,目标依赖于另一个目标的准确语义特定于规则种类,特定于规则的文档对此进行了详细介绍。对于处理源代码的规则,deps 通常指定 srcs 中的代码使用的代码依赖项。

通常,deps 依赖项用于允许一个模块使用以同一编程语言编写并单独编译的另一个模块中定义的符号。在许多情况下,我们也允许跨语言依赖项:例如,java_library 目标可以通过在 cc_library 目标中列出 C++ 代码,方法是在 deps 属性中列出后者。如需了解详情,请参阅依赖项的定义。

licenses

List of strings; optional; nonconfigurable

要用于此特定目标的许可类型字符串列表。 这是 Bazel 已不再使用的已弃用许可 API 的一部分。请勿使用。

srcs

List of labels ; optional

由此规则处理或包含的文件。通常直接列出文件,但也可以列出规则目标(例如 filegroupgenrule),以包含其默认输出。

针对特定语言的规则通常要求列出的文件具有特定的文件扩展名。

所有构建规则通用的属性

本部分介绍了隐式添加到所有构建规则的属性。

属性 说明
compatible_with

List of labels ; optional; nonconfigurable

除了默认支持的环境外,此目标可以构建的环境列表。

这是 Bazel 的约束系统的一部分,该系统允许用户声明哪些目标可以相互依赖,哪些不能相互依赖。例如,可外部部署的二进制文件不应依赖于包含公司密钥代码的库。如需了解详情,请参阅 ConstraintSemantics

deprecation

String; optional; nonconfigurable

与此目标相关联的说明性警告消息。 此令牌通常用于通知目标已过时、已被另一条规则取代、某个软件包仅私有或出于某种原因被视为有害。建议您添加一些引用(例如网页、错误编号或迁移示例 CL),以便用户轻松了解需要哪些更改才能避免相应消息。如果有可用作替换目标的新的目标,则最好只迁移旧目标的所有用户。

此属性不会影响内容的构建方式,但可能会影响构建工具的诊断输出。当具有 deprecation 特性的规则依赖于另一个软件包中的目标时,构建工具会发出警告。

软件包内依赖项可免除此警告,例如,构建已弃用规则的测试时不会遇到警告。

如果已弃用的目标依赖于另一个已弃用的目标,系统不会发出任何警告消息。

一旦用户停止使用该目标,就可以将其移除。

distribs

List of strings; optional; nonconfigurable

用于该特定目标的分发方法字符串列表。 这是 Bazel 已不再使用的已弃用许可 API 的一部分。请勿使用。

exec_compatible_with

List of labels ; optional; nonconfigurable

此目标的执行平台中必须存在的 constraint_values 列表。这是对规则类型已设置的任何限制条件的补充。限制条件用于限制可用执行平台的列表。如需了解详情,请参阅工具链解析的说明。

exec_properties

Dictionary of strings; optional

一个字符串,此字符串将添加到为此目标选择的平台的 exec_properties 中。请参阅 platform 规则的 exec_properties

如果某个键同时存在于平台级属性和目标级属性中,则该值将从目标获取。

features

List of feature strings; optional

功能是可在目标上启用或停用的字符串标记。特征的含义取决于规则本身。

features 属性与软件包features 属性结合使用。例如,如果在软件包级启用了 [a]、[b] 功能,并且目标的 features 属性包含 [‘-a’、‘c’’],则为该规则启用的功能将为‘b’和‘c’。查看示例

restricted_to

List of labels ; optional; nonconfigurable

可构建此目标环境的列表,而不是默认支持的环境。

这是 Bazel 的约束系统的一部分。如需了解详情,请参阅 compatible_with

tags

List of strings; optional; nonconfigurable

标记可用于任何规则。对测试和 test_suite 规则使用标记有助于对测试进行分类。非测试目标的标记用于控制在沙盒中运行的 genruleStarlark 操作,以及供人工和/或外部工具解析。

如果 Bazel 在任何测试或 genrule 目标的 tags 属性中发现以下关键字,或在任何 Starlark 操作发现 execution_requirements 的键中,就会修改其沙盒代码的行为。

  • no-sandbox 关键字会导致操作或测试从未被沙盒化;它仍然可以缓存或远程运行 - 使用 no-cacheno-remote 阻止其中之一或同时执行这两个操作。
  • no-cache 关键字导致操作或测试永远无法缓存(远程或本地)
  • no-remote-cache 关键字会导致操作或测试永远无法远程缓存(但可以在本地缓存;也可以远程执行)。注意:对于此标记,磁盘缓存被视为本地缓存,而 http 和 gRPC 缓存被视为远程缓存。如果指定了合并缓存(即包含本地和远程组件的缓存),系统会将其视为远程缓存,并完全停用缓存,除非设置了 --incompatible_remote_results_ignore_disk(在这种情况下将使用本地组件)。
  • no-remote-exec 关键字会导致操作或测试永远无法远程执行(但可能会远程缓存)。
  • no-remote 关键字可防止远程执行或缓存操作或测试。这相当于同时使用 no-remote-cacheno-remote-exec
  • no-remote-cache-upload 关键字可禁止上传某个衍生文件的远程缓存部分。而不会停用远程执行。
  • local 关键字用于禁止在沙盒内远程缓存、远程执行或运行操作或测试。 对于 genrule 和测试,使用 local = True 属性标记规则具有相同的效果。
  • requires-network 关键字允许从沙盒内访问外部网络。只有在启用沙盒功能后,此标记才会生效。
  • block-network 关键字阻止从沙盒内访问外部网络。在这种情况下,只允许与 localhost 通信。只有在启用沙盒功能后,此标记才会生效。
  • requires-fakeroot 以 uid 和 gid 0(即根用户)的身份运行测试或操作。仅 Linux 支持此操作。此标记优先于 --sandbox_fake_username 命令行选项。

测试上的标记通常用于为测试在调试和发布流程中的作用添加注解。通常,标记最适合缺少任何运行时注释功能的 C++ 和 Python 测试。使用标记和大小元素可以灵活地根据代码库签入政策组合测试套件。

如果 Bazel 在测试规则的 tags 属性中找到以下关键字,则会修改测试运行行为:

  • exclusive 会强制在“独占”模式下运行测试,以确保没有其他测试同时运行。完成所有构建活动和非独占测试后,系统将以串行方式执行此类测试。此类测试会停用远程执行,因为 Bazel 无法控制远程机器上运行的内容。
  • 如果在本地执行测试,exclusive-if-local 会强制在“独占”模式下运行测试;但如果远程执行,则会并行运行测试。
  • manual 关键字在展开目标模式通配符(...:*:all 等)和 test_suite 规则(在为 buildtestcoverage 命令计算要构建/运行的顶级目标集时,不会明确列出测试)时排除此目标。这不会影响其他上下文中的目标通配符或测试套件扩展,包括 query 命令。请注意,manual 并不意味着目标不应由持续构建/测试系统自动构建/运行。例如,可能需要从 bazel test ... 中排除某个目标,因为它需要特定的 Bazel 标志,但仍包含在正确配置的提交前或连续测试运行中。
  • external 关键字会强制无条件执行测试(不考虑 --cache_test_results 值)。
请参阅“测试百科全书”中的标记惯例,详细了解附加到测试目标的标记。
target_compatible_with

List of labels ; optional

此目标平台中必须存在的一系列 constraint_value 才会被视为兼容。这是对规则类型已设置的任何限制条件的补充。如果目标平台不符合所有列出的限制条件,则目标会被视为不兼容。当目标模式扩展时,系统会跳过构建和测试不兼容的目标(例如 //...:all)。在命令行中明确指定时,不兼容的目标会导致 Bazel 输出错误,并导致构建或测试失败。

间接依赖于不兼容目标的目标本身会被视为不兼容。系统还会跳过构建和测试。

空列表(默认值)表示目标与所有平台兼容。

工作区规则之外的所有规则都支持此属性。对于某些规则,此属性无效。例如,为 cc_toolchain 指定 target_compatible_with 没有用。

如需详细了解不兼容的目标跳过,请参阅平台页面。

testonly

Boolean; optional; default False except for test and test suite targets; nonconfigurable

如果为 True,则只有测试目标(例如测试)才能依赖于此目标。

因此,非 testonly 规则不能依赖任何 testonly 规则。

默认情况下,测试(*_test 规则)和测试套件(test_suite 规则)为 testonly

此属性旨在表示目标不应包含在已发布到生产环境的二进制文件中。

由于 testonly 在构建时强制执行,而不是在运行时强制执行,并且通过依赖项树进行病毒式传播,因此应该谨慎应用。例如,适用于单元测试的存根和虚假代码可能也会对涉及将发布至生产环境的二进制文件的集成测试有用,因此不应标记为仅测试。相反,甚至可能会无意间链接的规则(或许是因为它们无条件地替换了正常行为)应该绝对标记为 testtest。

toolchains

List of labels ; optional; nonconfigurable

允许此目标访问其“创建变量”的一组目标。这些目标可以是为 TemplateVariableInfo 提供规则的规则实例,也可以是为 Bazel 中内置的工具链类型提供的特殊目标。其中包括:

  • @bazel_tools//tools/cpp:current_cc_toolchain
  • @bazel_tools//tools/jdk:current_java_runtime

请注意,这与用于实现平台相关配置的规则实现所用的工具链解析的概念不同。您不能使用此属性来确定目标将使用哪个特定的 cc_toolchainjava_toolchain

visibility

List of labels ; optional; default default_visibility from package if specified, or //visibility:private otherwise; nonconfigurable

目标上的 visibility 属性用于控制目标是否可以在其他软件包中使用。请参阅关于可见性的文档。

所有测试规则通用的属性 (*_test)

本部分介绍了所有测试规则通用的属性。

属性 说明
args

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization

Bazel 使用 bazel test 执行时传递给目标的命令行参数。

这些参数会在 bazel test 命令行中指定的任何 --test_arg 值之前传递。

env

Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution

指定在 bazel test 执行测试时设置的其他环境变量。

此属性仅适用于原生规则,例如 cc_testpy_testsh_test。但不适用于 Starlark 定义的测试规则。对于您自己的 Starlark 规则,您可以添加 &envot;env” 属性,并使用它来填充 TestEnvironment 提供程序。

env_inherit

List of strings; optional

指定在 bazel test 执行测试时要从外部环境继承的其他环境变量。

此属性仅适用于原生规则,例如 cc_testpy_testsh_test。但不适用于 Starlark 定义的测试规则。

size

String "enormous", "large" "medium" or "small", default is "medium"; optional; nonconfigurable

指定测试目标的“重量”:测试需要花费的时间/资源。

单元测试称为“小”、集成测试“中”和端到端测试“大”或“超大”。Bazel 会使用该大小来确定默认超时时间,该超时时间可使用 timeout 属性覆盖。超时适用于 BUILD 目标中的所有测试,而不是单个测试。在本地运行时,size 还可用于调度目的:Bazel 会尝试遵循 --local_{ram,cpu}_resources,同时通过运行大量繁重测试而不导致本地机器过载。

测试大小对应于以下默认超时并假设本地资源峰值使用量:

大小 RAM(以 MB 为单位) CPU(在 CPU 核心中) 默认超时
small 20 1 短(1 分钟)
中等 100 1 中等(5 分钟)
300 1 长(15 分钟)
巨大 800 1 永恒(60 分钟)

生成测试时,环境变量 TEST_SIZE 将设置为此属性的值。

timeout

String "short", "moderate", "long", "eternal" (with the default derived from the test's size attribute); nonconfigurable

测试预计要持续多长时间才能返回。

虽然由测试的大小属性控制资源估算,但您可以单独设置测试的超时时间。如果未明确指定,超时时间取决于测试的大小。可以使用 --test_timeout 标志替换测试超时时间,例如,在已知运行缓慢的特定条件下运行。测试超时值对应于以下时间段:

超时值 时间段
短片 1 分钟
适中 5 分钟
long 15 分钟
永远 60 分钟

对于上述时间之外的测试超时,可以使用 --test_timeout bazel 标志替换测试超时时间,例如,在已知运行缓慢的条件下手动运行。--test_timeout 值以秒为单位。例如,--test_timeout=120 会将测试超时设置为两分钟。

生成测试时,环境变量 TEST_TIMEOUT 将设置为测试超时时间(以秒为单位)。

flaky

Boolean; optional; default False; nonconfigurable

将测试标记为不稳定。

如果设置,则最多执行三次测试,仅在每次失败时都会将其标记为失败。默认情况下,此属性设置为 False,并且测试仅执行一次。请注意,通常不建议使用此属性 - 在坚持其断言时,测试应该能够可靠地通过。

shard_count

Non-negative integer less than or equal to 50; optional

指定用于运行测试的并行分片的数量。

此值将用于确定用于确定运行测试的并行分片数量的任何启发法。请注意,对于某些测试规则,您可能需要先提供此参数,才能启用分片。另请参阅 --test_sharding_strategy

如果启用了测试分片,则系统在生成测试时会将环境变量 TEST_TOTAL_SHARDS 设置为此值。

分片要求测试运行程序支持测试分片协议。否则,它很可能会在每个分片中运行每个测试,而这并不是您想要的。

如需详细了解分片,请参阅“测试百科全书”中的测试分片

local

Boolean; default False; nonconfigurable

强制在不进行沙盒化的情况下在本地运行测试。

将其设置为 True 相当于提供“local”作为标记 (tags=["local"])。

所有二元规则通用的属性 (*_binary)

本部分介绍了所有二进制规则通用的属性。

属性 说明
args

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization; nonconfigurable

Bazel 通过 run 命令或作为测试执行时传递给目标的命令行参数。这些参数在 bazel runbazel test 命令行中指定的参数之前传递。

注意:在 Bazel 之外运行目标时不会传递参数(例如,在 bazel-bin/ 中手动执行二进制文件)。

env

Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution

指定当 bazel run 执行目标时要设置的其他环境变量。

此属性仅适用于原生规则,例如 cc_binarypy_binarysh_binary。但不适用于 Starlark 定义的可执行规则。

注意:在 Bazel 之外运行目标时,不会设置环境变量(例如,通过在 bazel-bin/ 中手动执行二进制文件)。

output_licenses

List of strings; optional

此二进制文件生成的输出文件的许可。 这是 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_settingconstraint_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 对象文件。 通过这种方式,构建工具可能会隐藏有关其工作方式的某些实现细节。构建概念参考中对此进行了更全面的说明。