会员
- analytics_test_transition
- 方面
- configuration_field
- Depset
- exec_group
- module_extension
- 提供程序
- repo_rule
- 规则
- 选择
- tag_class
- 可见性
分析测试转换
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 参数的字段提供给实现函数。以 显式属性必须具有 |
required_providers
|
default = [] 此属性可允许相应宽高比仅传播其规则宣传其所需提供商的目标。该值必须是包含单个提供商或供应商列表的列表,不能同时包含两者。例如, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 是无效值。解除嵌套的提供商列表将自动转换为一份提供商列表。也就是说, 要让某个规则能够看到某些规则(例如 |
required_aspect_providers
|
default = [] 此属性允许该方面检查其他方面。该值必须是包含单个提供商或供应商列表的列表,不能同时包含两者。例如, [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 是无效值。解除嵌套的提供商列表将自动转换为一份提供商列表。也就是说, 如需显示另一个方面的信息(例如 |
provides
|
default = [] 实现函数必须返回的提供程序列表。 如果实现函数从返回值中省略了此处列出的任何类型的提供程序,则会发生错误。不过,实现函数可能会返回此处未列出的其他提供程序。 该列表的每个元素都是 |
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_group s。如果设置此标记,便可以在单个实例中针对多个执行平台执行操作。如需了解详情,请参阅执行组文档。
|
配置字段
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如果指定,系统会限制允许的字段集。 可能的值包括:
|
init
|
callable; or None ;
default = 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 = ...) |
代码库规则
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 。用于定义预先声明的输出的架构。与 该参数的值是一个字典或一个生成字典的回调函数。回调的工作方式类似于计算的依赖项属性:函数的参数名称与规则的属性匹配,因此,如果您传递带有定义 字典中的每个条目都会创建一个预先声明的输出,其中键是一个标识符,而值是一个字符串模板,用于确定输出的标签。在规则的实现函数中,标识符将成为用于访问
实际上,最常见的替换占位符是 |
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 = [] 实现函数必须返回的提供程序列表。 如果实现函数从返回值中省略了此处列出的任何类型的提供程序,则会发生错误。不过,实现函数可能会返回此处未列出的其他提供程序。 该列表的每个元素都是 |
exec_compatible_with
|
sequence of strings ; default = []针对执行此规则类型的所有目标的执行平台上的约束列表。 |
analysis_test
|
default = False 如果为 true,则将此规则视为分析测试。 注意:分析测试规则主要使用 Starlark 核心库中提供的基础架构定义。如需指导,请参阅测试。 如果将规则定义为分析测试规则,则允许对其属性使用通过 analysis_test_transition 定义的配置转换,但您可以选择启用一些限制:
|
build_setting
|
BuildSetting; or None ;
default = None设置后,描述此规则的 build setting 类型。请参阅 config 模块。如果设置此属性,系统会自动向规则添加一个名为“build_setting_default”的必需属性,其类型与在此处传入的值相对应。 |
cfg
|
default = None 如果设置此参数,则在分析之前,系统会将规则应用于其自己的配置转换。 |
exec_groups
|
dict; or None ;默认值 = None执行组名称(字符串)的记录为 exec_group s。设置后,规则将允许在单个目标内的多个执行平台上执行操作。如需了解详情,请参阅执行组文档。
|
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 理解,并在日志记录、 如果省略此参数,则系统会将规则的名称设置为在声明的 .bzl 模块中绑定到此规则的第一个 Starlark 全局变量的名称。因此,如果名称为 为规则指定明确的名称不会更改您可以实例化规则的位置。 |
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
|
必需 软件包规范字符串或单个软件包规范字符串的列表。 软件包规格遵循与
不允许使用“@”语法;所有规范均相对于当前模块的代码库进行解释。 如果 请注意, |