.bzl 文件

报告问题 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

成员

analysis_test_transition

transition analysis_test_transition(settings)

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

此函数主要用于帮助使用 Analysis Test Framework 核心库。如需了解最佳实践，请参阅其文档（或其实现）。

参数

参数 说明
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=[])

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

参数

参数 说明
implementation 函数； 必需
实现此方面的 Starlark 函数，具有两个参数：Target（应用了该方面的目标）和 ctx（创建目标所依据的规则上下文）。目标对象的属性可通过 ctx.rule 字段获取。在分析阶段，系统会针对方面对目标的每次应用评估此函数。
attr_aspects 字符串的序列；默认值为 []
属性名称列表。方面会沿着具有这些名称的目标的属性中指定的依赖项传播。此处常见的值包括 deps 和 exports。该列表还可以包含单个字符串 "*"，以沿目标的所有依赖项传播。
toolchains_aspects 序列； 默认值为 []
工具链类型列表。相应方面会传播到与这些工具链类型匹配的目标工具链。
attrs dict； 默认值为 {}
一个用于声明方面所有属性的字典。它从属性名称映射到属性对象，例如 attr.label 或 attr.string（请参阅 attr 模块）。方面属性可作为 ctx 形参的字段供实现函数使用。

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

显式属性必须具有 string 类型，并且必须使用 values 限制。显式属性会限制方面只能用于具有相同名称、类型和有效值（根据限制）的属性的规则。

声明的属性会将 None 转换为默认值。
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 目标，前提是 some_rule 提供 FooInfo、或 BarInfo、或 BazInfo 和 QuxInfo 两者。
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 对象，但旧版提供程序除外，旧版提供程序由其字符串名称表示。如果规则的目标用作声明必需提供程序的目标的依赖项，则无需在此处指定该提供程序。实现函数返回该值就足够了。不过，即使这不是必需的，指定该属性也被认为是最佳实践。不过，方面的 required_providers 字段要求在此处指定提供商。

requires 方面的序列；默认值为 []
在传播此方面之前需要传播的方面列表。
fragments 字符串的序列；默认值为 []
方面在目标配置中所需的配置 fragment 的名称列表。
host_fragments 字符串的序列；默认值为 []
主机配置中方面所需的配置 fragment 的名称列表。
toolchains 序列； 默认值为 []
如果设置，则表示此方面所需的一组工具链。该列表可以包含 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 字符串的序列；默认值为 []
适用于此方面所有实例的执行平台限制条件列表。
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 字符串； 必需
包含后期绑定值的配置 fragment 的名称。
name string; 必需
要从配置 fragment 中获取的值的名称。

depset

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

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

deps 的所有元素（直接和间接）必须具有相同的类型，如表达式 type(x) 所获得的那样。

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

此外，元素目前必须是不可变的，不过此限制将在未来放宽。

所创建 depset 的顺序应与相应 transitive depset 的顺序兼容。"default" 顺序与任何其他顺序兼容，所有其他顺序仅与自身兼容。

参数

参数 说明
direct 序列；或 None； 默认值为 None
deps 的直接元素列表。
order string； 默认值为 "default"
新 depset 的遍历策略。如需了解可能的值，请点击此处。
transitive depset 的序列；或 None； 默认值为 None
一个 depset 列表，其元素将成为 depset 的间接元素。

exec_group

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

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

参数

参数 说明
toolchains 序列；默认值为 []
此执行组所需的工具链集。该列表可以包含 String、Label 或 StarlarkToolchainTypeApi 对象，并且可以包含任意组合。
exec_compatible_with 字符串的序列； 默认值为 []
执行平台上的限制条件列表。

exec_transition

transition exec_transition(implementation, inputs, outputs)

用于定义 exec 过渡的 transition() 的专用版本。如需了解最佳实践，请参阅其文档（或其实现）。只能从 Bazel 内置函数中使用。

参数

参数 说明
implementation 可调用； 必需
inputs 字符串的序列；必需
outputs 字符串的序列；必需

微距

macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)

定义一个符号宏，该宏可在 BUILD 文件或宏（旧版或符号）中调用，以定义目标（可能为多个）。

macro(...) 返回的值必须分配给 .bzl 文件中的全局变量；全局变量的名称将是宏符号的名称。

如需有关如何使用符号宏的全面指南，请参阅宏。

参数

参数 说明
implementation 函数； 必需
实现此宏的 Starlark 函数。宏属性的值会作为关键字实参传递给实现函数。实现函数必须至少具有两个命名形参（name 和 visibility），并且如果宏继承了属性（请参阅下文中的 inherit_attrs），则必须具有 **kwargs 剩余关键字形参。

按照惯例，实现函数应为宏需要检查、修改或传递给非“main”目标的任何属性设置命名形参，而将传递给“main”目标且不会发生更改的“批量”继承属性作为 **kwargs 传递。

实现函数不得返回值。相反，实现函数通过调用规则或宏符号来声明目标。

由符号宏声明的任何目标或内部符号宏（包括由宏的实现函数传递调用的任何 Starlark 函数）的名称必须等于 name（这称为“主要”目标），或者以 name 开头，后跟分隔符字符（"_"、"-" 或 "."）和字符串后缀。（允许声明违反此命名方案的目标，但无法构建、配置或依赖这些目标。）

默认情况下，由符号宏声明的目标（包括由宏的实现函数传递调用的任何 Starlark 函数声明的目标）仅在包含定义该宏的 .bzl 文件的软件包中可见。如需声明目标在外部可见（包括对符号宏的调用方），实现函数必须适当地设置 visibility，通常是通过将 visibility = visibility 传递给正在调用的规则或宏符号来实现。

以下 API 在宏实现函数及其传递调用的任何 Starlark 函数中均不可用：

attrs dict； 默认值为 {}
此宏支持的属性的字典，类似于 rule.attrs。键是属性名称，值是属性对象（如 attr.label_list(...)，请参阅 attr 模块）或 None。None 条目表示宏没有该名称的属性，即使它本来会通过 inherit_attrs 继承一个属性（见下文）也是如此。

特殊 name 属性是预先声明的，不得包含在字典中。visibility 属性名称是预留的，不得包含在字典中。

名称以 _ 开头的属性是私有属性，无法在规则的调用位置传递。此类属性可以分配默认值（如 attr.label(default="//pkg:foo")），以创建对标签的隐式依赖关系。

为了限制内存用量，可声明的属性数量存在上限。

inherit_attrs 规则；或宏；或字符串；或 None； 默认值为 None
一个规则符号、宏符号或内置通用属性列表的名称（见下文），宏应从中继承属性。

如果将 inherit_attrs 设置为字符串 "common"，则宏将继承所有 Starlark 规则使用的通用规则属性定义。

请注意，如果 rule() 或 macro() 的返回值未分配给 .bzl 文件中的全局变量，则相应的值尚未注册为规则或宏符号，因此无法用于 inherit_attrs。

继承机制的工作原理如下：

  1. 特殊属性 name 和 visibility 永远不会被继承；
  2. 隐藏属性（名称以 "_" 开头的属性）永远不会被继承；
  3. 名称已在 attrs 字典中定义的属性永远不会被继承（attrs 中的条目优先；请注意，可以将条目设置为 None，以确保宏中不会定义具有该名称的任何属性）；
  4. 所有其他属性均继承自规则或宏，并有效地合并到 attrs 字典中。

当继承非强制性属性时，无论原始规则或宏中指定了什么值，该属性的默认值都会被覆盖为 None。这样可确保，当宏将属性的值转发给封装的规则或宏的实例时（例如通过传入未修改的 **kwargs），外部宏调用中缺少的某个值在内部规则或宏的调用中也会缺少（因为将 None 传递给属性与省略属性的处理方式相同）。 这一点很重要，因为省略属性与传递其明显的默认值在语义上略有不同。具体而言，省略的属性不会显示在某些 bazel query 输出格式中，并且仅当省略值时才会执行计算的默认值。如果宏需要检查或修改继承的属性（例如，向继承的 tags 属性添加值），您必须确保在宏的实现函数中处理 None 情况。

例如，以下宏会继承 native.cc_library 中的所有属性，但 cxxopts（已从属性列表中移除）和 copts（已获得新定义）除外。它还会注意在附加其他标记之前检查继承的 tags 属性的默认 None 值。

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

如果设置了 inherit_attrs，则宏的实现函数必须具有 **kwargs 残差关键字参数。

按照惯例，宏应将继承的未被替换的属性不变地传递给宏所封装的“主要”规则或宏符号。通常，大多数继承的属性在实现函数的参数列表中都没有参数，而是通过 **kwargs 简单地传递。如果宏需要将某些继承的属性（最常见的是 tags 和 testonly）传递给“主要”目标和非“主要”目标，则实现函数可以方便地为这些属性设置显式形参；但如果宏还需要检查或操纵这些属性，您必须注意处理非强制性继承属性的 None 默认值。

finalizer bool； 默认值为 False
此宏是否为规则最终确定器，即无论其在 BUILD 文件中的位置如何，都会在软件包加载结束时（在所有非最终确定器目标都已定义之后）进行评估的宏。

与普通符号宏不同，规则最终确定器可以调用 native.existing_rule() 和 native.existing_rules() 来查询当前软件包中定义的非最终确定器规则目标。请注意，native.existing_rule() 和 native.existing_rules() 无法访问任何规则最终确定器（包括此最终确定器）定义的目标。

doc string；或 None； 默认值为 None
可由文档生成工具提取的宏的说明。

module_extension

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

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

参数

参数 说明
implementation 可调用对象；必需
实现此模块扩展的函数。必须接受单个参数 module_ctx。在 build 开始时调用一次，以确定可用的 repo 集。
tag_classes dict；默认值为 {}
用于声明扩展程序使用的所有标记类的字典。它从标记类的名称映射到 tag_class 对象。
doc 字符串；或 None； 默认值为 None
可由文档生成工具提取的模块扩展的说明。
environ 字符串的序列；默认值为 []
提供此模块扩展程序所依赖的环境变量的列表。如果该列表中的环境变量发生变化，系统将重新评估扩展程序。
os_dependent bool； 默认值为 False
用于指示相应扩展程序是否依赖于操作系统
arch_dependent 布尔值； 默认值为 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 可调用值。

如果指定了 init，则返回一个包含 2 个元素的元组：一个 Provider 可调用值和一个原始构造函数可调用值。如需了解详情，请参阅 规则（自定义提供程序的自定义初始化）以及下文中对 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 可调用对象；或 None； 默认值为 None
一个可选的回调函数，用于在实例化期间预处理和验证提供程序的字段值。如果指定了 init，provider() 会返回一个包含 2 个元素的元组：常规提供程序符号和原始构造函数。

下文将给出精确的说明；如需直观的讨论和使用情形，请参阅规则（提供程序的自定义初始化）。

假设 P 是通过调用 provider() 创建的提供程序符号。从概念上讲，P 的实例是通过调用默认构造函数 c(*args, **kwargs) 生成的，该函数会执行以下操作：

  • 如果 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 = ...)

repository_rule

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

创建新的代码库规则。将其存储在全局值中，以便可以从 module_extension() 实现函数加载和调用，或由 use_repo_rule() 使用。

参数

参数 说明
implementation callable; required
the function that implements this rule. 必须具有单个形参 repository_ctx。在加载阶段，系统会针对规则的每个实例调用该函数。
attrs dict；或 None； 默认值为 None
用于声明代码库规则的所有属性的字典。它从属性名称映射到属性对象（请参阅 attr 模块）。以 _ 开头的属性是私有属性，可用于向文件添加对标签的隐式依赖项（存储库规则不能依赖于生成的制品）。系统会隐式添加属性 name，因此不得指定该属性。

声明的属性会将 None 转换为默认值。
local bool； 默认值为 False
表示此规则从本地系统提取所有内容，并且应在每次提取时重新评估。
environ 字符串的序列； 默认值为 []
已弃用。此参数已被弃用。改用 repository_ctx.getenv。
提供此代码库规则所依赖的环境变量列表。如果该列表中的某个环境变量发生变化，系统将重新提取相应代码库。
configure bool； 默认值为 False
指示代码库是否出于配置目的检查系统
remotable bool； 默认值为 False
实验性。此参数目前处于实验阶段，随时可能发生变化。请勿依赖此功能。可通过设置 --experimental_repo_remote_exec
启用（实验性）与远程执行兼容
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=[])

创建新规则，该规则可从 BUILD 文件或宏中调用，以创建目标。

规则必须分配给 .bzl 文件中的全局变量；全局变量的名称就是规则的名称。

测试规则的名称必须以 _test 结尾，而所有其他规则的名称都不得包含此后缀。（此限制仅适用于规则，而不适用于规则的目标。）

参数

参数 说明
implementation 函数； 必需
实现此规则的 Starlark 函数，必须只有一个参数：ctx。在分析阶段，系统会针对规则的每个实例调用该函数。它可以访问用户提供的属性。它必须创建操作来生成所有声明的输出。
test 布尔值； 默认值为 unbound
相应规则是否为测试规则，即是否可以作为 blaze test 命令的主题。所有测试规则都会自动被视为可执行；无需（也不建议）为测试规则明确设置 executable = True。该值默认为 False。如需了解详情，请参阅 “规则”页面。
attrs dict；默认值为 {}
用于声明规则的所有属性的字典。它从属性名称映射到属性对象（请参阅 attr 模块）。以 _ 开头的属性是私有属性，可用于添加对标签的隐式依赖项。系统会隐式添加属性 name，因此不得指定该属性。系统会隐式添加属性 visibility、deprecation、tags、testonly 和 features，并且这些属性无法被替换。大多数规则只需要少量属性。为了限制内存用量，可声明的属性数量存在上限。

声明的属性会将 None 转换为默认值。
outputs dict；或 None；或 函数； 默认值为 None
已弃用。此参数已被弃用，很快就会被移除。请勿依赖此功能。它已通过 --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" 中，dirname 为 a，basename 为 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 字符串的序列； 默认值为 []
目标配置中规则所需的配置 fragment 的名称列表。
host_fragments 字符串的序列；默认值为 []
规则在主机配置中所需的配置 fragment 的名称列表。
_skylark_testable bool；默认值为 False
（实验性）

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

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

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

列表中的每个元素都是 provider() 返回的 *Info 对象，但旧版提供程序除外，旧版提供程序由其字符串名称表示。如果规则的目标用作声明必需提供程序的目标的依赖项，则无需在此处指定该提供程序。实现函数返回该值就足够了。不过，即使这不是必需的，指定该属性也被认为是最佳实践。不过，方面的 required_providers 字段要求在此处指定提供商。

dependency_resolution_rule bool; 默认值为 False
如果设置，规则可以通过在实体化程序中标记为可用的属性成为依赖项。设置了此标志的规则的每个属性都必须标记为在具体化程序中可用。这样一来，标记为“不允许”的规则就无法依赖于未标记为“不允许”的规则。
exec_compatible_with 字符串序列；默认值为 []
适用于相应规则类型的所有目标的执行平台限制条件列表。
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 dict；或 None； 默认值为 None
从执行组名称（字符串）到 exec_group 的字典。如果设置，则允许规则在单个目标中的多个执行平台上运行操作。如需了解详情，请参阅执行组文档。
initializer 默认值为 None
实验性：用于初始化规则属性的 Stalark 函数。

系统会在加载时针对规则的每个实例调用该函数。系统会使用 name 和规则定义的公共属性的值（而不是通用属性，例如 tags）调用该函数。

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

在评估属性定义中指定的默认值之前，系统会先评估初始化程序。因此，如果初始化程序签名中的某个形参包含默认值，则该默认值会覆盖属性定义中的默认值（返回 None 的情况除外）。

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

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

对于扩展规则，所有初始化程序都会按从子级到祖先的顺序调用。每个初始化程序仅传递其已知的公共属性。

parent 默认值为 None
实验性：要扩展的 Stalark 规则。设置后，系统会合并公共属性以及通告的提供程序。该规则与父级中的 executable 和 test 相匹配。合并 fragments、toolchains、exec_compatible_with 和 exec_groups 的值。可能无法设置旧版或已弃用的参数。在应用此规则的传入配置后，应用父级的传入配置过渡 cfg。
extendable 布尔值；或标签；或字符串；或 None； 默认值为 None
实验性功能：一个许可名单标签，用于定义哪些规则可以扩展此规则。也可以将其设置为 True/False，以始终允许/禁止扩展。Bazel 默认始终允许扩展程序。
subrules 子规则的序列；默认值为 []
实验性：此规则使用的子规则列表。

选择

unknown select(x, no_match_error='')

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

参数

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

子规则

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

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

参数

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

子规则只能具有标签类型的私有属性（即标签或标签列表）。与这些标签对应的已解析值会自动由 Bazel 作为具名实参传递给子规则的实现函数（因此实现函数必须接受与属性名称匹配的具名形参）。这些值的类型将为：

  • FilesToRunProvider，用于具有 executable=True 的标签属性
  • File，用于具有 allow_single_file=True 的标签属性
  • Target（适用于所有其他标签属性）
  • 所有标签列表属性的 [Target]
toolchains 序列； 默认值为 []
如果设置，则表示相应子规则所需的工具链集。该列表可以包含 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)

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

参数

参数 说明
attrs dict； 默认值为 {}
用于声明相应标记类的所有属性的字典。它从属性名称映射到属性对象（请参阅 attr 模块）。

请注意，与 rule()、aspect() 和 repository_rule() 不同，声明的属性不会将 None 转换为默认值。如需使用默认值，调用方必须完全省略相应属性。
doc 字符串；或 None； 默认值为 None
可由文档生成工具提取的标记类的说明。

visibility

None visibility(value)

设置当前正在初始化的 .bzl 模块的加载公开范围。

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

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

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

参数

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