全局变量

在全局环境中注册的对象、函数和模块。

成员

全部

bool all(elements)

如果所有元素的计算结果均为 True 或集合为空，则返回 true。元素通过 bool 函数转换为布尔值。
all(["hello", 3, True]) == True
all([-1, 0, 1]) == False

参数

参数 说明
elements 必需
一个字符串或一系列元素。

analysis_test_transition

transition analysis_test_transition(settings)

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

此函数主要用于为分析测试框架核心库提供支持。如需了解最佳实践，请参阅其文档（或其实现）。

参数

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

任意

bool any(elements)

如果至少有一个元素的计算结果为 True，则返回 true。元素通过 bool 函数转换为布尔值。
any([-1, 0, 1]) == True
any([False, 0, ""]) == False

参数

参数 说明
elements 必需
一个字符串或一系列元素。

archive_override

None archive_override(module_name, urls, integrity='', strip_prefix='', patches=[], patch_cmds=[], patch_strip=0)

指定此依赖项应来自特定位置的归档文件（zip、gzip 等），而不是来自注册表。该指令只能由根模块使用；换句话说，如果某个模块指定了任何替换项，则无法将其用作依赖项。

参数

参数 说明
module_name 必需
要应用此替换项的 Bazel 模块依赖项的名称。
urls string; or Iterable of strings； 必需
归档的网址；可以是 http(s):// 或 file:// 网址。
integrity 默认值 = ''
归档文件的预期校验和，采用子资源完整性格式。
strip_prefix 默认值 = ''
要从提取的文件中删除的目录前缀。
patches Iterable of strings； 默认值 = []
指向要应用于此模块的补丁文件的标签列表。补丁文件必须存在于顶级项目的源代码树中。它们按列表顺序应用。
patch_cmds Iterable of strings； 默认值 = []
应用补丁后，要应用于 Linux/Macos 的一系列 Bash 命令。
patch_strip 默认值 = 0
与 Unix 补丁的 --strip 参数相同。

切面

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

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

参数

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

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

显式属性的类型必须为 string，且必须使用 values 限制。显式属性将切面限制为只能与根据限制具有相同名称、类型和有效值的规则一起使用。

required_providers 默认值 = []
通过此属性，切面可将其传播范围限制为规则通告其所需提供程序的目标。该值必须是包含单个提供商或提供商列表（但不能同时包含两者）的列表。例如，[[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 默认值 = []
此属性允许此切面检查其他切面。该值必须是包含单个提供商或提供商列表（但不能同时包含两者）的列表。例如，[[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 默认值 = []
实现函数必须返回的提供程序列表。

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

该列表的每个元素都是 provider() 返回的 *Info 对象，但旧版提供程序由其字符串名称表示。

requires sequence of Aspects； 默认值 = []
此切面之前需要传播的切面的列表。
fragments sequence of strings； 默认值 = []
切面在目标配置中所需的配置 fragment 的名称列表。
host_fragments sequence of strings； 默认值 = []
切面在主机配置中所需的配置 fragment 的名称列表。
toolchains sequence； 默认值 = []
如果设置了此字段，则为此规则所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象，可以任意组合。系统将通过检查当前平台找到工具链，并通过 ctx.toolchain 将其提供给规则实现。
incompatible_use_toolchain_transition 默认值 = False
已弃用，已不再使用此属性，应将其移除。
doc 默认值 = ''
可通过文档生成工具提取的方面的说明。
apply_to_generating_rules 默认值 = False
如果为 true，该切面在应用于输出文件时，将应用于输出文件的生成规则。

例如，假设某个切面通过属性 `deps` 传递性传播，并应用于目标 `alpha`。假设 `alpha` 具有 `deps = [':beta_output']`，其中 `beta_output` 是目标 `beta` 的声明输出。假设 `beta` 将目标 `charlie` 作为其 `deps` 中的一个。如果切面的 `apply_to_generating_rules=True`，则切面将通过 `alpha`、`beta` 和 `charlie` 传播。如果为 False，则切面将仅传播到 `alpha`。

默认值为 false。
exec_compatible_with sequence of strings； 默认值 = []
执行平台上适用于此切面所有实例的限制条件列表。
exec_groups dict; or None； 默认 = 无
从“exec_group”中复制执行组名称（字符串）。如果设置，则允许切面在单个实例中的多个执行平台上运行操作。如需了解详情，请参阅执行组文档。

bazel_dep

None bazel_dep(name, version='', max_compatibility_level=-1, repo_name='', dev_dependency=False)

声明对另一个 Bazel 模块的直接依赖项。

参数

参数 说明
name 必需
要作为直接依赖项添加的模块的名称。
version 默认值 = ''
要作为直接依赖项添加的模块的版本。
max_compatibility_level 默认值 = -1
支持将模块添加为直接依赖项的最大 compatibility_level。模块的版本暗含了支持的最低兼容性级别以及未指定此属性的最高级别。
repo_name 默认值 = ''
表示此依赖项的外部代码库的名称。默认情况下，这是模块的名称。
dev_dependency 默认值 = False
如果为 true，如果当前模块不是根模块或已启用 `--ignore_dev_dependency`，系统会忽略此依赖项。

绑定

None bind(name, actual=None)

警告：不建议使用 bind()。请参阅考虑移除绑定，查看有关其问题和替代方案的详尽讨论。

在 //external 软件包中为目标提供别名。

参数

参数 说明
name 必需
“//external”下的标签用作别名
actual string; or None； 默认 = 无
要别名化的真实标签

bool

bool bool(x=False)

bool 类型的构造函数。如果对象为 None、False、空字符串 ("")、数字 0 或空集合（例如 ()、[]），则该方法会返回 False。否则，它会返回 True。

参数

参数 说明
x 默认值 = False
要转换的变量。

configuration_field

LateBoundDefault configuration_field(fragment, name)

引用 label 类型的属性的后期绑定默认值。值为“后期绑定”可能需要在确定值之前构建配置。任何使用此用作值的属性都必须不公开。

用法示例：

定义规则属性：

'_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)

创建一个 depset。direct 参数是一个 Depset 的直接元素列表，transitive 参数是一个 Depset 列表，其元素会成为已创建的 Depset 的间接元素。将 depset 转换为列表时，返回元素的顺序由 order 参数指定。如需了解详情，请参阅设置概览。

已弃用的所有元素（直接和间接）都必须属于同一种类型，可通过表达式 type(x) 获取。

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

此外，元素目前必须是不可变的，尽管将来会放宽此限制。

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

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

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

参数

参数 说明
direct sequence; or None； 默认 = 无
Depset 的 direct 元素列表。
order 默认 =“默认”
新出发集的遍历策略。请参阅此处了解可能的值。
transitive sequence of depsets; or None； 默认 = 无
一个废弃设置列表，其中的元素将成为其间接元素。

字典

dict dict(pairs=[], **kwargs)

根据可选的位置参数和一组可选的关键字参数创建字典。如果多次指定同一个键，将使用最后一个值。系统会将通过关键字参数提供的条目视为在通过位置参数提供的条目之后。

参数

参数 说明
pairs 默认值 = []
一个字典或可迭代对象，其元素均长度为 2（键、值）。
kwargs 必需
其他条目的字典。

dir

list dir(x)

返回字符串列表：参数对象的属性和方法的名称。

参数

参数 说明
x 必需
要检查的对象。

枚举

list enumerate(list, start=0)

返回一列对（二元素元组）及其索引 (int) 以及输入序列中的项。 
enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]

参数

参数 说明
list 必需
输入序列。
start 默认值 = 0
开始索引。

exec_group

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

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

参数

参数 说明
toolchains sequence； 默认值 = []
此执行组所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象，可以任意组合。
exec_compatible_with sequence of strings； 默认值 = []
执行平台上的约束条件列表。
copy_from_rule 默认值 = False
如果设为 true，此执行组将继承该组附加到的规则的工具链和限制条件。如果设置为任何其他字符串，则会抛出错误。

fail

None fail(msg=None, attr=None, *args)

导致执行失败并显示错误。

参数

参数 说明
msg 默认值 = 无
已弃用：请改用位置参数。此参数充当隐式前置位置参数。
attr string; or None； 默认 = 无
已弃用。用于将包含此字符串的可选前缀添加到错误消息中。
args 必需
错误消息中显示的值列表，采用 str 格式并以空格连接。

float

float float(x=unbound)

以浮点值形式返回 x。<ph type="x-smartling-placeholder">
    </ph>
  • 如果 x 已经是浮点数，则 float 不会原样返回它。
  • 如果 x 为布尔值，则 float 对 True 返回 1.0，对于 False 返回 0.0。
  • 如果 x 是整数，float 会返回与 x 最接近的有限浮点值；如果大小过大，则返回错误。
  • 如果 x 是一个字符串，它必须是有效的浮点字面量，或者等于（忽略大小写）NaN、Inf 或 Infinity，可以选择性地在前面加上 + 或 - 符号。
任何其他值都会导致错误。如果没有参数，float() 会返回 0.0。

参数

参数 说明
x 默认值 = 未绑定
要转换的值。

getattr

unknown getattr(x, name, default=unbound)

返回具有给定名称的结构字段（如果存在）。否则，它将返回 default（如果已指定）或引发错误。getattr(x, "foobar") 相当于 x.foobar。
getattr(ctx.attr, "myattr")
getattr(ctx.attr, "myattr", "mydefault")

参数

参数 说明
x 必需
要访问其属性的结构体。
name 必需
结构体属性的名称。
default 默认值 = 未绑定
结构体没有给定名称的属性时要返回的默认值。

git_override

None git_override(module_name, remote, commit='', patches=[], patch_cmds=[], patch_strip=0)

指定依赖项应来自 Git 代码库的特定提交。该指令只能由根模块使用；换句话说，如果某个模块指定了任何替换项，则无法将其用作依赖项。

参数

参数 说明
module_name 必需
要应用此替换项的 Bazel 模块依赖项的名称。
remote 必需
远程 Git 代码库的网址。
commit 默认值 = ''
应签出的提交。
patches Iterable of strings； 默认值 = []
指向要应用于此模块的补丁文件的标签列表。补丁文件必须存在于顶级项目的源代码树中。它们按列表顺序应用。
patch_cmds Iterable of strings； 默认值 = []
应用补丁后，要应用于 Linux/Macos 的一系列 Bash 命令。
patch_strip 默认值 = 0
与 Unix 补丁的 --strip 参数相同。

hasattr

bool hasattr(x, name)

如果对象 x 具有给定 name 的属性或方法，则返回 True，否则返回 False。示例：
hasattr(ctx.attr, "myattr")

参数

参数 说明
x 必需
要检查的对象。
name 必需
属性的名称。

哈希

int hash(value)

返回字符串的哈希值。它使用与 Java 的 String.hashCode() 相同的算法确定性地计算，即：
s[0] * (31^(n-1)) + s[1] * (31^(n-2)) + ... + s[n-1]
 目前不支持对字符串以外的值进行哈希处理。

参数

参数 说明
value 必需
要哈希处理的字符串值。

int

int int(x, base=unbound)

以整数值的形式返回 x。
  • 如果 x 已经是整数，int 会原封不动地返回该值。
  • 如果 x 为布尔值，int 会针对 True 返回 1，为 False 返回 0。
  • 如果 x 是字符串，则必须采用 <sign><prefix><digits> 格式。<sign> 是 "+"、"-" 或空（解释为正数）。<digits> 是从 0 到 base - 1 的一连串数字，其中字母 a-z（或等效的 A-Z）用作 10-35 的数字。如果 base 为 2/8/16，则 <prefix> 是可选的，分别为 0b/0o/0x（或等效的 0B/0O/0X）；如果 base 是除这些碱基或特殊值 0 之外的任何其他值，则前缀必须为空。如果 base 为 0，则字符串会被解释为整数字面量，因为系统会选择以 2/8/10/16 为基数的其中一个，具体取决于使用了哪个前缀。如果 base 为 0，则不使用前缀，并且有多个数字，则前导数字不能为 0；这是为了避免八进制和十进制混淆。字符串所表示的数字大小必须在 int 类型的允许的范围内。
  • 如果 x 是浮点数，则 int 会返回该浮点数的整数值，向零舍入。如果 x 是非有限值（NaN 或无穷大），则报告错误。
如果 x 是任何其他类型，或者值是不符合上述格式的字符串，则此函数会失败。与 Python 的 int 函数不同，此函数不允许零参数，也不允许字符串参数出现多余的空格。

示例：

int("123") == 123
int("-123") == -123
int("+123") == 123
int("FF", 16) == 255
int("0xFF", 16) == 255
int("10", 0) == 10
int("-0x10", 0) == -16
int("-0x10", 0) == -16
int("123.456") == 123

参数

参数 说明
x 必需
要转换的字符串。
base 默认值 = 未绑定
用于解释字符串值的基数；默认为 10。必须介于 2 到 36 之间（含 2 和 36），或为 0 以检测基数，就像 x 是整数字面量一样。如果值不是字符串，则不能提供此参数。

len

int len(x)

返回字符串、序列（如列表或元组）、字典或其他可迭代对象的长度。

参数

参数 说明
x 必需
要报告其长度的值。

list

list list(x=[])

返回元素与给定可迭代值相同的新列表。
list([1, 2]) == [1, 2]
list((2, 3, 2)) == [2, 3, 2]
list({5: "a", 2: "b", 4: "c"}) == [5, 2, 4]

参数

参数 说明
x 默认值 = []
要转换的对象。

local_path_override

None local_path_override(module_name, path)

指定依赖项应来自本地磁盘上的特定目录。该指令只能由根模块使用；换句话说，如果某个模块指定了任何替换项，则无法将其用作依赖项。

参数

参数 说明
module_name 必需
要应用此替换项的 Bazel 模块依赖项的名称。
path 必需
此模块所在目录的路径。

max

unknown max(*args)

返回所有指定参数中最大的一个。如果只提供一个参数，该参数必须是非空的可迭代对象。如果元素不可比较（例如，整数与字符串），或者未提供任何参数，则会发生错误。
max(2, 5, 4) == 5
max([5, 6, 3]) == 6

参数

参数 说明
args 必需
要检查的元素。

分钟

unknown min(*args)

返回所有指定参数中的最小值。如果只提供一个参数，则该参数必须是非空可迭代对象。如果元素不可进行比较（例如 int 与字符串）或未提供任何参数，则会出错。
min(2, 5, 4) == 2
min([5, 6, 3]) == 3

参数

参数 说明
args 必需
要检查的元素。

module

None module(name='', version='', compatibility_level=0, repo_name='', bazel_compatibility=[])

声明当前 Bazel 代码库表示的 Bazel 模块的某些属性。这些属性要么是模块的基本元数据（例如名称和版本），要么会影响当前模块及其依赖项的行为。

最多只能调用一次。仅当此模块是根模块（例如，不被其他模块依赖）时，才能省略它。

参数

参数 说明
name 默认值 = ''
模块的名称。仅当此模块是根模块（例如，不被其他模块依赖）时，才能省略。有效的模块名称必须：1) 只能包含小写字母 (a-z)、数字 (0-9)、点 (.)、连字符 (-) 和下划线 (_)；2) 以小写字母开头；3) 以小写字母或数字结尾。
version 默认值 = ''
模块的版本。仅当此模块是根模块（例如，不被其他模块依赖）时，才能省略。
compatibility_level 默认值 = 0
模块的兼容性级别；每次引入不兼容的重大更改时，都应更改此名称。这基本上就是SemVer 的相同之处，只不过它并未嵌入版本字符串本身，而是作为单独的字段存在。具有不同兼容性级别的模块会参与版本解析，就像它们是具有不同名称的模块一样，但最终的依赖关系图不能包含同名但兼容性级别不同的多个模块（除非 multiple_version_override 有效；如需了解详情，请参阅此处）。
repo_name 默认值 = ''
表示此模块的代码库的名称，如模块本身所示。默认情况下，代码库的名称是模块的名称。如果项目一直使用与其模块名称不同的代码库名称，则可以指定此属性，以简化迁移过程。
bazel_compatibility Iterable of strings； 默认值 = []
一个 Bazel 版本列表，允许用户声明哪些 Bazel 版本与此模块兼容。这不会影响依赖项解析，但 bzlmod 将使用此信息来检查当前的 Bazel 版本是否兼容。此值的格式为以英文逗号分隔的一些限制条件值的字符串。支持三个限制条件：<=X.X.X：Bazel 版本必须等于或低于 X.X.X。当较新版本中存在已知不兼容的更改时使用。>=X.X.X：Bazel 版本必须等于或高于 X.X.X。当您依赖于一些从 X.X.X 版本开始才提供的功能时使用。-X.X.X：Bazel 版本 X.X.X 不兼容。当 X.X.X 中存在破坏您的 bug 时使用，但在后续版本中已修复。

module_extension

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

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

参数

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

multiple_version_override

None multiple_version_override(module_name, versions, registry='')

指定某个依赖项仍应来自注册表，但允许其多个版本共存。该指令只能由根模块使用；换句话说，如果某个模块指定了任何替换项，则无法将其用作依赖项。

参数

参数 说明
module_name 必需
要应用此替换项的 Bazel 模块依赖项的名称。
versions Iterable of strings； 必需
明确指定允许共存的版本。这些版本必须已存在于依赖关系图预选择中。此模块的依赖项将“升级”如果依赖项的版本高于同一兼容性级别上允许的任何版本，则会导致错误。
registry 默认值 = ''
覆盖此模块的注册表；应使用指定的注册表，而不是从默认的注册表列表中查找此模块。

输出

None print(sep=" ", *args)

将 args 输出为调试输出。其前缀为字符串 "DEBUG" 和此调用的位置（文件和行号）。参数转换为字符串的确切方式未指定，可能随时发生变化。具体来说，它可能与 str() 和 repr() 设置的格式不同（且更为详细）。

我们不建议在正式版代码中使用 print，因为它会给用户造成一些垃圾内容。对于弃用功能，请尽可能使用 fail() 来显示硬错误。

参数

参数 说明
sep 默认值 = "“
对象之间的分隔符字符串，默认为空格（“ ”）。
args 必需
要打印的对象。

provider

unknown provider(doc='', *, 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 默认值 = ''
可通过文档生成工具提取的提供商的说明。
fields sequence of strings; or dict; or None； 默认 = 无
如果已指定，则会限制允许的字段集。
可能的值有：
  • 字段列表：
    provider(fields = ['a', 'b'])

  • 字典字段名称 ->文档：
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
所有字段均为选填字段。
init callable; or 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 = ...)

范围

sequence range(start_or_stop, stop_or_none=None, step=1)

使用 step 递增创建一个列表，其中包含从 start 到 stop 的项。如果只提供一个参数，则各个项的范围为 0 到该元素。
range(4) == [0, 1, 2, 3]
range(3, 9, 2) == [3, 5, 7]
range(3, 0, -1) == [3, 2, 1]

参数

参数 说明
start_or_stop 必需
如果提供了 start 元素，则为 start 元素的值，否则为 stop 值且实际 start 为 0
stop_or_none int; or None； 默认 = 无
不包含在结果列表中的第一项的可选索引；在达到 stop 之前停止生成列表。
step 默认值 = 1
增量（默认值为 1）。此值可能为负数。

register_execution_platforms()

None register_execution_platforms(*platform_labels)

注册已定义的平台，以便 Bazel 在解析工具链期间将其用作执行平台。

参数

参数 说明
platform_labels sequence of strings； 必需
要注册的平台的标签。

register_execution_platforms(dev_dependency)

None register_execution_platforms(dev_dependency=False, *platform_labels)

指定选择此模块时要注册的已定义的执行平台。应为绝对目标模式（即以 @ 或 // 开头）。如需了解详情，请参阅工具链解析。

参数

参数 说明
dev_dependency 默认值 = False
如果为 true，如果当前模块不是根模块或已启用 `--ignore_dev_dependency`，系统不会注册执行平台。
platform_labels sequence of strings； 必需
要注册的平台的标签。

register_toolchains()

None register_toolchains(*toolchain_labels)

注册已定义的工具链，以便 Bazel 能够在工具链解析期间使用该工具链。请参阅定义和注册工具链的示例。

参数

参数 说明
toolchain_labels sequence of strings； 必需
要注册的工具链的标签。

register_toolchains(dev_dependency)

None register_toolchains(dev_dependency=False, *toolchain_labels)

指定要在选择此模块时注册的已定义工具链。应为绝对目标模式（即以 @ 或 // 开头）。如需了解详情，请参阅工具链解析。

参数

参数 说明
dev_dependency 默认值 = False
如果为 true，则当当前模块不是根模块或已启用“--ignore_dev_dependency”时，系统不会注册工具链。
toolchain_labels sequence of strings； 必需
要注册的工具链的标签。

Repositories_rule(implementation, attrs, local, environ, configure, remotable, doc)

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

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

参数

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

Repositories_rule(implementation, attrs, local, environ, configure, remotable, doc)

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

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

参数

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

复活节

string repr(x)

将任何对象转换为字符串表示形式。这对于调试非常有用。
repr("ab") == '"ab"'

参数

参数 说明
x 必需
要转换的对象。

reversed

list reversed(sequence)

返回一个新的未冻结列表，其中包含以颠倒顺序显示的原始可迭代序列的元素。
reversed([3, 5, 4]) == [4, 5, 3]

参数

参数 说明
sequence 必需
要反转的可迭代序列（例如列表）。

规则

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='', *, 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 默认值 = False
此规则是否是测试规则，即它是否可能是 blaze test 命令的正文。所有测试规则都会自动被视为可执行文件；没有必要（也不建议）为测试规则明确设置 executable = True。有关详情，请参阅 “规则”页面。
attrs dict; or None； 默认 = 无
字典声明规则的所有属性。它从属性名称映射到属性对象（请参阅 attr 模块）。以 _ 开头的属性是私有属性，可用于添加对标签的隐式依赖项。属性 name 是隐式添加的，不得指定。属性 visibility、deprecation、tags、testonly 和 features 是隐式添加的，无法替换。大多数规则只需要少量属性。为限制内存用量，规则函数对属性的大小施加了限制。
outputs dict; or None; or function； 默认 = 无
已弃用。此参数已被弃用，很快就会被移除。请勿依赖它。此选项已通过 ---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 默认值 = False
此规则是否被视为可执行，即它是否可能是 blaze run 命令的正文。有关详情，请参阅 “规则”页面。
output_to_genfiles 默认值 = False
如果为 true，文件将在 genfiles 目录（而非 bin 目录）中生成。除非您需要它以便与现有规则兼容（例如，为 C++ 生成头文件时），否则请勿设置此标志。
fragments sequence of strings； 默认值 = []
规则在目标配置中要求的配置 fragment 的名称列表。
host_fragments sequence of strings； 默认值 = []
规则在主机配置中要求的配置 fragment 的名称列表。
_skylark_testable 默认值 = False
（实验性）

如果为 true，此规则将公开其操作，以便通过操作提供程序依赖于它的规则进行检查。提供程序也可通过调用 ctx.created_actions() 使用规则本身。

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

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

该列表的每个元素都是 provider() 返回的 *Info 对象，但旧版提供程序由其字符串名称表示。

exec_compatible_with sequence of strings； 默认值 = []
执行平台上的一系列限制条件，这些限制条件会应用于此规则类型的所有目标。
analysis_test 默认值 = False
如果为 true，则此规则被视为分析测试。

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

如果规则被定义为分析测试规则，就可以对其属性使用通过 analysis_test_transition 定义的配置转换，但会选择接受一些限制：

  • 此规则的目标数量有限。
  • 该规则被视为测试规则（就像设置了 test=True 一样）。这会取代 test 的值
  • 规则实施函数可能无法注册操作。相反，它必须通过提供 AnalysisTestResultInfo 来注册通过/失败结果。
build_setting BuildSetting; or None； 默认 = 无
如果设置，则说明此规则是哪种 build setting。请参阅 config 单元。如果设置了此属性，则会使用名为“build_setting_default”的必需属性会自动添加到此规则，其类型与此处传递的值相对应。
cfg 默认值 = 无
如果已设置，则指向配置转换，规则将在分析之前应用于自己的配置。
exec_groups dict; or None； 默认 = 无
从“exec_group”中复制执行组名称（字符串）。如果设置，则允许规则在单个目标内的多个执行平台上运行操作。如需了解详情，请参阅执行组文档。
compile_one_filetype sequence of strings; or None； 默认 = 无
供 --compile_one_dependency 使用：如果多条规则使用指定的文件，我们是否应该选择此规则而不是其他规则。
name string; or 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 必需
将配置条件映射到值的字典。每个键都是一个标签或用于标识 config_setting 或 constraint_value 实例的标签字符串。如需了解何时使用标签而非字符串，请参阅有关宏的文档。
no_match_error 默认值 = ''
（可选）没有条件匹配时要报告的自定义错误。

single_version_override

None single_version_override(module_name, version='', registry='', patches=[], patch_cmds=[], patch_strip=0)

指定依赖项仍应来自注册表，但应固定其版本、覆盖其注册表或应用的补丁列表。该指令只能由根模块使用；换句话说，如果某个模块指定了任何替换项，则无法将其用作依赖项。

参数

参数 说明
module_name 必需
要应用此替换项的 Bazel 模块依赖项的名称。
version 默认值 = ''
替换依赖关系图中此模块的声明版本。也就是说，此模块将被“固定”此替换版本。如果只覆盖注册表或补丁，则可以省略此属性。
registry 默认值 = ''
覆盖此模块的注册表；应使用指定的注册表，而不是从默认的注册表列表中查找此模块。
patches Iterable of strings； 默认值 = []
指向要应用于此模块的补丁文件的标签列表。补丁文件必须存在于顶级项目的源代码树中。它们按列表顺序应用。
patch_cmds Iterable of strings； 默认值 = []
应用补丁后，要应用于 Linux/Macos 的一系列 Bash 命令。
patch_strip 默认值 = 0
与 Unix 补丁的 --strip 参数相同。

已排序

list sorted(iterable, *, key=None, reverse=False)

返回一个新的已排序列表，其中包含所提供的可迭代序列的所有元素。如果任何一对元素 x、y 无法使用 x <y。元素按升序排序，除非反向参数为 True（在这种情况下，顺序是降序）。 排序是稳定的：比较相等的元素会保留其原始的相对顺序。 
sorted([3, 5, 4]) == [3, 4, 5]

参数

参数 说明
iterable 必需
要排序的可迭代序列。
key 默认值 = 无
在比较之前应用于每个元素的可选函数。
reverse 默认值 = False
按降序返回结果。

str

string str(x)

将任何对象转换为字符串。这对于调试非常有用。
str("ab") == "ab"
str(8) == "8"

参数

参数 说明
x 必需
要转换的对象。

tag_class

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

创建一个新的 tag_class 对象，该对象定义了一类标记（可供模块扩展程序使用的数据对象）的属性架构。

参数

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

tuple

tuple tuple(x=())

返回一个与给定的可迭代值具有相同元素的元组。
tuple([1, 2]) == (1, 2)
tuple((2, 3, 2)) == (2, 3, 2)
tuple({5: "a", 2: "b", 4: "c"}) == (5, 2, 4)

参数

参数 说明
x 默认值 = ()
要转换的对象。

类型

string type(x)

返回其参数的类型名称。这对于调试和类型检查非常有用。示例：
type(2) == "int"
type([1]) == "list"
type(struct(a = 2)) == "struct"
此函数将来可能会发生变化。如需编写与 Python 兼容的代码并满足未来需求，请仅将其用于比较返回值：
if type(x) == type([]):  # if x is a list

参数

参数 说明
x 必需
要检查其类型的对象。

use_extension

module_extension_proxy use_extension(extension_bzl_file, extension_name, *, dev_dependency=False)

返回表示模块扩展的代理对象；可以调用其方法来创建模块扩展标记。

参数

参数 说明
extension_bzl_file 必需
Starlark 文件的标签，用于定义模块扩展名。
extension_name 必需
要使用的模块扩展的名称。Starlark 文件必须导出使用此名称的符号。
dev_dependency 默认值 = False
如果为 true，如果当前模块不是根模块或已启用 `--ignore_dev_dependency`，系统会忽略这种模块扩展用法。

use_repo

None use_repo(extension_proxy, *args, **kwargs)

将给定模块扩展程序生成的一个或多个代码库导入当前模块的作用域中。

参数

参数 说明
extension_proxy 必需
由 use_extension 调用返回的模块扩展代理对象。
args 必需
要导入的代码库的名称。
kwargs 必需
以不同名称指定要导入到当前模块范围内的特定代码库。键应该是要在当前范围内使用的名称，而值应该是模块扩展程序导出的原始名称。

visibility

None visibility(value)

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

模块的加载可见性决定了其他 BUILD 和 .bzl 文件是否可以加载该模块。（这与底层 .bzl 源文件的目标可见性不同，后者控制着相应文件是否可能显示为其他目标的依赖项。）加载可见性在软件包级别起作用：要加载模块，执行加载的文件必须位于已被授予模块可见性的软件包中。无论其可见性如何，模块始终可以在自己的软件包中加载。

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

如果 --check_bzl_visibility 标志设置为 false，加载可见性违规行为会发出警告，但不会导致构建失败。

参数

参数 说明
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" 值始终可用，并且 "//..." 始终会被解释为“当前代码库中的所有软件包”。

工作区

None workspace(name)

此函数只能在 WORKSPACE 文件中使用，并且必须在 WORKSPACE 文件中的所有其他函数之前声明。每个 WORKSPACE 文件都应该有一个 workspace 函数。

设置此工作区的名称。工作区名称应为项目的 Java 软件包式说明，使用下划线作为分隔符。例如，github.com/bazelbuild/bazel 应使用 com_github_bazelbuild_bazel。

此名称用于存储代码库的 runfile 的目录。例如，如果本地仓库中有 Runfile foo/bar 且 WORKSPACE 文件包含 workspace(name = 'baz')，则此 Runfile 将在 mytarget.runfiles/baz/foo/bar 下可用。如果未指定工作区名称，则 runfile 将通过符号链接到 bar.runfiles/foo/bar。

远程代码库规则名称必须是有效的工作区名称。例如，您可以使用 maven_jar(name = 'foo')，但不能使用 maven_jar(name = 'foo%bar')，因为 Bazel 会尝试为包含 workspace(name = 'foo%bar') 的 maven_jar 写入一个 WORKSPACE 文件。

参数

参数 说明
name 必需
工作区的名称名称必须以字母开头，且只能包含字母、数字、下划线、短划线和英文句点。

zip

list zip(*args)

返回 tuple 的 list，其中第 i 个元组包含每个参数序列或可迭代对象的第 i 个元素。该列表具有最短输入的大小。使用单个可迭代参数时，它会返回 1 元组的列表。如果没有参数，它将返回一个空列表。示例：
zip()  # == []
zip([1, 2])  # == [(1,), (2,)]
zip([1, 2], [3, 4])  # == [(1, 3), (2, 4)]
zip([1, 2], [3, 4, 5])  # == [(1, 3), (2, 4)]

参数

参数 说明
args 必需
要压缩的列表。