.bzl 文件

<ph type="x-smartling-placeholder"></ph> 报告问题 每晚 · 7.3。 · 7.2 条 · 7.1。 · 7.0。 · 6.5

所有 .bzl 文件中都可用的全局方法。

成员

analysis_test_transition

transition analysis_test_transition(settings)

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

此函数主要用于支持分析测试框架核心库。如需了解最佳实践,请参阅其文档(或其实现)。

参数

参数 说明
settings dict; 必需
此字典包含有关此配置转换应设置的配置设置的信息。键是 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=[])

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

参数

参数 说明
implementation function; 必需
用于实现此切面的 Starlark 函数,恰好有两个参数:Target(应用切面的目标)和 ctx(创建目标时所依据的规则上下文)。目标的属性可通过 ctx.rule 字段获取。在将某个方面应用于目标的每次分析阶段中,系统会对此函数进行评估。
attr_aspects string 的序列; 默认值为 []
属性名称列表。切面会沿着具有这些名称的目标的属性中指定的依赖项传播。此处的常见值包括 depsexports。该列表还可包含单个字符串 "*",用于沿目标的所有依赖项传播。
toolchains_aspects sequence; 默认值为 []
工具链类型列表。切面会传播到与这些工具链类型匹配的目标工具链。
attrs dict; 默认值为 {}
声明切面所有属性的字典。它会从属性名称映射到属性对象,例如 `attr.label` 或 `attr.string`(请参阅 attr 模块)。切面属性可作为 ctx 参数的字段提供给实现函数。

_ 开头的隐式属性必须具有默认值,并且类型为 labellabel_list

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

required_providers sequence; 默认值为 []
通过此属性,切面可将其传播范围限制为规则通告其所需提供程序的目标。该值必须是包含单个提供商或提供商列表(但不能同时包含两者)的列表。例如,[[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 无效。

未嵌套的提供商列表会自动转换为包含一个提供商列表的列表。也就是说,[FooInfo, BarInfo] 将自动转换为 [[FooInfo, BarInfo]]

为了使某些规则(例如 some_rule)目标对切面可见,some_rule 必须通告至少一个必需提供商列表中的所有提供商。例如,如果切面的 required_providers[[FooInfo], [BarInfo], [BazInfo, QuxInfo]],则当且仅当 some_rule 提供 FooInfoBarInfo 或同时提供 BazInfoQuxInfo 时,此切面才能看到 some_rule 目标。

required_aspect_providers sequence; 默认值为 []
此属性允许此切面检查其他切面。该值必须是包含单个提供商或提供商列表(但不能同时包含两者)的列表。例如,[[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 是有效值,而 [FooInfo, BarInfo, [BazInfo, QuxInfo]] 无效。

未嵌套的提供商列表会自动转换为包含一个提供商列表的列表。也就是说,[FooInfo, BarInfo] 将自动转换为 [[FooInfo, BarInfo]]

如需让其他切面(例如 other_aspect)对此切面可见,other_aspect 必须至少提供其中一个列表中的所有提供程序。在 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 的示例中,当且仅当 other_aspect 提供 FooInfoBarInfoBazInfoQuxInfo 时,此切面才会看到 other_aspect

provides sequence; 默认值为 []
实现函数必须返回的提供程序列表。

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

该列表的每个元素都是 provider() 返回的 *Info 对象,但旧版提供程序由其字符串名称表示。如果规则的目标被用作声明所需提供程序的目标的依赖项,则无需在此处指定该提供程序。实现函数返回它就足够了。不过,虽然这并不是强制性要求,但这被认为是最佳做法。不过,aspectrequired_providers 字段要求在此处指定提供商。

requires Aspectsequence; 默认值为 []
此切面之前需要传播的切面的列表。
fragments string 的序列; 默认值为 []
切面在目标配置中所需的配置 fragment 的名称列表。
host_fragments string 的序列; 默认值为 []
切面在主机配置中所需的配置 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` 中的一个。如果切面的 `apply_to_generating_rules=True`,则切面将通过 `alpha`、`beta` 和 `charlie` 传播。如果为 False,则切面将仅传播到 `alpha`。

默认值为 false。

exec_compatible_with string 的序列; 默认值为 []
执行平台上适用于此切面所有实例的限制条件列表。
exec_groups dict;或 None; 默认值为 None
exec_group 读取执行组名称(字符串)。如果设置,则允许切面在单个实例中的多个执行平台上运行操作。如需了解详情,请参阅执行组文档
subrules 子规则序列; 默认值为 []
实验性:此切面使用的子规则列表。

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 string; 必需
包含延迟绑定值的配置 fragment 的名称。
name string; 必需
要从配置 fragment 获取的值的名称。

出发

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

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

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

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

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

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

参数

参数 说明
direct sequence;或 None; 默认值为 None
一个 Depset 的 direct 元素列表。
order string; 默认值为 "default"
新出发集的遍历策略。请参阅此处了解可能的值。
transitive depsetsequence;或 None; 默认值为 None
一个废弃设置列表,其中的元素将成为其间接元素。

exec_group

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

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

参数

参数 说明
toolchains sequence; 默认值为 []
此执行组所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象,可以任意组合形式。
exec_compatible_with string 的序列; 默认值为 []
执行平台上的约束条件列表。

exec_transition

transition exec_transition(implementation, inputs, outputs)

用于定义执行转换的专用 transition() 版本。如需了解最佳实践,请参阅其文档(或其实现)。只能从 Bazel 内置项使用。

参数

参数 说明
implementation Callable; 必需
inputs string 的序列; 必需
outputs string 的序列; 必需

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)

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

参数

参数 说明
implementation Callable; 必需
实现此模块扩展的函数。只能接受一个参数 module_ctx。在构建开始时调用该函数一次,以确定可用代码库集。
tag_classes dict; 默认值为 {}
用于声明扩展程序使用的所有标记类的字典。它会从标记类的名称映射到 tag_class 对象。
doc string;或 None; 默认值为 None
模块扩展的说明,可通过文档生成工具提取。
environ string 的序列; 默认值为 []
提供此模块扩展所依赖的环境变量列表。如果该列表中的环境变量发生变化,则系统将重新评估该扩展程序。
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 Callable 值和原始构造函数 Callable 值。有关详情,请参阅 规则(自定义提供程序的自定义初始化)以及下面关于 init 参数的讨论。

参数

参数 说明
doc string;或 None; 默认值为 None
可通过文档生成工具提取的提供商的说明。
fields string 的序列;dict;或 None; 默认值为 None
如果已指定,则会限制允许的字段集。
可能的值包括:
  • 字段列表:
    provider(fields = ['a', 'b'])

  • 字典字段名称 ->文档:
    provider(
           fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
所有字段均为选填字段。
init Callable;或 None; 默认值为 None
用于在实例化期间预处理和验证提供程序字段值的可选回调。如果指定了 initprovider() 会返回一个包含 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 == 1MyInfo 实例。

但在指定了 init 的情况下,调用 P(*args, **kwargs) 将改为执行以下步骤:

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

注意:上述步骤意味着,如果 *args**kwargsinit 的签名不匹配,或 init 正文的评估失败(可能是通过调用 fail() 有意为之),或者如果 init 的返回值不是具有预期架构的字典,就会发生错误。

通过这种方式,init 回调允许使用位置参数和任意逻辑进行预处理和验证,从而泛化正常的提供程序构造。这不会规避允许的 fields 列表。

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

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 Callable; 必需
执行此规则的函数。必须有一个参数 repository_ctx。在加载阶段,系统会针对规则的每个实例调用该函数。
attrs dict;或 None; 默认值为 None
字典声明规则的所有属性。它从属性名称映射到属性对象(请参阅 attr 模块)。以 _ 开头的属性是私有属性,可用于为文件添加对标签的隐式依赖项(仓库规则不能依赖于生成的工件)。属性 name 是隐式添加的,不得指定。
local bool; 默认值为 False
表示此规则会从本地系统提取所有内容,并且应在每次提取时重新评估。
environ string 的序列; 默认值为 []
已弃用。此参数已被弃用。请改为迁移到 repository_ctx.getenv
提供此代码库规则所依赖的环境变量列表。如果该列表中的环境变量发生变化,系统将重新提取仓库。
configure bool; 默认值为 False
指示仓库针对配置进行检查
remotable bool; 默认值为 False
实验性。此参数处于实验阶段,随时可能发生变化。请勿依赖它。您可以通过设置 --experimental_repo_remote_exec
兼容远程执行,在实验阶段启用它
doc string;或 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=[], exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

创建新规则,可通过 BUILD 文件或宏调用来创建目标。

必须为 .bzl 文件中的全局变量指定规则;全局变量的名称就是规则的名称。

测试规则的名称必须以 _test 结尾,而所有其他规则不得具有此后缀。(此限制仅适用于规则,而不适用于其目标。)

参数

参数 说明
implementation function; 必需
实现此规则的 Starlark 函数,都必须有且只有 1 个参数:ctx。在分析阶段,系统会针对规则的每个实例调用该函数。它可以访问用户提供的属性。它必须创建操作才能生成所有声明的输出。
test bool; 默认值为 unbound
此规则是否是测试规则,即它是否可能是 blaze test 命令的正文。所有测试规则都会自动被视为可执行文件;executable没有必要(也不建议)为测试规则明确设置 executable = True。该值默认为 False。如需了解详情,请参阅“规则”页面
attrs dict; 默认值为 {}
字典声明规则的所有属性。它从属性名称映射到属性对象(请参阅 attr 模块)。以 _ 开头的属性是私有属性,可用于添加对标签的隐式依赖项。属性 name 是隐式添加的,不得指定。属性 visibilitydeprecationtagstestonlyfeatures 是隐式添加的,无法替换。大多数规则只需要少量属性。为了限制内存用量,可以声明的属性数量存在上限。
outputs dict;或 None;或功能; 默认值为 None
已弃用。此参数已被弃用,很快就会被移除。请勿依赖它。此选项已通过 --incompatible_no_rule_outputs_param 停用。使用此标志可验证您的代码是否与即将移除的 API 兼容。
此参数已被弃用。迁移规则以改用 OutputGroupInfoattr.output

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

此参数的值是一个字典或生成字典的回调函数。该回调函数的运作方式与计算的依赖项属性类似:函数的参数名称会与规则的属性进行匹配,因此,例如,如果您传递带有 def _my_func(srcs, deps): ... 定义的 outputs = _my_func,该函数将有权访问属性 srcsdeps。无论是直接指定字典还是通过函数指定字典,其解释如下。

字典中的每个条目都会创建一个预声明的输出,其中键是标识符,值是用于确定输出标签的字符串模板。在规则的实现函数中,标识符成为用于访问 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 bool; 默认值为 unbound
此规则是否被视为可执行,即它是否可能是 blaze run 命令的正文。默认值为 False。有关详情,请参阅 “规则”页面
output_to_genfiles bool; 默认值为 False
如果为 true,文件将在 genfiles 目录(而非 bin 目录)中生成。除非您需要它以便与现有规则兼容(例如,为 C++ 生成头文件时),否则请勿设置此标志。
fragments string 的序列; 默认值为 []
规则在目标配置中要求的配置 fragment 的名称列表。
host_fragments string 的序列; 默认值为 []
规则在主机配置中要求的配置 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 string;或 None; 默认值为 None
可通过文档生成工具提取的规则的说明。
provides sequence; 默认值为 []
实现函数必须返回的提供程序列表。

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

该列表的每个元素都是 provider() 返回的 *Info 对象,但旧版提供程序由其字符串名称表示。如果规则的目标被用作声明所需提供程序的目标的依赖项,则无需在此处指定该提供程序。实现函数返回它就足够了。不过,虽然这并不是强制性要求,但这被认为是最佳做法。不过,aspectrequired_providers 字段要求在此处指定提供商。

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

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

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

  • 此规则的目标数量有限。
  • 该规则被视为测试规则(就像设置了 test=True 一样)。这会取代 test 的值
  • 规则实施函数可能无法注册操作。相反,它必须通过提供 AnalysisTestResultInfo 来注册通过/失败结果。
build_setting BuildSetting;或 None; 默认值为 None
如果设置,则说明此规则是哪种 build setting。请参阅 config 模块。如果设置了此属性,则会使用名为“build_setting_default”的必需属性会自动添加到此规则,其类型与此处传递的值相对应。
cfg 默认值为 None
如果已设置,则指向配置转换,规则将在分析之前应用于自己的配置。
exec_groups 字典;或 None; 默认为 None
执行组名称(字符串)与 exec_groups 的字典。如果设置,则允许规则在单个目标内的多个执行平台上运行操作。如需了解详情,请参阅执行组文档
initializer 默认值为 None
实验性:用于初始化规则属性的 Stalark 函数。

系统会在加载规则的每个实例时调用该函数。此方法通过 name 以及规则定义的公共属性的值进行调用(而非使用通用属性,例如 tags)。

它必须返回一个从属性名称到所需值的字典。未返回的属性不受影响。如果返回 None 作为值,将使用属性定义中指定的默认值。

初始化器将在属性定义中指定的默认值之前进行求值。因此,如果初始化程序签名中的某个参数包含默认值,它将覆盖属性定义中的默认值(除非返回 None)。

同样,如果初始化程序签名中的某个参数没有默认值,则该参数将变为必需参数。在这种情况下,最好忽略属性定义的默认/强制设置。

最好对未处理的属性使用 **kwargs

对于扩展规则,系统会从子级到祖先实体调用所有初始化程序。系统仅会向每个初始化程序传递其了解的公共属性。

parent 默认值为 None
实验性:经过扩展的 Stalark 规则。设置后,公共属性以及通告的提供程序会合并。该规则与父级中的 executabletest 匹配。fragmentstoolchainsexec_compatible_withexec_groups 的值会合并。无法设置旧版或已弃用的参数。系统会在此规则的传入配置之后应用父级的传入配置转换“cfg”。
extendable bool;或标签;或 string;或 None; 默认值为 None
实验性:许可名单中的标签,用于定义哪些规则可以扩展此规则。您还可以将其设为 True/False,以始终允许/禁止扩展。Bazel 默认始终允许扩展程序。
subrules 子规则序列; 默认值为 []
实验性:此规则使用的子规则列表。

选择

unknown select(x, no_match_error='')

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

参数

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

子规则

Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])

构造子规则的新实例。此函数的结果必须存储在全局变量中,然后才能使用。

参数

参数 说明
implementation function; 必需
用于实现此子规则的 Starlark 函数
attrs dict; 默认值为 {}
用于声明子规则所有(私有)属性的字典。

子规则只能包含标签类型的不公开属性(即 label 或 label-list)。Bazel 会自动将与这些标签对应的已解析值作为命名参数传递给子规则的实现函数(因此实现函数需要接受与属性名称匹配的命名参数)。这些值的类型将为:

  • FilesToRunProvider 表示标签属性为 executable=True
  • File 表示标签属性为 allow_single_file=True
  • 对于所有其他标签属性,则为 Target
  • [Target](适用于所有标签列表属性)
toolchains sequence; 默认值为 []
如果设置,则表示此子规则所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象,可以任意组合。系统将通过检查当前平台找到工具链,并通过 ctx.toolchains 将其提供给子规则实现。
fragments string 的序列; 默认值为 []
子规则在目标配置中所需的配置 fragment 的名称列表。
subrules 子规则序列; 默认值为 []
此子规则所需的其他子规则的列表。

tag_class

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

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

参数

参数 说明
attrs dict; 默认值为 {}
用于声明此标记类的所有属性的字典。它从属性名称映射到属性对象(请参阅 attr 模块)。
doc string;或 None; 默认值为 None
可通过文档生成工具提取的标记类的说明。

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