所有 .bzl 文件中都可用的全局方法。
成员
- analysis_test_transition
- aspect
- configuration_field
- depset
- exec_group
- exec_transition
- module_extension
- 提供程序
- repository_rule
- rule
- select
- 子规则
- tag_class
- 公开范围
analysis_test_transition
transition analysis_test_transition(settings)
创建要应用于分析测试规则依赖项的配置转换。此过渡只能应用于包含 analysis_test = True
的规则的属性。此类规则的功能受到限制(例如,其依赖项树的大小受限),因此与使用 transition()
创建的转场效果相比,使用此函数创建的转场效果的潜在范围受到限制。
此函数主要用于简化 Analysis Test Framework 核心库的使用。如需了解最佳实践,请参阅其文档(或其实现)。
参数
参数 | 说明 |
---|---|
settings
|
字典;
必需 一个字典,其中包含应由此配置转换设置的配置设置的相关信息。键是 build 设置标签,值是转换后的新值。所有其他设置保持不变。使用此属性声明分析测试需要设置的特定配置设置,以便测试能够通过。 |
切面
Aspect aspect(implementation, attr_aspects=[], toolchains_aspects=[], attrs={}, 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, subrules=[])
参数
参数 | 说明 |
---|---|
implementation
|
function;
必需 用于实现此方面功能的 Starlark 函数,该函数只有两个参数:Target(要应用此方面功能的目标)和 ctx(用于创建目标的规则上下文)。您可以通过 ctx.rule 字段获取目标的属性。在分析阶段,系统会针对将某个方面应用于目标的每次操作来评估此函数。
|
attr_aspects
|
字符串的序列;默认为 [] 属性名称列表。切面会沿着具有这些名称的目标的属性中指定的依赖项传播。此处的常见值包括 deps 和 exports 。该列表还可以包含单个字符串 "*" ,以沿着目标的所有依赖项传播。
|
toolchains_aspects
|
sequence;
默认为 [] 工具链类型列表。该方面会传播到与这些工具链类型匹配的目标工具链。 |
attrs
|
字典;
默认值为 {} 用于声明相应方面所有属性的字典。它用于从属性名称映射到属性对象,例如 attr.label 或 attr.string (请参阅 attr 模块)。作为 ctx 形参的字段,这些方面属性可供实现函数使用。以 显式属性必须为 声明的属性会将 |
required_providers
|
sequence;默认为 [] 此属性可让此方面将其传播限制为仅限规则中宣传其所需提供程序的目标。该值必须是包含单个提供商或提供商列表的列表,但不能同时包含这两者。例如, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是一个有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 无效。非嵌套提供商列表会自动转换为包含一个提供商列表的列表。也就是说, 为了使某些规则(例如 |
required_aspect_providers
|
sequence;
默认值为 [] 此属性允许此 aspect 检查其他 aspect。该值必须是包含单个提供商或提供商列表的列表,但不能同时包含这两者。例如, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是一个有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 无效。未嵌套的提供商列表会自动转换为包含一个提供商列表的列表。也就是说, 若要使另一个 aspect(例如 |
provides
|
sequence;
默认为 [] 实现函数必须返回的提供程序列表。 如果实现函数从其返回值中省略了此处列出的任何提供程序类型,则会出错。不过,实现函数可能会返回此处未列出的其他提供程序。 列表中的每个元素都是 |
requires
|
Aspect 的序列;默认为 [] 在此 aspect 之前需要传播的 aspect 的列表。 |
fragments
|
字符串的序列;
默认为 [] 该方面在目标配置中需要的配置 fragment 的名称列表。 |
host_fragments
|
字符串的序列;
默认为 [] 该方面在主机配置中需要的配置 fragment 的名称列表。 |
toolchains
|
sequence;默认值为 [] 如果设置了此项,则表示此切面所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象,可以任意组合。系统会通过检查当前平台来查找工具链,并通过 ctx.toolchain 将其提供给方面实现。
|
incompatible_use_toolchain_transition
|
bool;默认值为 False 已弃用,已不再使用,应将其移除。 |
doc
|
string;或 None ;默认值为 None 可通过文档生成工具提取的切面的说明。 |
apply_to_generating_rules
|
bool;
默认为 False 如果为 true,则在应用于输出文件时,该方面将应用于输出文件的生成规则。 例如,假设一个切面通过属性 `deps` 以传递方式传播,并且应用于目标 `alpha`。假设 `alpha` 的 `deps = [':beta_output']` 为 `beta_output` 是目标 `beta` 的声明输出。假设 `beta` 将目标 `charlie` 设为其 `deps` 的 `deps`。如果 `apply_to_beta` 将仅传播到 `alphali` 的切面,那么 char_to_generating_alpha 的切面为 默认值为 false。 |
exec_compatible_with
|
字符串的序列;
默认为 [] 适用于此方面所有实例的执行平台限制条件的列表。 |
exec_groups
|
dict;或 None ;默认值为 None 转换为 exec_group s 的执行组名称(字符串)的 Dict。如果设置,则允许在单个实例中对多个执行平台运行操作。如需了解详情,请参阅执行组文档。
|
subrules
|
子规则的序列;默认值为 [] 实验性:此方面使用的子规则列表。 |
configuration_field
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
|
string;
必需 包含延迟绑定值的配置 fragment 的名称。 |
name
|
string;
必需 要从配置 fragment 中获取的值的名称。 |
Depset
depset depset(direct=None, order="default", *, transitive=None)
direct
参数是一个 Depset 的直接元素列表,transitive
参数是一个 Depset 列表,其元素会成为已创建的 Depset 的间接元素。将 depset 转换为列表时返回元素的顺序由 order
参数指定。如需了解详情,请参阅依赖项集概览。
废弃集的所有元素(直接和间接)都必须属于同一种类型,可以通过表达式 type(x)
获得。
由于基于哈希的集合用于在迭代期间消除重复项,因此 depset 的所有元素都应可哈希化。不过,目前并未在所有构造函数中一致地检查此不变量。使用 --incompatible_always_check_depset_elements 标志启用一致的检查;这将是未来版本中的默认行为;请参阅问题 10313。
此外,元素目前必须是不可变的,但我们日后会放宽此限制。
创建的 depset 的顺序应与其 transitive
depset 的顺序兼容。"default"
顺序与任何其他顺序兼容,所有其他顺序仅与自身兼容。
参数
参数 | 说明 |
---|---|
direct
|
sequence;或 None ;
默认为 None depset 的直接元素的列表。 |
order
|
字符串;
默认为 "default" 新 depset 的遍历策略。如需了解可能的值,请点击此处。 |
transitive
|
依赖项集的序列;或 None ;
默认值为 None 依赖项集的列表,其元素将成为依赖项集的间接元素。 |
exec_group
exec_group exec_group(toolchains=[], exec_compatible_with=[])
参数
参数 | 说明 |
---|---|
toolchains
|
sequence;
默认为 [] 此执行组所需的一组工具链。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象,可以任意组合。 |
exec_compatible_with
|
字符串的序列;默认值为 [] 执行平台上的限制条件列表。 |
exec_transition
transition exec_transition(implementation, inputs, outputs)
transition()
版本。如需了解最佳实践,请参阅其文档(或其实现)。只能从 Bazel 内置函数使用。
参数
参数 | 说明 |
---|---|
implementation
|
Callable;必需 |
inputs
|
字符串的序列;
必需 |
outputs
|
字符串的序列;
必需 |
module_extension
unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)
use_extension
将其导出并在 MODULE.bazel 文件中使用。
参数
参数 | 说明 |
---|---|
implementation
|
可调用;
必需 用于实现此模块扩展的函数。只能接受一个参数 module_ctx 。系统会在构建开始时调用此函数一次,以确定一组可用代码库。
|
tag_classes
|
dict;默认值为 {} 一个字典,用于声明扩展程序使用的所有标记类。它会从标记类的名称映射到 tag_class 对象。 |
doc
|
string;或 None ;默认值为 None 模块扩展的说明,可由文档生成工具提取。 |
environ
|
字符串的序列;默认为 [] 提供此模块扩展程序依赖的环境变量列表。如果该列表中的环境变量发生变化,系统会重新评估扩展程序。 |
os_dependent
|
bool;
默认值为 False 指示此扩展程序是否依赖于操作系统 |
arch_dependent
|
bool;
默认值为 False 表示此扩展程序是否依赖于架构 |
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
可调用值和一个原始构造函数可调用值。如需了解详情,请参阅 规则(自定义提供程序的自定义初始化)以及下面对 init
参数的讨论。
参数
参数 | 说明 |
---|---|
doc
|
string;或 None ;
默认为 None 提供方说明,可由文档生成工具提取。 |
fields
|
string、dict;或 None ;默认值为 None 如果指定,则会限制允许的字段集。 可能的值包括:
|
init
|
可调用对象;或 None ;
默认为 None 可选回调,用于在实例化期间预处理和验证提供程序的字段值。如果指定了 init ,provider() 会返回一个包含 2 个元素的元组:普通提供程序符号和原始构造函数。下面提供了精确的说明;如需直观地了解相关讨论和用例,请参阅规则(提供程序的自定义初始化)。 设
init 回调,对符号 P 本身的调用会被视为对默认构造函数 c 的调用;换句话说,P(*args, **kwargs) 会返回 c(*args, **kwargs) 。例如,MyInfo = provider() m = MyInfo(foo = 1) m 成为具有 m.foo == 1 的 MyInfo 实例。但在指定了
注意:上述步骤意味着,如果 这样一来, 指定 MyInfo, _new_myinfo = provider(init = ...) |
repository_rule
callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)
module_extension()
实现函数加载和调用它,或者供 use_repo_rule()
使用。
参数
参数 | 说明 |
---|---|
implementation
|
可调用;
必需 用于实现此规则的函数。必须有一个参数 repository_ctx 。在规则的每个实例的加载阶段都会调用该函数。 |
attrs
|
字典;或 None ;
默认为 None 用于声明代码库规则的所有属性的字典。它会从属性名称映射到属性对象(请参阅 attr 模块)。以 _ 开头的属性是私有的,可用于向文件添加对标签的隐式依赖项(代码库规则不能依赖于生成的工件)。系统会隐式添加属性 name ,因此不得指定该属性。声明的属性会将 |
local
|
bool;默认值为 False 指示此规则从本地系统提取所有内容,并且在每次提取时都应重新评估。 |
environ
|
字符串的序列;默认为 [] 已废弃。此参数已被弃用。请改为迁移到 repository_ctx.getenv 。提供此代码库规则依赖的环境变量列表。如果该列表中的环境变量发生更改,系统会重新提取代码库。 |
configure
|
bool;
默认值为 False 指示代码库出于配置目的检查系统 |
remotable
|
bool;默认值为 False 实验性。此参数处于实验阶段,随时可能发生变化。请勿依赖此功能。您可以通过设置 --experimental_repo_remote_exec Compatible with remote execution 以实验性方式启用该功能 |
doc
|
字符串;或 None ;
默认为 None 可由文档生成工具提取的代码库规则说明。 |
规则
callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])
规则必须分配给 .bzl 文件中的全局变量;全局变量的名称就是规则的名称。
测试规则的名称必须以 _test
结尾,而所有其他规则不得带有此后缀。(此限制仅适用于规则,而不适用于其目标。)
参数
参数 | 说明 |
---|---|
implementation
|
function;
必需 实现此规则的 Starlark 函数必须只有一个参数:ctx。在分析阶段,系统会针对规则的每个实例调用该函数。它可以访问用户提供的属性。它必须创建操作来生成所有声明的输出。 |
test
|
bool;
默认值为 unbound 此规则是否为测试规则,即是否可以是 blaze test 命令的主体。所有测试规则都会自动视为可执行;无需(也不建议)为测试规则显式设置 executable = True 。此值默认为 False 。如需了解详情,请参阅“规则”页面。
|
attrs
|
dict;默认值为 {} 用于声明规则所有属性的字典。它用于从属性名称映射到属性对象(请参阅 attr 模块)。以 _ 开头的属性是私有的,可用于向标签添加隐式依赖项。系统会隐式添加属性 name ,因此无需指定该属性。属性 visibility 、deprecation 、tags 、testonly 和 features 是隐式添加的,无法替换。大多数规则只需要几个属性。为了限制内存用量,可声明的属性数量存在上限。声明的属性会将 |
outputs
|
字典;或 None ;或函数;
默认是 None 已废弃。此参数已弃用,很快就会被移除。请勿依赖此功能。在 --incompatible_no_rule_outputs_param 中,此功能处于停用状态。使用此标志可验证您的代码是否与即将移除的 API 兼容。此参数已被弃用。迁移规则以改用 OutputGroupInfo 或 attr.output 。用于定义预声明输出的架构。与 此参数的值是字典,或者是生成字典的回调函数。该回调函数的运作方式与计算的依赖项属性类似:函数的参数名称会与规则的属性进行匹配,因此,例如,如果您传递带有 字典中的每个条目都会创建一个预声明的输出,其中键是标识符,值是用于确定输出标签的字符串模板。在规则的实现函数中,该标识符会变为用于在
在实践中,最常见的替换占位符是 |
executable
|
bool;
默认值为 unbound 确定此规则是否被视为可执行的,即是否可以成为 blaze run 命令的正文。默认值为 False 。如需了解详情,请参阅 “规则”页面。
|
output_to_genfiles
|
bool;默认值为 False 如果为 true,文件将在 genfiles 目录(而非 bin 目录)中生成。除非您需要此标志来与现有规则保持兼容性(例如,为 C++ 生成头文件时),否则请勿设置此标志。 |
fragments
|
字符串的序列;默认为 [] 目标配置中规则所需的配置 fragment 的名称列表。 |
host_fragments
|
字符串的序列;默认为 [] 该规则在主机配置中所需的配置 fragment 的名称列表。 |
_skylark_testable
|
bool;默认值为 False (实验性) 如果为 true,此规则将公开其操作,以便通过 Actions 提供程序依赖它的规则进行检查。规则本身也可以通过调用 ctx.created_actions() 来使用该提供程序。这应仅用于测试 Starlark 规则的分析时行为。此标志未来可能会被移除。 |
toolchains
|
sequence;
默认为 [] 如果设置,则表示此规则所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象,可以任意组合。系统将通过检查当前平台找到工具链,并通过 ctx.toolchain 将其提供给规则实现。 |
incompatible_use_toolchain_transition
|
bool;
默认为 False 已废弃,不再使用,应予移除。 |
doc
|
字符串;或 None ;
默认值为 None 可由文档生成工具提取的规则说明。 |
provides
|
sequence;
默认为 [] 实现函数必须返回的提供程序列表。 如果实现函数在其返回值中省略了此处列出的任何类型的提供程序,则会发生错误。不过,实现函数可能会返回此处未列出的其他提供程序。 该列表的每个元素都是 |
dependency_resolution_rule
|
bool;
默认值为 False 如果设置,则规则可以通过在材质化程序中也标记为可用的属性成为依赖项。设置了此标志的规则的每个属性都必须标记为可在 Material 化器中使用。这样,这样标记的规则就不能依赖于未标记的规则。 |
exec_compatible_with
|
string 的 sequence,默认值为 [] 执行平台上的一系列限制条件,这些限制条件会应用于此规则类型的所有目标。 |
analysis_test
|
bool;
默认为 False 如果为 true,则将此规则视为分析测试。 注意:分析测试规则主要使用核心 Starlark 库中提供的基础架构进行定义。如需相关指导,请参阅测试。 如果将规则定义为分析测试规则,则允许对其属性使用使用 analysis_test_transition 定义的配置转换,但会选择接受一些限制:
|
build_setting
|
BuildSetting;或 None ;默认值为 None 如果设置,则说明此规则所属的类型 build setting 。请参阅 config 模块。设置此属性后,系统会自动将名为“build_setting_default”的必需属性添加到此规则,其类型与此处传入的值相对应。
|
cfg
|
默认值为 None 如果设置,则指向规则在分析之前将应用于其自身配置的配置转换。 |
exec_groups
|
字典;或 None ;
默认为 None 执行组名称(字符串)与 exec_group s 的字典。如果设置,则允许规则在单个目标内的多个执行平台上运行操作。如需了解详情,请参阅执行组文档。
|
initializer
|
默认值为 None 实验性:Stalark 函数初始化规则的属性。 系统会在规则的每个实例加载时调用该函数。该方法使用 它必须返回一个字典,其中包含属性名称与所需值的对应关系。未返回的属性不会受到影响。将 系统会先评估初始化程序,然后再评估属性定义中指定的默认值。因此,如果初始化程序签名中的参数包含默认值,则会覆盖属性定义中的默认值(返回 同样,如果初始化程序签名中的参数没有默认值,该参数将变为必需参数。在这种情况下,最好省略属性定义的默认/强制性设置。 最好对未处理的属性使用 对于扩展的规则,系统会从子级到祖先依次调用所有初始化程序。每个初始化程序只会传递它知道的公共属性。 |
parent
|
默认值为 None 实验性:扩展的 Stalark 规则。设置后,系统会合并公共属性以及通告的提供程序。该规则与父级中的 executable 和 test 匹配。fragments 、toolchains 、exec_compatible_with 和 exec_groups 的值会合并。无法设置旧版或已弃用的参数。父级的传入配置转换 cfg 会在此规则的传入配置之后应用。
|
extendable
|
bool;或标签;或字符串;或 None ;
默认值为 None 实验性:许可名单的标签,用于定义哪些规则可以扩展此规则。您还可以将其设为 True/False,以始终允许/禁止扩展。Bazel 默认始终允许扩展程序。 |
subrules
|
子规则的序列;默认为 [] 实验性:此规则使用的子规则列表。 |
选择
unknown select(x, no_match_error='')
select()
是一个辅助函数,用于使规则属性可配置。如需了解详情,请参阅 build 百科全书。
参数
参数 | 说明 |
---|---|
x
|
字典;
必需 用于将配置条件映射到值的字典。每个键都是一个标签或标签字符串,用于标识 config_setting 或 constraint_value 实例。如需了解何时使用标签而非字符串,请参阅有关宏的文档。 |
no_match_error
|
字符串;
默认值为 '' 如果没有条件匹配,可报告可选的自定义错误。 |
子规则
Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])
参数
参数 | 说明 |
---|---|
implementation
|
function;
required 用于实现此子规则的 Starlark 函数 |
attrs
|
字典;
默认为 {} 用于声明子规则的所有(私有)属性的字典。 子规则只能包含标签类型(即标签或标签列表)的私有属性。Bazel 会自动将与这些标签对应的已解析值作为命名参数传递给子规则的实现函数(因此,实现函数必须接受与属性名称匹配的命名参数)。这些值的类型将为:
|
toolchains
|
sequence;
默认为 [] 如果设置,则表示此子规则所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象,可以任意组合。系统会通过检查当前平台来查找工具链,并通过 ctx.toolchains 将其提供给子规则实现。请注意,如果设置此参数,则需要在使用规则上启用 AEG。如果您尚未迁移到 AEG,请参阅 https://bazel.build/extending/auto-exec-groups#migration-aegs。
|
fragments
|
字符串的序列;
默认为 [] 子规则在目标配置中需要的配置 fragment 的名称列表。 |
subrules
|
子规则的顺序;默认为 [] 此子规则所需的其他子规则的列表。 |
tag_class
tag_class tag_class(attrs={}, *, doc=None)
参数
参数 | 说明 |
---|---|
attrs
|
字典;
默认值为 {} 用于声明此代码类的所有属性的字典。它用于从属性名称映射到属性对象(请参阅 attr 模块)。 请注意,与 |
doc
|
字符串;或 None ;
默认为 None 标记类的说明,可由文档生成工具提取。 |
visibility
None
visibility(value)
设置当前正在初始化的 .bzl 模块的加载可见性。
模块的加载可见性决定了其他 BUILD 和 .bzl 文件能否加载该模块。(这与底层 .bzl 源文件的目标可见性不同,后者用于控制该文件是否可以显示为其他目标的依赖项。)加载可见性在软件包级别运作:如需加载模块,执行加载的文件必须位于已获授对该模块的可见性的软件包中。无论其可见性如何,模块始终可以在自己的软件包中加载。
每个 .bzl 文件只能调用一次 visibility()
,并且只能在顶层调用,不能在函数内调用。首选样式是将此调用放在 load()
语句和确定实参所需的任何简短逻辑的下方。
如果将标志 --check_bzl_visibility
设为 false,加载可见性违规问题将会发出警告,但不会导致构建失败。
参数
参数 | 说明 |
---|---|
value
|
必需 软件包规范字符串列表或单个软件包规范字符串。 软件包规范遵循与
不允许使用“@”语法;所有规范都相对于当前模块的代码库进行解读。 如果 请注意, |