常见定义

报告问题 查看源代码

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

目录

• 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	标签列表；默认值为 [] 此规则在运行时所需的文件。可以列出文件或规则目标。通常允许任何目标。 data 属性中目标的默认输出和 runfile 应显示在由此目标输出或具有此目标的运行时依赖项的任何可执行文件的 *.runfiles 区域中。这可能包括执行此目标的 srcs 时使用的数据文件或二进制文件。如需详细了解如何依赖和使用数据文件，请参阅数据依赖项部分。 如果新规则处理可能在运行时使用其他输入的输入，则应定义 data 属性。规则的实现函数还必须从任何 data 属性的输出和 runfile 以及来自任何提供源代码或运行时依赖项的依赖项属性的 runfile 中填充目标的 runfile。
deps	标签列表；默认值为 [] 此目标的依赖项。通常，应仅列出规则目标。（虽然某些规则允许将文件直接列在 deps 中，但应尽可能避免这种情况。） 特定于语言的规则通常将列出的目标限制为具有特定提供程序的目标。 使用 deps 表示一个目标依赖于另一个目标的确切语义取决于规则类型，并且特定于规则的文档会详细介绍。对于处理源代码的规则，deps 通常会指定 srcs 中的代码所使用的代码依赖项。 大多数情况下，deps 依赖项允许一个模块使用在另一个模块中定义的符号，这些符号采用相同的编程语言编写并单独编译。在很多情况下，也允许使用跨语言依赖项：例如，java_library 目标可能依赖于 cc_library 目标中的 C++ 代码，只需在 deps 属性中列出后者即可。如需了解详情，请参阅依赖项的定义。
licenses	字符串列表；不可配置；默认值为 ["none"] 要用于此特定目标的许可类型字符串列表。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用。
srcs	标签列表；默认值为 [] 此规则处理或包含的文件。通常直接列出文件，但也可以列出规则目标（如 filegroup 或 genrule）以包含其默认输出。 特定于语言的规则通常要求列出的文件具有特定的文件扩展名。

所有构建规则通用的属性

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

属性	说明
compatible_with	标签列表；不可配置；默认值为 [] 此目标可以为其构建的列表，以及默认支持的环境。 这是 Bazel 限制条件系统的一部分，可让用户声明哪些目标可以相互依赖，哪些不可以。例如，可在外部部署的二进制文件不应依赖于包含公司密钥代码的库。如需了解详情，请参阅 ConstraintSemantics。
deprecation	字符串；不可配置；默认值为 None 与此目标相关的说明性警告消息。 通常用于通知用户目标已过时、已被另一条规则取代、仅供软件包专用或可能因某种原因而被视为有害。建议您添加一些参考资料（例如网页、bug 编号或迁移 CL 示例），以便用户轻松了解需要做出哪些更改才能避免此消息。 如果有可用作替代目标的新目标，最好只迁移旧目标的所有用户。 此属性对构建方式没有影响，但可能会影响构建工具的诊断输出。当具有 deprecation 属性的规则被另一个软件包中的目标依赖时，构建工具会发出警告。 软件包内依赖项不受此警告的约束，例如，在构建已弃用的规则的测试时不会遇到警告。 如果已弃用的目标依赖于其他已弃用的目标，系统不会发出警告消息。 用户停止使用后，即可移除目标。
distribs	字符串列表；不可配置；默认值为 [] 要用于此特定目标的分发方法字符串列表。 这是 Bazel 不再使用的已弃用许可 API 的一部分。请勿使用。
exec_compatible_with	标签列表；不可配置；默认值为 [] 对于此目标，执行平台中必须存在的 constraint_values 列表。这是对规则类型已设置的任何限制条件的补充。限制条件用于限制可用执行平台的列表。如需了解详情，请参阅工具链解析的说明。
exec_properties	字符串字典；默认值为 {} 一个字符串字典，将添加到为此目标选择的平台的 exec_properties 中。请参阅 platform 规则的 exec_properties。 如果某个键同时存在于平台级属性和目标级属性中，则系统将从目标中获取其值。
features	feature 字符串列表；默认值为 [] 功能是可以在目标上启用或停用的字符串标记。特征的含义取决于规则本身。 此 features 属性与 软件包级 features 属性结合使用。例如，如果在软件包级别启用了功能 ["a", "b"]，并且目标的 features 属性包含 ["-a", "c"]，则为规则启用的功能将是“b”和“c”。 查看示例。
restricted_to	标签列表；不可配置；默认值为 [] 可以构建此目标的环境列表，而不是默认支持的环境。 这是 Bazel 限制条件系统的一部分。如需了解详情，请参阅 compatible_with。
tags	字符串列表；不可配置；默认值为 [] 标记可以用于任何规则。测试和 test_suite 规则上的标记有助于对测试进行分类。 非测试目标上的标记用于控制 genrule 和 Starlark 操作的沙盒化执行，以及由人工和/或外部工具解析。 如果 Bazel 在任何测试或 genrule 目标的 tags 属性中或针对任何 Starlark 操作的 execution_requirements 键中发现以下关键字，就会修改其沙盒代码的行为。 no-sandbox 关键字会导致操作或测试永远不会被沙盒化；它们仍可缓存或远程运行 - 请使用 no-cache 或 no-remote 来阻止其中之一或同时阻止二者。 no-cache 关键字导致操作或测试永远不会被缓存（远程或本地） no-remote-cache 关键字会导致操作或测试永远不会被远程缓存（但它们可以缓存在本地；也可以远程执行）。 注意：对于此标记，磁盘缓存被视为本地缓存，而 http 和 gRPC 缓存被视为远程缓存。 如果使用本地磁盘缓存和远程缓存的组合（组合缓存），系统会将其视为远程缓存并完全停用，除非设置了 --incompatible_remote_results_ignore_disk（在这种情况下将使用本地组件）。 no-remote-exec 关键字会导致操作或测试永远无法远程执行（但可以远程缓存）。 no-remote 关键字可防止远程执行或远程缓存操作或测试。这相当于同时使用 no-remote-cache 和 no-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 规则的扩展中排除目标；在计算要针对 build、test 和 coverage 命令构建/运行的顶级目标集时，不会明确列出测试的 test_suite 规则。而不会影响其他上下文（包括 query 命令）中的目标通配符或测试套件扩展。请注意，manual 并不意味着连续构建/测试系统不应自动构建/运行目标。例如，您可能希望从 bazel test ... 中排除某个目标，因为它需要特定的 Bazel 标志，但仍包含在正确配置的提交前或持续测试运行中。 external 关键字将强制无条件执行测试（无论 --cache_test_results 值如何）。 请参阅测试百科全书中的标记规范，了解附加到测试目标的标记的更多规范。
target_compatible_with	标签列表；默认值为 [] 目标平台中必须存在的 constraint_value 列表，此目标才会被视为兼容。这是对规则类型已设置的任何限制条件的补充。如果目标平台无法满足列出的所有限制条件，则目标平台会被视为不兼容。incompatible扩展目标模式（例如 //...、:all）时，系统会跳过不兼容的目标进行构建和测试。如果在命令行中明确指定不兼容的目标，则不兼容的目标会导致 Bazel 输出错误，并导致构建或测试失败。 间接依赖于不兼容的目标的目标本身会被视为不兼容。构建和测试时会跳过这些测试。 空列表（这是默认值）表示目标与所有平台兼容。 除工作区规则之外的所有规则都支持此属性。对于某些规则，此属性无效。例如，为 cc_toolchain 指定 target_compatible_with 毫无用处。 如需详细了解不兼容的目标跳过功能，请参阅平台页面。
testonly	布尔值；不可配置；默认值为 False（测试套件目标和测试套件目标除外） 如果为 True，则只有 testonly 目标（例如测试）可以依赖于此目标。 同样，不为 testonly 的规则不得依赖于任何处于 testonly 状态的规则。 默认情况下，测试（*_test 规则）和测试套件（test_suite 规则）为 testonly。 此属性旨在表示目标不应包含在已发布为正式版的二进制文件中。 由于 testonly 在构建时强制执行，而不是在运行时强制执行，并且会在依赖项树中病毒式传播，因此应用时应谨慎。例如，对单元测试有用的存根和虚构实现对涉及将要发布到生产环境的相同二进制文件的集成测试也很有用，因此可能不应标记为仅测试。反之，如果规则甚至有可能链接起来（或许是因为它们无条件地覆盖正常行为），则应将其标记为仅供测试。
toolchains	标签列表；不可配置；默认值为 [] 允许此目标访问其 Make 变量的一组目标。这些目标要么是提供 TemplateVariableInfo 的规则实例，要么是内置于 Bazel 中的工具链类型的特殊目标。其中包括： @bazel_tools//tools/cpp:current_cc_toolchain @bazel_tools//tools/jdk:current_java_runtime 请注意，这与工具链解析的概念不同，工具链解析用于实现依赖于平台的配置的规则。您无法使用此属性来确定目标将使用哪个特定 cc_toolchain 或 java_toolchain。
visibility	标签列表；不可配置；如果指定，则默认为来自软件包的 default_visibility，否则为 "//visibility:private" 目标上的 visibility 属性用于控制目标能否在其他软件包中使用。如需了解可见性，请参阅文档。

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

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

属性	说明
args	字符串列表；受限于 $(location) 和 "Make variable" 替换以及 Bourne shell 令牌化；默认值为 [] 在使用 bazel test 执行 Bazel 时，Bazel 传递给目标的命令行参数。 这些参数在 bazel test 命令行中指定的任何 --test_arg 值之前传递。
env	字符串字典；值可被替换为 $(location) 和 "Make variable"；默认值为 [] 指定在 bazel test 执行测试时要设置的其他环境变量。 此属性仅适用于原生规则，例如 cc_test、py_test 和 sh_test。但不适用于 Starlark 定义的测试规则。对于您自己的 Starlark 规则，您可以添加“env”属性，并使用它来填充 TestEnvironment 提供程序。
env_inherit	字符串列表；默认值为 [] 指定在 bazel test 执行测试时要从外部环境继承的其他环境变量。 此属性仅适用于原生规则，例如 cc_test、py_test 和 sh_test。但不适用于 Starlark 定义的测试规则。
size	字符串 "enormous"、"large"、"medium" 或 "small"；不可配置；默认值为 "medium" 指定测试目标的“重量”：测试需要运行多长时间/资源。 单元测试被视为“小型”测试，集成测试“中”测试，端到端测试被视为“大型”或“巨大”。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	字符串 "short"、"moderate"、"long" 或 "eternal"；不可配置；默认值派生自测试的 size 属性 测试在返回之前预计会运行多长时间。 虽然测试的大小属性控制资源估算，但可以单独设置测试的超时。如果未明确指定，超时将取决于测试的大小。测试超时可以使用 --test_timeout 标志替换，例如，在某些已知慢速条件下运行。测试超时值对应于以下时间段： 超时值 时间段 短片 1 分钟 中 5 分钟 long 15 分钟 永恒 60 分钟 对于上述时间之外的时间，可以使用 --test_timeout bazel 标志替换测试超时，例如，在已知慢速条件下手动运行时。--test_timeout 值以秒为单位。例如，--test_timeout=120 会将测试超时设置为两分钟。 生成测试时，环境变量 TEST_TIMEOUT 将设置为测试超时时间（以秒为单位）。
flaky	布尔值；不可配置；默认值为 False 将测试标记为不稳定。 如果设置了此字段，则最多执行测试三次，仅在每次失败时才会将其标记为失败。默认情况下，此属性设置为 False，且仅执行一次测试。请注意，通常不建议使用此属性，因为如果测试的断言得到支持，测试应能可靠地通过测试。
shard_count	小于或等于 50 的非负整数；默认值为 -1 指定用于运行测试的并行分片数。 如果设置此值，则此值将替换用于确定运行测试的并行分片数量的任何启发法。请注意，对于某些测试规则，可能需要从一开始就启用分片。另请参阅 --test_sharding_strategy： 如果已启用测试分片，则在生成测试时，环境变量 TEST_TOTAL_SHARDS 将设置为此值。 分片要求测试运行程序支持测试分片协议。否则，它很可能会在每个分片中运行每个测试，这不是您想要的结果。 如需详细了解分片，请参阅测试百科全书中的测试分片。
local	布尔值；不可配置；默认值为 False 强制测试在本地运行，而不采用沙盒机制。 将此属性设为 True 等同于提供“local”作为标记 (tags=["local"])。

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

本部分介绍了所有二元规则共有的属性。

属性	说明
args	字符串列表；具体取决于使用 $(location) 和 "Make variable" 替换值以及 Bourne shell 标记化；不可配置；默认值为 [] Bazel 将在通过 run 命令执行或作为测试执行时传递给目标的命令行参数。这些参数在 bazel run 或 bazel test 命令行中指定的参数之前传递。 注意：在 Bazel 外部运行目标时（例如，通过手动执行 bazel-bin/ 中的二进制文件），系统不会传递这些参数。
env	字符串字典；值可被替换为 $(location) 和 "Make variable"；默认值为 {} 指定在 bazel run 执行目标时要设置的其他环境变量。 此属性仅适用于原生规则，例如 cc_binary、py_binary 和 sh_binary。而不适用于 Starlark 定义的可执行规则。 注意：在 Bazel 外部运行目标时（例如，通过手动执行 bazel-bin/ 中的二进制文件），系统不会设置环境变量。
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 概念参考。