.bzl 文件

报告问题

本页面包含所有 .bzl 文件中可用的全局方法。

会员

分析测试转换

transition analysis_test_transition(settings)

创建要应用于分析测试规则依赖项的配置转换。此过渡只能应用于采用 analysis_test = True 的规则的属性。由于此类规则在功能上受到限制（例如，其依赖项树的大小有限），因此与使用 transition() 创建的转换相比，使用此函数创建的转换在潜在范围内会受到限制。

此函数主要用于协助分析测试框架核心库。有关最佳实践，请参阅其文档（或其实现）。

参数

参数 说明
settings 必需
一个字典，其中包含有关应通过此配置转换设置的配置设置的信息。键是 build 设置标签，值是其转换后的新值。其他所有设置保持不变。使用此参数可声明分析测试需要通过的特定配置设置才能通过。

切面

Aspect aspect(implementation, attr_aspects=[], attrs=None, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None)

创建新的宽高比。此函数的结果必须存储在全局值中。如需了解详情，请参阅 Aspects 简介。

参数

参数 说明
implementation 必需
用于实现此宽高比的 Starlark 函数，恰好有两个参数：目标（应用宽高比的目标）和 ctx（作为目标创建的规则上下文）。目标的属性可通过 ctx.rule 字段获取。在分析阶段中，系统会针对目标的每个方面评估此函数。
attr_aspects sequence of strings; default = []
属性名称列表。该宽高比会传播到具有这些名称的目标的属性中指定的依赖项。常用值包括 deps 和 exports。该列表还可以包含一个字符串，以沿目标的所有依赖项传播。"*"
attrs dict; or None; default = None
一个声明方面所有属性的字典。它会从属性名称映射到属性对象，例如“attr.label”或“attr.string”（请参阅 attr 模块）。宽高比属性可作为 ctx 参数的字段提供给实现函数。

以 _ 开头的隐式属性必须具有默认值，且类型为 label 或 label_list。

显式属性必须具有 string 类型，并且必须使用 values 限制。显式属性会限制相应元素只能用于具有名称、类型和有效值的属性（根据限制）的规则。
required_providers default = []
此属性可允许相应宽高比仅传播其规则宣传其所需提供商的目标。该值必须是包含单个提供商或供应商列表的列表，不能同时包含两者。例如，[[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值，而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 是无效值。

解除嵌套的提供商列表将自动转换为一份提供商列表。也就是说，[FooInfo, BarInfo] 将自动转换为 [[FooInfo, BarInfo]]。

要让某个规则能够看到某些规则（例如 some_rule）目标，some_rule 必须通告至少一个必需的提供方列表中的所有提供方。例如，如果宽高比的 required_providers 为 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]]，当且仅当 some_rule 提供 FooInfo、BarInfo 和/或 BazInfo 和 QuxInfo 时，此方面才能看到 some_rule 目标。

required_aspect_providers default = []
此属性允许该方面检查其他方面。该值必须是包含单个提供商或供应商列表的列表，不能同时包含两者。例如，[[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值，而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 是无效值。

解除嵌套的提供商列表将自动转换为一份提供商列表。也就是说，[FooInfo, BarInfo] 将自动转换为 [[FooInfo, BarInfo]]。

如需显示另一个方面的信息（例如 other_aspect），other_aspect 必须至少提供一个列表中的所有提供商。在 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 的示例中，当且仅当 other_aspect 提供 FooInfo、或 BarInfo 或 BazInfo 和 QuxInfo 时，这方面才会看到 other_aspect。
provides default = []
实现函数必须返回的提供程序列表。

如果实现函数从返回值中省略了此处列出的任何类型的提供程序，则会发生错误。不过，实现函数可能会返回此处未列出的其他提供程序。

该列表的每个元素都是 provider() 返回的 *Info 对象，不过旧版提供程序由其字符串名称表示。当规则的目标用作声明必需提供程序的目标的依赖项时，无需在此处指定该提供程序。实现函数只需返回该值即可。不过，尽管这并非强制性要求，但这属于最佳做法。不过，方面的 required_providers 字段要求在此处指定提供程序。

requires sequence of Aspects; default = []
必须在此宽高比之前传播的各个方面。
fragments sequence of strings; default = []
在目标配置中，相应方面所需的配置 Fragment 的名称列表。
host_fragments sequence of strings; default = []
主机配置中所需的相应配置 Fragment 的名称列表。
toolchains sequence; default = []
如果已设置，则此规则需要的工具链集。该列表可以包含任何组合形式的 String、Label 或 StarlarkToolchainTypeApi 对象。系统会通过检查当前平台找到工具链，并通过 ctx.toolchain 提供给规则实现。
incompatible_use_toolchain_transition default = False
已弃用，不再使用，应移除。
doc string; or None; default = None
可通过文档生成工具提取的方面说明。
apply_to_generating_rules default = False
如果为 true，则宽高比将应用于输出文件，但应用于输出文件的生成规则。

例如，假设某个构面通过属性“deps”传播，并且已应用于目标“alpha”。假设“alpha”具有“deps = [':beta_output']”，其中“beta_output”是目标“beta”的声明输出。假设“beta”的目标为“charlie”作为其“deps”。如果“apply_to_generate.与 {1>”进行关联，则前者必须经过上述测试。

默认为 false。
exec_compatible_with sequence of strings; default = []
适用于此方面所有实例的执行平台上的约束列表。
exec_groups dict; or None；默认值 = None
执行组名称（字符串）的记录为 exec_groups。如果设置此标记，便可以在单个实例中针对多个执行平台执行操作。如需了解详情，请参阅执行组文档。

配置字段

LateBoundDefault configuration_field(fragment, name)

引用标签类型的特性的后期默认值。如果某个值要求先构建配置，然后再确定该值，则该值为“滞后值”。任何将此值用作值的属性都必须不公开。

用法示例：

定义规则属性：

'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))

在规则实现中访问：

  def _rule_impl(ctx):
    foo_info = ctx.attr._foo
    ...

参数

参数 说明
fragment 必需
包含后期值的配置 Fragment 的名称。
name 必需
从配置 fragment 获取的值的名称。

偏移量

depset depset(direct=None, order="default", *, transitive=None)

创建偏移量。direct 参数是依赖项的直接元素列表，transitive 参数是一个依赖项的列表，其元素成为所创建依赖项的间接元素。从偏移量转换为列表时，元素返回的顺序由 order 参数指定。如需了解详情，请参阅依赖项概览。

依赖项的所有元素（直接和间接）都必须采用表达式 type(x) 相同的类型。

由于基于哈希的集合用于在迭代期间消除重复，因此依赖项的所有元素都应该可进行哈希处理。但是，目前并非所有构造函数都会一致检查此不变。使用 --incompatible_Always_check_depset_elements 标志实现一致性检查；这将会是未来版本中的默认行为；请参阅问题 10313。

此外，元素目前是不可变的，但这种限制将来会放宽。

已创建的依赖项的顺序应与其 transitive 依赖项的顺序兼容。"default" 订单与任何其他订单兼容，其他所有订单仅与自身兼容。

关于向后/向前兼容性的说明。此函数目前接受位置 items 参数。此版本已弃用，日后将被移除。移除后，direct 将成为 depset 函数的唯一位置参数。因此，以下两项调用是等效且可满足未来需求的调用：

depset(['a', 'b'], transitive = [...])
depset(direct = ['a', 'b'], transitive = [...])

参数

参数 说明
direct sequence; or None; default = None
依赖项的“直接”元素列表。
order default = "default"
新依赖项的遍历策略。如需了解可能的值，请参阅此处。
transitive sequence of depsets; or None; default = None
一系列依赖项，其元素将变为依赖项的间接元素。

高管群组

exec_group exec_group(toolchains=[], exec_compatible_with=[])

创建一个执行组，用于在执行规则期间为特定执行平台创建操作。

参数

参数 说明
toolchains sequence; default = []
此执行组所需的一组工具链。该列表可以包含任何组合形式的 String、Label 或 StarlarkToolchainTypeApi 对象。
exec_compatible_with sequence of strings; default = []
执行平台上的约束列表。

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc='')

创建新的模块扩展。请将其存储在全局值中，以便导出可在 MODULE.bazel 文件中使用。

参数

参数 说明
implementation 必需
用于实现此模块扩展的函数。必须接受一个参数，即 module_ctx。在构建开始时，系统会调用该函数一次，以确定一组可用的代码库。
tag_classes default = {}
用于声明扩展程序使用的所有标记类的字典。它会从标记类的名称映射到 tag_class 对象。
doc default = ''
可通过生成工具的文档提取的模块扩展的说明。

provider

unknown provider(doc=None, *, fields=None, init=None)

定义提供程序符号。提供程序可通过调用对其进行实例化，也可以直接用作键，从目标中检索该提供程序的实例。示例：
MyInfo = provider()
...
def _my_library_impl(ctx):
    ...
    my_info = MyInfo(x = 2, y = 3)
    # my_info.x == 2
    # my_info.y == 3
    ...

如需查看有关如何使用提供程序的全面指南，请参阅规则（提供程序）。

如果未指定 init，则返回 Provider Callable 值。

如果指定了 init，则返回一个包含 2 个元素的元组：Provider Callable 值和原始构造函数 Callable 值。如需了解详情，请参阅 规则（自定义提供程序的自定义初始化）以及对 init 参数的讨论。

参数

参数 说明
doc string; or None; default = None
对可通过文档生成工具提取的提供程序的说明。
fields sequence of strings; or dict; or None; default = None
如果指定，系统会限制允许的字段集。
可能的值包括：
  • 字段列表：
    provider(fields = ['a', 'b'])

  • 字典字段名称 -> 文档：
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
所有字段均为选填。
init callable; or None; default = None
在初始化期间预处理和验证提供程序字段值的可选回调函数。如果指定了 init，provider() 会返回一个包含 2 个元素的元组：常规提供程序符号和原始构造函数。

确切的说明如下所示；如需直观的讨论和用例，请参阅规则（提供程序的自定义初始化）。

让 P 成为通过调用 provider() 创建的提供程序符号。从概念上讲，通过调用默认构造函数 c(*args, **kwargs) 生成 P 实例，该函数会执行以下操作：

  • 如果 args 不为空，则会发生错误。
  • 如果在调用 provider() 时指定了 fields 参数，并且 kwargs 中包含未在 fields 中列出的任何键，则会发生错误。
  • 否则，c 会返回一个新实例，对于 kwargs 中的每个 k: v 条目，名为 k 且值为 v 的字段。
如果未提供 init 回调函数，则对符号 P 本身的调用将充当对默认构造函数 c 的调用；换言之，P(*args, **kwargs) 会返回 c(*args, **kwargs)。例如，
MyInfo = provider()
m = MyInfo(foo = 1)
将直接让其设为 m 为 m.foo == 1 的 MyInfo 实例。

但如果指定了 init，调用 P(*args, **kwargs) 将改为执行以下步骤：

  1. 以 init(*args, **kwargs) 的形式调用该回调函数，即，其位置和关键字参数与传递给 P 的位置参数完全相同。
  2. init 的返回值应为字典 d，其键为字段名称字符串。否则，则会出现错误。
  3. 生成 P 的新实例就像通过将 d 的条目作为关键字参数调用默认构造函数一样（如 c(**d) 中所示）。

注意：如果 *args 或 **kwargs 与 init 的签名不匹配，或者 init 正文的评估失败（可能是有意通过调用 fail()），或者 init 的返回值不是具有预期架构的字典，那么上述步骤意味着出错。

这样，init 回调允许位置参数和任意逻辑来进行预处理和验证，从而对常规提供程序构造进行泛化。这不会规避规避的 fields 列表。

指定 init 后，provider() 的返回值会变为元组 (P, r)，其中 r 是原始构造函数。实际上，r 的行为与上文讨论的默认构造函数 c 的行为完全相同。通常，r 会绑定到一个名称带有下划线前缀的变量，以便只有当前的 .bzl 文件可以直接访问它：

MyInfo, _new_myinfo = provider(init = ...)

代码库规则

callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc='')

创建新的代码库规则。请将其存储在全局值中，以便可以从 WORKSPACE 文件加载和调用它。

参数

参数 说明
implementation 必需
实现此规则的函数。必须只包含一个参数 repository_ctx。在加载规则的过程中，系统会为规则的每个实例调用该函数。
attrs dict; or None; default = None
用于声明规则的所有属性。它会从属性名称映射到属性对象（请参阅 attr 模块）。以 _ 开头的属性是不公开的，可用于将标签隐式添加到文件中（代码库规则不能依赖于生成的工件）。属性 name 是隐式添加的，不得指定。
local default = False
表示此规则从本地系统提取所有内容，应在每次提取时重新评估。
environ sequence of strings; default = []
提供此代码库规则所依赖的环境变量的列表。如果该列表中的某个环境变量发生更改，系统将重新提取代码库。
configure default = False
表示代码库用于检查系统是否存在配置问题
remotable default = False
实验性。此参数是实验性参数，随时可能会更改。请勿依赖它。可以通过设置 ---experimental_repo_remote_exec
与远程执行兼容 来在实验阶段启用它
doc default = ''
可通过文档生成工具提取的代码库规则的说明。

规则

callable rule(implementation, test=False, attrs=None, outputs=None, executable=False, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, provides=[], exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, compile_one_filetype=None, name=None)

创建新规则。该规则可通过 BUILD 文件或宏调用，以创建目标。

规则必须分配给 .bzl 文件中的全局变量；全局变量的名称是规则的名称。

测试规则的名称必须以 _test 结尾，而所有其他规则均不得使用此后缀。（此限制仅适用于规则，不适用于其目标。）

参数

参数 说明
implementation 必需
实现此规则的 Starlark 函数必须只有一个参数：ctx。在分析的每一个规则实例阶段都会调用该函数。它可以访问用户提供的属性。它必须创建操作来生成所有声明的输出。
test default = False
此规则是否为测试规则，即是否是 blaze test 命令的正文。所有测试规则都会自动被视为可执行；您无需（和不建议）为测试规则明确设置 executable = True。如需了解详情，请参阅 “规则”页面。
attrs dict; or None; default = None
用于声明规则的所有属性。它会从属性名称映射到属性对象（请参阅 attr 模块）。以 _ 开头的属性是私有属性，可用于为标签添加隐式依赖项。属性 name 是隐式添加的，不得指定。visibility、deprecation、tags、testonly 和 features 属性是隐式添加的，无法替换。大多数规则只需要少量属性。为了限制内存用量，规则函数对属性的大小施加了上限。
outputs dict; or None; or function; default = None
已弃用。此参数已被弃用，很快就会被移除。请勿依赖它。该功能在 ---incompatible_no_rule_outputs_param 中已停用。使用此标记可确认您的代码与即将移除的代码兼容。
此参数已被弃用。请迁移规则以改用 OutputGroupInfo 或 attr.output。

用于定义预先声明的输出的架构。与 output 和 output_list 属性不同，用户不为这些文件指定标签。如需详细了解预先声明的输出，请参阅“规则”页面。

该参数的值是一个字典或一个生成字典的回调函数。回调的工作方式类似于计算的依赖项属性：函数的参数名称与规则的属性匹配，因此，如果您传递带有定义 def _my_func(srcs, deps): ... 的 outputs = _my_func，函数可以访问属性 srcs 和 deps。字典是直接指定的，还是通过函数指定的，都会按如下方式解读。

字典中的每个条目都会创建一个预先声明的输出，其中键是一个标识符，而值是一个字符串模板，用于确定输出的标签。在规则的实现函数中，标识符将成为用于访问 ctx.outputs 中输出 File 的字段名称。输出标签的软件包与规则的软件包相同，并且通过将 "%{ATTR}" 形式的每个占位符替换为由 ATTR 属性值构成的字符串来生成软件包之后的部分：

  • 字符串类型的属性将一字不差地进行替换。
  • 标签类型属性成为软件包后标签的一部分，减去文件扩展名。例如，标签 "//pkg:a/b.c" 会变为 "a/b"。
  • 输出类型的属性成为软件包后面的标签部分，包括文件扩展名（对于上述示例，"a/b.c"）。
  • 占位符中使用的所有列表类型属性（例如 attr.label_list）都必须只有一个元素。转换版本与非名单版本 (attr.label) 相同。
  • 其他属性类型可能不会在占位符中显示。
  • 特殊非属性占位符 %{dirname} 和 %{basename} 会展开为规则标签的各个部分（不包括其软件包）。例如，在 "//pkg:a/b.c" 中，目录名称为 a，基名为 b.c。

实际上，最常见的替换占位符是 "%{name}"。例如，对于名为“foo”的目标，输出字典 {"bin": "%{name}.exe"} 预先声明了一个名为 foo.exe 的输出，该输出可在实现函数中访问为 ctx.outputs.bin。
executable default = False
此规则是否被视为可执行，即，它是否为 blaze run 命令的正文。如需了解详情，请参阅 “规则”页面。
output_to_genfiles default = False
如果为 true，文件会在 genfiles 目录中生成，而不是在 bin 目录中。除非需要兼容现有规则（例如，为 C++ 生成头文件时），否则请勿设置此标志。
fragments sequence of strings; default = []
规则在目标配置中所需的配置 Fragment 的名称列表。
host_fragments sequence of strings; default = []
规则在主机配置中所需的配置 Fragment 的名称列表。
_skylark_testable default = False
（实验性）

如果为 true，此规则将通过依赖于 Actions 提供程序的规则来公开其操作。规则本身也可以通过调用 ctx.created_actions() 来访问提供程序。

此测试您应仅用于测试 Starlark 规则的分析时行为。此标志将来可能会被移除。
toolchains sequence; default = []
如果已设置，则此规则需要的工具链集。该列表可以包含任何组合形式的 String、Label 或 StarlarkToolchainTypeApi 对象。系统会通过检查当前平台找到工具链，并通过 ctx.toolchain 提供给规则实现。
incompatible_use_toolchain_transition default = False
已弃用，不再使用，应移除。
doc string; or None; default = None
通过生成工具可提取的规则的说明。
provides default = []
实现函数必须返回的提供程序列表。

如果实现函数从返回值中省略了此处列出的任何类型的提供程序，则会发生错误。不过，实现函数可能会返回此处未列出的其他提供程序。

该列表的每个元素都是 provider() 返回的 *Info 对象，不过旧版提供程序由其字符串名称表示。当规则的目标用作声明必需提供程序的目标的依赖项时，无需在此处指定该提供程序。实现函数只需返回该值即可。不过，尽管这并非强制性要求，但这属于最佳做法。不过，方面的 required_providers 字段要求在此处指定提供程序。

exec_compatible_with sequence of strings; default = []
针对执行此规则类型的所有目标的执行平台上的约束列表。
analysis_test default = False
如果为 true，则将此规则视为分析测试。

注意：分析测试规则主要使用 Starlark 核心库中提供的基础架构定义。如需指导，请参阅测试。

如果将规则定义为分析测试规则，则允许对其属性使用通过 analysis_test_transition 定义的配置转换，但您可以选择启用一些限制：

  • 此规则的目标在传递时可能具有的传递依赖项数量有限。
  • 该规则被视为测试规则（就像设置了 test=True 一样）。这取代了 test 的值
  • 规则实现函数不得注册操作。相反，它必须通过提供 AnalysisTestResultInfo 来注册通过/失败结果。
build_setting BuildSetting; or None; default = None
设置后，描述此规则的 build setting 类型。请参阅 config 模块。如果设置此属性，系统会自动向规则添加一个名为“build_setting_default”的必需属性，其类型与在此处传入的值相对应。
cfg default = None
如果设置此参数，则在分析之前，系统会将规则应用于其自己的配置转换。
exec_groups dict; or None；默认值 = None
执行组名称（字符串）的记录为 exec_groups。设置后，规则将允许在单个目标内的多个执行平台上执行操作。如需了解详情，请参阅执行组文档。
compile_one_filetype sequence of strings; or None; default = None
供 --compile_one_dependency 使用：如果多条规则使用指定的文件，我们是否应该选择此规则而不是其他规则。
name string; or None; default = None
已弃用。此参数已被弃用，很快就会被移除。请勿依赖它。该功能在 --+incompatible_remove_rule_name_parameter 中已停用。使用此标记可确认您的代码与即将移除的代码兼容。
已弃用：请勿使用。

此规则的名称，由 Bazel 理解，并在日志记录、native.existing_rule(...)[kind] 和 bazel query 等上下文中报告。这通常与绑定到此规则的 Starlark 标识符相同；例如，名为 foo_library 的规则通常声明为 foo_library = rule(...)，并在 BUILD 文件中将其实例化为 foo_library(...)。

如果省略此参数，则系统会将规则的名称设置为在声明的 .bzl 模块中绑定到此规则的第一个 Starlark 全局变量的名称。因此，如果名称为 foo_library，则 foo_library = rule(...) 无需指定此参数。

为规则指定明确的名称不会更改您可以实例化规则的位置。

select

unknown select(x, no_match_error='')

select() 是一个辅助函数，用于使规则属性可配置。如需了解详情，请参阅构建百科全书。

参数

参数 说明
x 必需
用于将配置条件映射到值的字典。每个键都是一个 label 或标签字符串，用于标识 config_setting 或 constraint_value 实例。如需了解何时使用标签而不是字符串，请参阅关于宏的文档。
no_match_error default = ''
可选的自定义错误，在没有条件匹配时进行报告。

tag_class

tag_class tag_class(attrs={}, *, doc='')

创建一个新的 tag_class 对象，该对象定义了一个代码类的属性架构，该类是可供模块扩展使用的数据对象。

参数

参数 说明
attrs default = {}
用于声明此标记类的所有属性的字典。它会从属性名称映射到属性对象（请参阅 attr 模块）。
doc default = ''
可通过文档生成工具提取的标记类的说明。

visibility

None visibility(value)

设置当前初始化的 .bzl 模块的负载可见性。

模块的负载可见性决定了其他 BUILD 和 .bzl 文件能否加载模块。（这与底层 .bzl 源文件的目标可见性不同，后者规定文件是否可能显示为其他目标的依赖项。）加载可见性位于软件包级别：要加载模块，正在加载的文件必须位于模块可见的软件包中。无论模块是否可见，始终都可以在自己的模块中加载。

visibility() 只能在每个 .bzl 文件中调用一次，并且只能在顶层调用，不能在函数内调用。首选样式是将此调用放在 load() 语句以及确定该参数所需的任何简短逻辑的正下方。

如果 --check_bzl_visibility 标志设置为 false，则出现可见性违规行为会发出警告，但不会使 build 失败。

参数

参数 说明
value 必需
软件包规范字符串或单个软件包规范字符串的列表。

软件包规格遵循与 package_group 相同的格式，但不允许使用排除的软件包规格。也就是说，规范可能采用以下格式：

  • "//foo"：软件包 //foo
  • "//foo/..."：软件包 //foo 及其所有子软件包。
  • "public" 或 "private"：分别显示所有软件包或没有软件包

不允许使用“@”语法；所有规范均相对于当前模块的代码库进行解释。

如果 value 是字符串列表，则向此模块授予的软件包集是各规范所表示的软件包的并集。（空列表与 private 具有相同的效果。）如果 value 是单个字符串，则会被视为单例列表 [value]。

请注意，--incompatible_package_group_has_public_syntax 和 --incompatible_fix_package_group_reporoot_syntax 标志对此参数没有任何影响。"public" 和 "private" 值始终可用，并且 "//..." 始终解释为“当前代码库中的所有软件包”。