常见定义

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

目录

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

所有构建规则通用的属性

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

属性	说明
compatible_with	List of labels ; optional; nonconfigurable 除了默认支持的环境之外，还可以构建此目标的环境列表。 这是 Bazel 约束系统的一部分，可让用户声明哪些目标可以相互依赖，哪些目标不能相互依赖。例如，可在外部部署的二进制文件不应依赖于具有公司密钥代码的库。如需了解详情，请参阅 ConstraintSemantics。
deprecation	String; optional; nonconfigurable 与此目标相关联的说明性警告消息。通常情况下，这用于通知用户：目标已作废、被其他规则取代、仅对软件包可见，或因某种原因被视为有害。建议您提供一些参考信息（例如网页、bug 编号或示例迁移 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 规则有助于对测试进行分类。 非测试目标上的标记用于控制 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 关键字可阻止操作或测试在沙盒内远程缓存、远程执行或运行。对于 genrules 和测试，使用 local = True 属性标记规则具有相同的效果。 requires-network 关键字允许从沙盒内访问外部网络。此标记仅在启用沙盒的情况下有效。 block-network 关键字用于阻止从沙盒内部访问外部网络。在这种情况下，系统仅允许与 localhost 通信。此标记仅在启用沙盒的情况下有效。 requires-fakeroot 以 uid 和 gid 0（即 root 用户）的身份运行测试或操作。只有 Linux 支持此功能。此标记优先于 --sandbox_fake_username 命令行选项。 测试上的标记通常用于为测试在调试和发布流程中的作用添加注解。通常，标记最适合缺少任何运行时注释功能的 C++ 和 Python 测试。通过使用标记和大小元素，您可以根据代码库签入政策灵活地组合测试套件。 如果 Bazel 在测试规则的 tags 属性中发现以下关键字，则会修改测试运行行为： exclusive 会强制以“独占”模式运行测试，以确保不会同时运行其他测试。完成所有构建 Activity 和非独占测试后，将按顺序执行此类测试。此类测试的远程执行已停用，因为 Bazel 无法控制远程机器上运行的内容。 如果在本地执行，exclusive-if-local 会强制以“独占”模式运行测试；但如果远程执行，则并行运行测试。 使用 manual 关键字时，系统在扩展目标模式通配符（...、:*、:all 等）和 test_suite 规则时会将目标排除在外，这些规则在计算要用于 build、test 和 coverage 命令构建/运行的顶级目标集时，不会明确列出测试。它不会影响其他上下文（包括 query 命令）中的目标通配符或测试套件扩展。请注意，manual 并不意味着目标不应由连续构建/测试系统自动构建/运行。例如，可能需要从 bazel test ... 中排除某个目标，因为它需要特定的 Bazel 标志，但仍包含在正确配置的预提交或连续测试运行中。 external 关键字将强制无条件执行测试（无论 --cache_test_results 值如何）。 如需了解有关附加到测试目标的代码的更多惯例，请参阅《测试百科全书》中的标记规范。
target_compatible_with	List of labels ; optional 目标平台中必须存在的 constraint_value 的列表才会被视为兼容。这是对规则类型已设置的任何限制条件的补充。如果目标平台不满足列出的所有限制条件，则目标平台会被视为不兼容。incompatible当目标模式展开（例如 //...、:all）时，系统会跳过不兼容的目标进行构建和测试。如果在命令行中明确指定，则不兼容的目标会导致 Bazel 输出错误，并导致构建或测试失败。 以传递方式依赖于不兼容目标的目标本身会被视为不兼容。构建和测试也会跳过这些测试。 空列表（这是默认列表）表示目标与所有平台兼容。 除工作区规则之外的所有规则都支持此属性。对于某些规则，此属性无效。例如，为 cc_toolchain 指定 target_compatible_with 没有用。 如需详细了解不兼容的目标跳过，请参阅平台页面。
testonly	Boolean; optional; default False except for test and test suite targets; nonconfigurable 如果为 True，则只有 testonly 目标（例如测试）可以依赖于此目标。 同理，不为 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_toolchain 或 java_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 test 执行 Bazel 时传递给目标的命令行参数。 这些参数会在 bazel test 命令行中指定的任何 --test_arg 值之前传递。
env	Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution 指定在由 bazel test 执行测试时设置的其他环境变量。 此属性仅适用于原生规则，如 cc_test、py_test 和 sh_test。不适用于 Starlark 定义的测试规则。对于您自己的 Starlark 规则，您可以添加“env”属性，并使用它来填充 TestEnvironment 提供程序。
env_inherit	List of strings; optional 指定在由 bazel test 执行测试时从外部环境继承的其他环境变量。 此属性仅适用于原生规则，如 cc_test、py_test 和 sh_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 将测试标记为不稳定。 如果设置了此字段，则最多执行 3 次测试，仅当每次测试失败时才将其标记为失败。默认情况下，此属性设置为 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 相当于以标记 (tags=["local"]) 的形式提供“local”。

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

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

属性	说明
args	List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization; nonconfigurable 当目标由 run 命令执行或作为测试执行时，Bazel 会传递给目标的命令行参数。这些参数会在 bazel run 或 bazel test 命令行中指定的参数之前传递。 注意：在 Bazel 之外运行目标时（例如，通过在 bazel-bin/ 中手动执行二进制文件时），系统不会传递参数。
env	Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution 指定在由 bazel run 执行目标时设置的其他环境变量。 此属性仅适用于原生规则，如 cc_binary、py_binary 和 sh_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_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 概念参考中对此有详细说明。