常见定义

报告问题 查看源代码

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

目录

Bourne shell 令牌化

某些规则的某些字符串特性根据 Bourne shell 的标记化规则被拆分为多个字词:不带英文引号的空格分隔不同的字词,而单引号和双引号字符和反斜杠则用来防止进行词元化处理。

在本文档中,这些令牌化的属性在它们的定义中进行了明确指示。

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

标签扩展

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

属性示例包括 genrule.cmdcc_binary.linkopts。在各种情况下,细节可能会略有不同,例如:相对标签是否展开;展开至多个文件的标签的处理方式等。如需了解详情,请参阅规则属性文档。

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

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

属性 说明
data

List of labels ; optional

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

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

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

deps

List of labels ; optional

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

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

对于使用 deps 来指示目标依赖于另一个目标的具体语义,取决于该规则的类型,关于特定规则的文档将进行更详细的介绍。对于处理源代码的规则,deps 通常指定 srcs 中的代码使用的代码依赖项。

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

licenses

List of strings; optional; nonconfigurable

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

srcs

List of labels ; optional

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

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

所有构建规则通用的属性

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

属性 说明
compatible_with

List of labels ; optional; nonconfigurable

此环境可用于构建此环境的列表,以及默认支持的环境。

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

deprecation

String; optional; nonconfigurable

与此目标关联的说明性警告消息。 这通常用于通知用户目标已过时、被其他规则取代、仅对软件包可见,或出于某种原因被视为有害。最好添加一些引用(例如网页、bug 编号或示例迁移 CL),以便用户轻松了解需要做出哪些更改才能避免该消息。如果有可以用作替换掉数的新目标,则最好只迁移旧目标的所有用户。

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

例如,软件包内依赖项不受此警告的影响,因此在构建已弃用的规则的测试时不会遇到警告。

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

用户停止使用目标后,即可将其移除。

distribs

List of strings; optional; nonconfigurable

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

exec_compatible_with

List of labels ; optional; nonconfigurable

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

exec_properties

Dictionary of strings; optional

将添加到为此目标选择的平台的 exec_properties 中的字符串的字典。请参阅平台规则的 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 属性中发现以下关键字,或在 execution_requirements 中发现任何 Starlark 操作中的键,就会修改其沙盒代码的行为。

  • 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(即 root 用户)的形式运行测试或操作。仅 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 是在构建时强制执行的,而不是在运行时强制执行的,并且通过依赖项树进行广泛传播,因此应谨慎应用。例如,对于单元测试来说,有用的桩和虚假项也适用于涉及将发布到生产环境的相同二进制文件的集成测试,因此可能不应标记为仅测试。反过来说,甚至可能不安全的关联规则(或许是无条件地替换正常行为)应该标记为仅测试。

toolchains

List of labels ; optional; nonconfigurable

该目标允许访问其 Make 变量的一组目标。这些目标可以是提供 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 规则,您可以添加“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 分钟)
medium 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 的一部分。请勿使用此 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_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 进行检查的内容;这里是目标命名空间。每个文件目标对应于磁盘上的一个实际文件(“文件系统命名空间”);每个规则目标可能对应于磁盘上的零个、一个或多个实际文件。磁盘上可能没有相应的目标;例如,C++ 编译期间生成的 .o 对象文件无法从 BUILD 文件或命令行引用。 这样一来,构建工具可能会隐藏有关其工作方式的某些实现细节。构建概念参考对这一点进行了更详细的说明。