常见定义

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

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

目录

Bourne shell 令牌化

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

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

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

标签展开

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

例如,genrule.cmdcc_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

标签列表;默认值为 []

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

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

所有构建规则通用的属性

本部分介绍了隐式添加到所有 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 发现以下内容,就会修改其沙盒代码的行为 任何测试或 genruletags 属性中的关键字 target 或 execution_requirements 的键(适用于任何 Starlark) 操作。

  • no-sandbox 关键字导致操作或测试永远无法 沙盒它仍然可以缓存或远程运行 - 请使用 no-cacheno-remote 来阻止其中之一或同时阻止二者。
  • no-cache 关键字导致操作或测试永远无法 缓存内容(本地或远程)。注意:就此标记而言,磁盘缓存 系统会将 HTTP 和 gRPC 缓存视为本地缓存 遥控器。其他缓存(如 Skyframe 或永久性操作缓存)则不涵盖在内, 。
  • no-remote-cache 关键字导致操作或测试永远无法 远程缓存(但可以在本地缓存;也可以远程执行)。 注意:就此标记而言,磁盘缓存被视为本地缓存, 而 HTTP 和 gRPC 缓存则被视为远程缓存。其他缓存,例如 SkyFrame 或永久性操作缓存不受影响。 如果使用了本地磁盘缓存和远程缓存的组合(组合缓存), 则会被视为远程缓存并完全停用,除非 --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 个关键字阻止对 从沙盒内部访问网络在这种情况下,只有通信 本地主机。只有当沙盒环境已启用时, 。
  • 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

标签列表;默认值为 []

一系列 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_toolchainjava_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_testpy_testsh_test。它不适用于 Starlark 定义的测试规则。对于您自己的 Starlark 规则,您可以添加“env” 属性并使用它来填充 TestEnvironment 提供商。

env_inherit

字符串列表;默认值为 []

指定要从 外部环境。bazel test

此属性仅适用于原生规则,例如 cc_testpy_testsh_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_binarypy_binarysh_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_settingconstraint_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 概念参考