常见定义

报告问题 查看源代码 敬上 每晚 · 7.3。 · 7.2。 · 7.1。 · 7.0。 · 6.5

本部分定义了 Google Cloud 上的 许多函数或构建规则。

目录

• Bourne shell 令牌化
• 标签展开
• 大多数构建规则定义的典型属性
• 所有构建规则通用的属性
• 所有测试规则通用的属性 (*_test)
• 所有二元规则通用的属性 (*_binary)
• 可配置的属性
• 隐式输出目标

Bourne shell 令牌化

某些规则的某些字符串属性会拆分成多个 将单词转换为多个单词： 不带英文引号的空格用于分隔不同的字词，使用单引号和 英文双引号字符和反斜杠用于防止 标记化。

受此标记化影响的特性包括 本文档的定义中对此进行了明确说明。

受“品牌”约束的属性变量扩展和 Bourne shell 标记化通常用于将任意选项传递给 编译器和其他工具此类属性的示例包括 cc_library.copts和java_library.javacopts。 这些替换结合在一起， 扩展为特定于配置的列表的单个字符串变量 包含可选字词。

标签展开

只有极少数规则的某些字符串属性会带有标签 扩展：如果这些字符串包含有效标签，如 子字符串（例如 //mypkg:target），并且该标签是一个 已声明的先决条件，则会扩展到 以 目标 //mypkg:target。

例如，genrule.cmd 和 cc_binary.linkopts。不同国家/地区的详情可能会 例如，相对标签是否 已展开；扩展到多个文件的标签是如何 等等。请参阅规则属性文档 。

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

本部分介绍了由许多构建规则定义的属性， 而不是全部。

属性	说明
data	标签列表；默认值为 [] 此规则在运行时所需的文件。可以列出文件或规则目标。一般 允许任何目标。 data 属性中目标的默认输出和 runfile 应出现在任意可执行文件的*.runfiles区域中 或具有此目标的运行时依赖项。这可能包括数据 当此目标的 系统会执行 srcs。请参阅 数据依赖项 部分，详细了解如何依赖和使用数据文件。 新规则在处理后，应定义 data 属性 可能在运行时使用其他输入的输入。规则的实现函数 还必须填充目标的 runfiles 任何 data 属性的输出和 runfile， 以及来自提供 源代码或运行时依赖项
deps	标签列表；默认值为 [] 此目标的依赖项。通常，应仅列出规则目标。（尽管 有些规则允许文件直接列在 deps 中， 应尽可能避免）。 特定于语言的规则通常会将列出的目标限制为 特定提供商。 一个目标依赖于另一个目标，具体语义是 deps 特定于规则类型，而规则专用 文档。对于处理源代码的规则 deps 通常指定 srcs。 大多数情况下，deps 依赖项用于让一个模块使用 使用相同编程语言编写的另一个模块中定义的符号，并且 单独编译的内容。很多语言中也允许使用跨语言依赖项 用例：例如，java_library 目标可能依赖于 C++ 代码 方法（在 cc_library 目标中列出后者） deps 属性。查看 依赖项 。
licenses	字符串列表；不可配置； 默认值为 ["none"] 要用于此特定目标的许可类型字符串列表。 这是 Bazel 不再使用的已弃用许可 API 的一部分。错误做法 使用它。
srcs	标签列表；默认值为 [] 此规则处理或包含的文件。通常直接列出文件，但 可能会列出规则目标（例如 filegroup 或 genrule）， 添加其默认输出 针对特定语言的规则通常要求列出的文件具有特定的 文件扩展名。

所有构建规则通用的属性

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

属性	说明
compatible_with	标签列表； 不可配置；默认值为 [] 可以构建此目标的环境列表 默认支持的环境。 这是 Bazel 限制条件系统的一部分，该系统可让用户声明 目标可以和不能相互依赖。例如，可在外部部署 二进制文件不应依赖于包含公司密钥代码的库。请参阅 ConstraintSemantics。
deprecation	String;不可配置；默认值为 None 与此目标相关的说明性警告消息。 通常情况下，此标识符用于通知用户某个定位条件已过时， 或已被其他规则取代、仅供软件包使用，或者 可能出于某种原因被视为有害的内容。建议添加 一些参考信息（如网页、错误编号或迁移 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 属性中的关键字 target 或 execution_requirements 的键（适用于任何 Starlark） 操作。 no-sandbox 关键字导致操作或测试永远无法 沙盒它仍然可以缓存或远程运行 - 请使用 no-cache 或 no-remote 来阻止其中之一或同时阻止二者。 no-cache 关键字导致操作或测试永远无法 缓存内容（本地或远程）。注意：就此标记而言，磁盘缓存 系统会将 HTTP 和 gRPC 缓存视为本地缓存 遥控器。其他缓存（如 Skyframe 或永久性操作缓存）则不涵盖在内， 。 no-remote-cache 关键字导致操作或测试永远无法 远程缓存（但可以在本地缓存；也可以远程执行）。 注意：就此标记而言，磁盘缓存被视为本地缓存， 而 HTTP 和 gRPC 缓存则被视为远程缓存。其他缓存，例如 SkyFrame 或永久性操作缓存不受影响。 如果使用了本地磁盘缓存和远程缓存的组合（组合缓存）， 则会被视为远程缓存并完全停用，除非 --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 个关键字阻止对 从沙盒内部访问网络在这种情况下，只有通信 本地主机。只有当沙盒环境已启用时， 。 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 命令）。它不会 会影响其他上下文中的目标通配符或测试套件扩展，包括 query 命令。请注意，manual 并不意味着目标应 不能由连续构建/测试系统自动构建/运行。例如， 从bazel test ...中排除某个目标，因为它需要 运行 Bazel 标志，但仍包含在正确配置的提交前测试或持续测试中 。 external 个关键字将强制测试无条件 已执行（无论 --cache_test_results 值）。 请参阅 代码规范 ，了解有关附加至测试目标的标记的更多惯例。
target_compatible_with	标签列表；默认值为 [] 一系列 constraint_value 秒 必须出现在目标平台中，系统才会考虑此目标 兼容。这是对由 规则类型。如果目标平台不符合列出的所有限制条件，则 该定位条件会被视为不兼容。不兼容的目标包括 在目标模式展开时跳过构建和测试 （例如 //...、:all）。在 不兼容的目标，则不兼容会导致 Bazel 输出错误 构建或测试失败 间接依赖于不兼容目标的目标本身就是 视为不兼容。构建和测试时会跳过这些测试。 空列表（这是默认值）表示目标兼容 支持所有平台 除工作区规则之外的所有规则都支持此项 属性。 对于某些规则，此属性无效。例如，指定 target_compatible_with代表 cc_toolchain 没用。 请参阅 平台 页，详细了解不兼容的跳过目标。
testonly	布尔值；不可配置；默认值为 False （测试套件目标和测试套件目标除外） 如果为 True，则只有 testonly 目标（例如测试）可以依赖于此目标。 与之类似，非 testonly 的规则不允许 依赖于任何为 testonly 的规则。 测试（*_test 条规则） 和测试套件（test_suite 规则） 为 testonly。 此属性旨在表明，不得使用 包含在已发布正式版的二进制文件中包含的文件。 因为 testonly 在构建时强制执行，在运行时不会强制执行，并且会传播 因此应谨慎应用。对于 例如存根和伪造 对于单元测试很有用；对于集成测试 包含将要发布到生产环境的相同二进制文件；以及 因此可能不应标记为 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 package（如果已指定），或 "//visibility:private" 否则 目标上的 visibility 属性用于控制目标 可在其他软件包中使用请参阅有关 visibility。

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

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

属性	说明
args	字符串列表；受制于 $(location) 和 创建变量" 替换以及 Bourne shell 令牌化；默认值为 [] Bazel 传递给目标的命令行参数 使用 bazel test 执行。 这些参数会在任何 --test_arg 值之前传递 bazel test 命令行中所指定。
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" 指定测试目标的“重量”：测试需要运行多长时间/资源。 单元测试被视为“小型测试”，集成测试被视为“中测试”，端到端测试被视为“大型测试”或 “enormous”。Bazel 会根据该大小确定默认超时，您可以使用 timeout 属性。超时针对的是 BUILD 目标中的所有测试，而不是每个测试 单个测试在本地运行测试时，size 会额外用于 安排：Bazel 会尝试遵循 --local_{ram,cpu}_resources，而不是 同时运行大量密集测试会使本地计算机不堪重负。 测试大小对应于以下默认超时和假设的本地资源峰值 使用： 大小 RAM（以 MB 为单位） CPU（在 CPU 核心中） 默认超时 小 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) 和 创建变量" 替换以及 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 文件中定义构建规则时，您要明确 在软件包中声明新的已命名规则目标很多 build 规则 函数还隐式包含一个或多个输出文件 目标，其内容和含义因规则而异。 例如，当您明确声明 java_binary(name='foo', ...) 条规则，您也是 隐式声明输出文件 将 foo_deploy.jar 定位为同一软件包的成员。 （此特定目标是一个独立的 Java 归档， 进行部署。）

隐式输出目标是全局 目标图表。与其他目标一样，它们是按需构建的 在顶级 build 命令中指定，或者当 是其他 build 目标的必要前提条件。它们可以是 在 BUILD 文件中作为依赖项引用，可在 bazel query 等分析工具的输出。

对于每种构建规则，规则的文档都包含 特殊部分，详细说明任何隐式 该规则声明所需的输出。

这两种广告之间 构建系统使用的两个命名空间： 标签用于标识目标 也就是规则或文件。文件目标可分为 源（或输入）文件目标和派生（或输出）文件 目标。以下是您可以在 BUILD 文件中提及的内容， 从命令行构建或使用 bazel query 进行检查； 这就是目标命名空间。每个文件目标都对应着 磁盘上的一个实际文件（“文件系统命名空间”）；每条规则 目标可以对应于磁盘上的零个、一个或多个实际文件。 磁盘上可能存在没有对应目标的文件；用于 例如，在 C++ 编译期间生成的 .o 对象文件 不可从 BUILD 文件或命令行中引用。 这样，构建工具可能会隐藏 工作方式有关详情，请参阅 BUILD 概念参考。