2022 年 BazelCon 将于 11 月 16 日至 17 日在纽约和线上举办。
立即报名！

全局变量

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
在全局环境中注册的对象、函数和模块。

成员

all

bool all(elements)

如果所有元素求得的值为 True，或者集合为空，则返回 true。元素使用 bool 函数转换为布尔值。
all(["hello", 3, True]) == True
all([-1, 0, 1]) == False

参数

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

分析测试

None analysis_test(name, implementation, attrs=None, fragments=[], toolchains=[], attr_values={})

实验性。此 API 目前处于实验阶段，可能会随时更改。请勿依赖它。通过设置 --+experimental_analysis_test_call
可以创建新的分析测试目标，通过实验来进行启用。

测试的传递依赖项数量有限。此限制由 --analysis_testing_deps_limit 标志控制。

参数

参数 说明
name 必需
目标的名称。它应该是 Starlark 标识符，与模式匹配 #[A-Za-z_][A-Za-z0-9_]*'。
implementation 必需
实现此分析测试的 Starlark 函数。它必须且只能有一个参数：ctx。系统会在分析阶段调用该函数。它可以访问由 attrs 声明并通过 attr_values 填充的属性。实现函数不得注册操作。而必须通过提供 AnalysisTestResultInfo 来注册通过/失败结果。
attrs dict; or None；默认值 = None
声明属性的字典。请参阅规则调用。属性可以使用通过 analytics_test_transition 定义的配置过渡。
fragments sequence of strings；默认值为 []
可用于实现分析测试的配置 Fragment 列表。
toolchains sequence；默认值为 []
测试所需的一组工具链。请参阅规则调用。
attr_values dict of strings；默认值 = {}
要传递给实现的属性值字典。

分析_转换

transition analysis_test_transition(settings)

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

此函数主要用于帮助实现分析测试框架核心库。请参阅其文档（或其实现）了解最佳做法。

参数

参数 说明
settings 必需
包含配置设置相关信息的字典，应通过此配置转换进行设置。键是 build 设置标签，值是新的转换后值。其他所有设置保持不变。使用此方法可声明分析测试需要通过的具体配置设置。

任意

bool any(elements)

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

参数

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

归档替换值

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

指定此依赖项应来自特定位置的归档文件（zip、gzip 等），而不是来自注册表。此指令只能由根模块使用；换言之，如果某个模块指定了任何覆盖设置，该模块就无法被其他依赖项用作依赖项。

参数

参数 说明
module_name 必需
要应用此替换值的 Bazel 模块依赖项的名称。
urls string; or Iterable of strings；必需
归档的网址；可以是 http(s):// 或 file:// 网址。
integrity default = ''
归档文件的预期校验和，采用子资源完整性格式。
strip_prefix default = ''
要从提取的文件中移除的目录前缀。
patches Iterable of strings; default = []
指向要应用于此模块的补丁文件的标签列表。补丁文件必须位于顶级项目的源代码树中。它们按列表顺序应用。
patch_strip default = 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)

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

参数

参数 说明
implementation 必需
实施此方面的 Starlark 函数，正好有两个参数：Target（应用该方面的目标）和 ctx（创建目标时所基于的规则上下文）。目标的属性可通过 ctx.rule 字段获取。分析期间，会针对目标的每个方面应用此函数。
attr_aspects sequence of strings；默认值为 []
。属性名称列表。宽高比会传播到具有这些名称的目标的属性中指定的依赖项。此处的常见值包括 deps 和 exports。该列表还可以包含一个字符串 "*"，用于传播目标的所有依赖项。
attrs dict; or None；默认值 = 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 必须通告至少 1 个所需提供商列表中的所有提供商。例如，当某个方面的 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 对象，只不过旧版提供程序由其字符串名称表示。
requires sequence of Aspects; default = []
必须在此方面之前传播的方面列表。
fragments sequence of strings；默认值为 []
。目标配置中所需的相应方面的配置 Fragment 的名称列表。
host_fragments sequence of strings; default = []
主机配置中所需的配置片段的名称列表。
toolchains sequence; default = []
如果已设置，则此规则所需的一组工具链。该列表可以包含任意组合的字符串、标签或 StarlarkToolchainTypeApi 对象。您可以通过查看当前平台找到工具链，并通过 ctx.toolchain 提供给规则实现。
incompatible_use_toolchain_transition default = False
已弃用，不再使用，应将其移除。
doc default = ''
可通过文档生成工具提取的各部分的说明。
apply_to_generating_rules default = False
如果为 true，则该宽高比应用于输出文件时将改为应用于输出文件的生成规则。

例如，假设某个属性通过属性“deps”以传递方式传播，并且它应用于目标“alpha”。假设“alpha”包含 `deps = [':beta_output']`，其中“beta_output”是目标“beta”的声明输出。假设“beta”将目标“charli”应用于 `alpha`。

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

bazel_dep

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

声明对其他 Bazel 模块的直接依赖项。

参数

参数 说明
name 必需
要作为直接依赖项添加的模块的名称。
version default = ''
要作为直接依赖项添加的模块版本。
repo_name default = ''
表示此依赖项的外部代码库的名称。默认情况下，这是模块的名称。
dev_dependency default = False
如果为 true，则在当前模块不是根模块或启用了 `--ignore_dev_dependency` 时，此依赖项将被忽略。

bind

None bind(name, actual=None)

警告：不建议使用 bind()。请参阅考虑解除绑定，以就其问题和替代方案进行深入讨论。

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

参数

参数 说明
name 必需
将 '//external' 下的标签用作别名
actual string; or None; default = None
要别名的真实标签

bool

bool bool(x=False)

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

参数

参数 说明
x default = False
要转换的变量。

配置字段

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 required
从配置 Fragment 获取的值的名称。

Depset

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

创建 depset。direct 参数是 Depset 的直接元素列表，transitive 参数是 Desets 列表，其元素成为所创建 Dedeset 的间接元素。将偏移量转换为列表时元素返回的顺序由 order 参数指定。如需了解详情，请参阅Depsets 概览。

属性值的所有元素（直接和间接）都必须与通过表达式 type(x) 获取的类型相同。

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

此外，元素当前不可变，但将来的限制将放宽。

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

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

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

参数

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

字典

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

根据可选的位置参数和一组可选的关键字参数创建字典。如果多次提供相同的键，将使用最后一个值。通过关键字参数提供的条目应位于通过位置参数提供的条目之后。

参数

参数 说明
pairs default = []
一个字典或元素，其元素均为 2（键、值）。
kwargs 必需
其他条目的字典。

dir

list dir(x)

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

参数

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

枚举

list enumerate(list, start=0)

返回一对（双元素元组）列表，其中包含索引（整数）和输入序列中的项。
enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]

参数

参数 说明
list 必需
输入序列。
start default = 0
起始索引。

行政群组

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

创建执行组，该组可用于在规则实现过程中为特定执行平台创建操作。

参数

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

fail

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

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

参数

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

float

float float(x=unbound)

以浮点值的形式返回 x。
  • 如果 x 已是浮点数，float 则保持不变。
  • 如果 x 是布尔值，float 将返回 1.0（表示 True），0.0（表示 False）。
  • 如果 x 是一个整数，则 float 会返回最接近的 x 的 x 浮点值，如果数量太大，则返回错误。
  • 如果 x 是一个字符串，它必须是有效的浮点数字面量，或者等于（不区分大小写）NaN、Inf 或 Infinity，并且前面可以加上 + 或 - 符号。
任何其他值都会导致错误。如果没有参数，float() 会返回 0.0。

参数

参数 说明
x default = unbound
要转换的值。

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 default = unbound
如果该结构体没有给定名称的属性，则返回默认值。

git_override

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

指定依赖项应来自 Git 代码库的特定提交内容。此指令只能由根模块使用；换言之，如果某个模块指定了任何覆盖设置，该模块就无法被其他依赖项用作依赖项。

参数

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

Hasattr

bool hasattr(x, name)

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

参数

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

hash

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 会返回 1 表示 True，0 表示返回 False。
  • 如果 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 default = unbound
用于解释字符串值的基本值；默认值为 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 default = []
要转换的对象。

local_path_override

None local_path_override(module_name, path)

指定依赖项应来自本地磁盘上的特定目录。此指令只能由根模块使用；换言之，如果某个模块指定了任何覆盖设置，该模块就无法被其他依赖项用作依赖项。

参数

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

最大值

unknown max(*args)

返回所有给定参数中最大的参数。如果只提供一个参数，该参数必须是非空的 iterable。如果元素无法比较（例如使用字符串的 int），或者没有给出任何参数，则会出错。 
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, execution_platforms_to_register=[], toolchains_to_register=[])

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

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

参数

参数 说明
name default = ''
模块的名称。仅当此模块为根模块（例如，如果模块不依赖于其他模块时）时，才能省略此参数。有效的模块名称必须符合以下要求：1) 只能包含小写字母 (a-z)、数字 (0-9)、点 (.)、连字符 (-) 和下划线 (_)；2) 必须以小写字母开头；3) 以小写字母或数字结尾。
version default = ''
模块的版本。仅当此模块是根模块时（例如，如果模块不依赖于其他模块的情况下），才能省略。
compatibility_level default = 0
模块的兼容性级别；每当出现不兼容的问题时，都应更改此值。就 SemVer 而言，这本质上是该模块的“主要版本”，只不过它不是嵌入版本字符串中，而是作为一个单独的字段存在。不同兼容性级别的模块参与版本解析时就像是模块名称不同的模块一样，但最终的依赖关系图不能包含多个名称相同但兼容性级别不同的模块（除非 multiple_version_override 有效；如需了解详情，请参阅此处）。
execution_platforms_to_register Iterable of strings；默认值为 []
。选择此模块后要注册的已定义执行平台列表。应为绝对目标模式列表（即以 @ 或 // 开头）。如需了解详情，请参阅工具链解决方案。
toolchains_to_register Iterable of strings；默认值为 []
。选择此模块后要注册的已定义的工具链列表。应为绝对目标模式列表（即以 @ 或 // 开头）。如需了解详情，请参阅工具链解决方案。

module_extension

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

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

参数

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

多个版本替换值

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

指定依赖项仍应来自注册表，但应允许其多个版本共存。此指令只能由根模块使用；换言之，如果某个模块指定了任何覆盖设置，该模块就无法被其他依赖项用作依赖项。

参数

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

平面

None print(sep=" ", *args)

将 args 输出为调试输出。它将带有字符串 "DEBUG" 以及此调用的位置（文件和行号）作为前缀。未指定将参数转换为字符串的确切方式，并且可能会随时更改。具体而言，它可能不同于 str() 和 repr() 所设置的格式（并且更为详细）。

我们不建议在正式版代码中使用 print，因为它会给用户带来垃圾内容。如需弃用，请尽可能优先使用硬错误 fail()。

参数

参数 说明
sep default = " "
对象之间的分隔符字符串，默认为空格 (" ")。
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 值和一个 Raw 构造函数 Callable 值。如需了解详情，请参阅规则（自定义提供程序的自定义初始化）和下面的 init 参数的讨论。

参数

参数 说明
doc default = ''
可通过文档生成工具提取的提供商的说明。
fields sequence of strings; or dict; or None；默认值为 None
指定后，用于限制允许的字段集。
可能的值包括：
  • 字段列表：
    provider(fields = ['a', 'b'])

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

后面给出了精确的说明；如需了解直观的讨论和用例，请参阅规则（提供程序的自定义初始化）。

通过调用 provider() 让 P 成为创建的提供程序符号。从概念上讲，通过调用默认构造函数 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

通过这种方式，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 到 0。
range(4) == [0, 1, 2, 3]
range(3, 9, 2) == [3, 5, 7]
range(3, 0, -1) == [3, 2, 1]

参数

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

register_execute_platforms()

None register_execution_platforms(*platform_labels)

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

参数

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

register_execute_platforms()

None register_execution_platforms(*platform_labels)

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

参数

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

register_toolchains()

None register_toolchains(*toolchain_labels)

注册一个已定义的工具链，以便 Bazel 可以在工具链解析期间使用它。请参阅定义和注册工具链的示例。

参数

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

register_toolchains()

None register_toolchains(*toolchain_labels)

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

参数

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

repository_rule(implementation, 属性, 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; default = None
字典，用于声明规则的所有属性。它会从属性名称映射到属性对象（请参阅 attr 模块）。以 _ 开头的属性是不公开的，可用于向文件添加对标签的隐式依赖项（代码库规则不能依赖生成的工件）。属性 name 是隐式添加的，不得指定。
local default = False
表示此规则从本地系统提取所有内容，应在每次提取时重新评估。
environ sequence of strings；默认值为 []
。提供此代码库规则所依赖的环境变量列表。如果该列表中的某个环境变量发生更改，系统将重新提取代码库。
configure default = False
表示存储区用于检查系统是否出于配置目的
remotable default = False
实验性。此参数是实验性参数，随时都可能更改。请勿依赖它。可以通过设置 ---experimental_repo_remote_exec
与远程执行兼容，对实验性功能加以启用
doc default = ''
可通过文档生成工具提取的代码库规则的说明。

repository_rule(implementation, 属性, 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; default = None
字典，用于声明规则的所有属性。它会从属性名称映射到属性对象（请参阅 attr 模块）。以 _ 开头的属性是不公开的，可用于向文件添加对标签的隐式依赖项（代码库规则不能依赖生成的工件）。属性 name 是隐式添加的，不得指定。
local default = False
表示此规则从本地系统提取所有内容，应在每次提取时重新评估。
environ sequence of strings；默认值为 []
。提供此代码库规则所依赖的环境变量列表。如果该列表中的某个环境变量发生更改，系统将重新提取代码库。
configure default = False
表示存储区用于检查系统是否出于配置目的
remotable default = False
实验性。此参数是实验性参数，随时都可能更改。请勿依赖它。可以通过设置 ---experimental_repo_remote_exec
与远程执行兼容，对实验性功能加以启用
doc default = ''
可通过文档生成工具提取的代码库规则的说明。

转化

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 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；默认值 = None
已弃用。此参数已被弃用，很快就会被移除。请勿依赖它。已通过 ---incompatible_no_rule_outputs_param 将其停用。使用此标志可以验证您的代码是否与其即将移除的代码兼容。
此参数已被弃用。迁移规则以改用 OutputGroupInfo 或 attr.output。

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

此参数的值是一个字典或一个可生成字典的回调函数。该回调函数的工作原理与计算的依赖项属性类似：函数的参数名称与该规则的属性相匹配，因此，如果您将 outputs = _my_func 与定义 def _my_func(srcs, deps): ... 一起传递，该函数便可以访问属性 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" 中，dirname 为 a，basename 为 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；默认值为 []
。目标配置中规则所需的配置 Fragment 的名称列表。
host_fragments sequence of strings；默认值 = []
规则在主机配置中需要的配置片段的名称列表。
_skylark_testable default False还可以通过调用 ctx.created_actions() 让规则本身访问该提供程序。

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

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

列表中的每个元素都是一个由 provider() 返回的 *Info 对象，只不过旧版提供程序由其字符串名称表示。
exec_compatible_with sequence of strings；默认值为 []
执行平台上适用于此规则类型的所有目标的限制条件列表。
analysis_test default = False
如果值为 true，则此规则将被视为分析测试。

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

如果规则被定义为分析测试规则，则规则可以针对其属性使用通过 analytics_test_transition 定义的配置过渡，但会有一些限制：

  • 此规则的目标在传递可能具有的传递依赖项数量方面受到限制。
  • 系统会将该规则视为测试规则（就像设置了 test=True 一样）。这会取代 test 的值
  • 规则实现函数不得注册操作。而必须通过提供 AnalysisTestResultInfo 来注册通过/失败结果。
build_setting BuildSetting; or None；默认值 = 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；默认值 = None
由 --compile_one_dependency 使用：如果多条规则使用指定的文件，我们是否应该选择此规则而不是其他规则。
name string; or None；默认值为“无”
已弃用：请勿使用。

此规则的名称，由 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 = ''
可选的自定义错误，在没有条件匹配时进行报告。

single_version_override

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

指定依赖项仍应来自注册表，但应固定其版本、替换其注册表或应用补丁程序列表。此指令只能由根模块使用；换言之，如果某个模块指定了任何覆盖设置，该模块就无法被其他依赖项用作依赖项。

参数

参数 说明
module_name 必需
要应用此替换值的 Bazel 模块依赖项的名称。
version default = ''
替换此依赖项图中声明的此模块版本。换句话说，此模块将“固定”到此替换版本。如果所有人只想替换注册表或补丁，则可以省略此属性。
registry default = ''
替换此模块的注册表；应使用指定的注册表，而不是从默认注册表中查找此模块。
patches Iterable of strings; default = []
指向要应用于此模块的补丁文件的标签列表。补丁文件必须位于顶级项目的源代码树中。它们按列表顺序应用。
patch_strip default = 0
与 Unix 补丁程序的 --strip 参数相同。

已排序

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

返回新的已排序列表，其中包含提供的可迭代序列的所有元素。如果任何元素 x、y 均未与 x < y 进行比较，则可能会出现错误。除非反向参数为 True（在此顺序为降序），否则元素按升序排列。 排序比较稳定：比较相等的元素会保留原始相对顺序。 
sorted([3, 5, 4]) == [3, 4, 5]

参数

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

字符串

string str(x)

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

参数

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

tag_class

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

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

参数

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

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 default = ()
要转换的对象。

类型

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 必需
要检查的类型的对象。

使用扩展程序

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

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

参数

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

使用代码库

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

将给定模块扩展生成的一个或多个代码库导入当前模块的范围内。

参数

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

visibility

None visibility(value)

（实验性；由 --experimental_bzl_visibility 启用。）此功能的 API 可能会更改。只有 --experimental_bzl_visibility_allowlist 中出现的软件包才能调用此函数。已知问题：目前在 bzlmod 下可能无法使用此功能。）

设置当前初始化的 .bzl 模块的 bzl-visibility。

.bzl 模块的 bzl-visibility（不要与目标可见性混淆）决定了是否允许特定软件包的 BUILD 和 .bzl 文件中的相应 .bzl 的 load()。允许的值包括：

  • "public"（默认）：.bzl 可在任何位置加载。
  • "private"：.bzl 只能由同一软件包（子软件包除外）中的文件加载。
  • 一系列软件包规范（例如 ["//pkg1","//pkg2/subpkg/..."]）：.bzl 可由任何符合指定规范之一的软件包中的文件加载。软件包规范可以是包含所有路径的软件包路径或以 "/..." 结尾的软件包路径；目前不支持否定模式。所有软件包规范均在当前代码库中；不允许使用“@”语法。

通常，visibility() 会在 .bzl 文件的顶部调用，紧跟在其 load() 语句之后。（将此声明放在文件或帮助程序方法中之后的样式很糟糕。）在每个 .bzl 中或在 .bzl' 的顶级代码执行完毕之后，只能调用多次。

请注意，具有公开 bzl-visibility 的 .bzl 模块不一定暗示其对应的文件目标具有公开可见性。这意味着能够对 .bzl 文件执行 load() 操作，而无需依赖于 filegroup 或其他目标。

参数

参数 说明
value 必需
要设置的 bzl 可见性级别。可以是 "public"、"private" 或软件包列表。

工作区

None workspace(name)

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

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

此名称用于存储代码库的运行文件的目录。例如，如果本地代码库中有一个运行文件 foo/bar，并且 WORKSPACE 文件包含 workspace(name = 'baz')，则该运行文件将在 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 所需的
列表进行压缩。