.bzl 文件

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

显式属性必须为 string 类型，并且必须使用 values 限制。显式属性会限制相应方面仅与具有相同名称、类型和有效值的规则搭配使用。

声明的属性会将 None 转换为默认值。

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

若要让某些规则（例如 some_rule）的目标对某个方面可见，some_rule 必须宣传至少一个必需提供商列表中的所有提供商。例如，如果某个方面（aspect）的 required_providers 为 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]]，则只有当 some_rule 提供 FooInfo、BarInfo 或同时提供 BazInfo 和 QuxInfo 时，此方面才能看到 some_rule 目标。

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

若要使另一个 aspect（例如 other_aspect）对此 aspect 可见，other_aspect 必须提供至少一个列表中的所有提供程序。在 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] 示例中，只有当 other_aspect 提供 FooInfo、或 BarInfo、或 BazInfo 和 QuxInfo 时，此 aspect 才能看到 other_aspect。

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

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

例如，假设某个方面通过属性 `deps` 传递，并应用于目标 `alpha`。假设 `alpha` 的 `deps = [':beta_output']`，其中 `beta_output` 是目标 `beta` 的声明输出。假设 `beta` 的 `deps` 之一是目标 `charlie`。如果该方面的 `apply_to_generating_rules=True`，则该方面将通过 `alpha`、`beta` 和 `charlie` 传播。如果为 False，则该方面将仅传播到 `alpha`。

默认值为 false。

根据惯例，实现函数应针对宏需要检查、修改或传递给非“主要”目标的任何属性提供命名参数，而将以不变形式传递给“主要”目标的“批量”继承属性则以 **kwargs 的形式传递。

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

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

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

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

• package()、licenses()
• environment_group()
• native.glob() - 您可以改为通过标签列表属性将正则表达式传递给宏
• native.subpackages()
• （仅在规则终结器中允许，请参阅下文中的 finalizer） native.existing_rules(), native.existing_rule()
• （适用于 WORKSPACE 线程） workspace()、register_toolchains()、register_execution_platforms()、bind()、代码库规则实例化

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

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

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

如果将 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）同时传递给“main”和非“main”目标，则实现函数可以为这些继承的属性提供显式参数，这样会很方便；但如果宏还需要检查或操控这些属性，则必须小心处理非必需继承属性的 None 默认值。

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

• 字段列表：
  

  provider(fields = ['a', 'b'])

• 字典字段名称 -> 文档：
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

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

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

• 如果 args 不为空，则会发生错误。
• 如果在调用 provider() 时指定了 fields 参数，并且 kwargs 包含 fields 中未列出的任何键，则会发生错误。
• 否则，c 会返回一个新实例，其中 kwargs 中的每个 k: v 条目都有一个名为 k 且值为 v 的字段。

MyInfo = provider()
m = MyInfo(foo = 1)

但是，如果指定了 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 = ...)

声明的属性会将 None 转换为默认值。

声明的属性会将 None 转换为默认值。

用于定义预声明输出的架构。与 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 访问。

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

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

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

如果将规则定义为分析测试规则，则允许对其属性使用使用 analysis_test_transition 定义的配置转换，但会选择接受一些限制：

• 此规则的目标可能具有的传递依赖项数量有限。
• 该规则会被视为测试规则（就像设置了 test=True 一样）。此值会替换 test 的值
• 规则实现函数可能无法注册操作。而是必须通过提供 AnalysisTestResultInfo 来注册通过/失败结果。

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

它必须返回一个字典，其中包含属性名称与所需值的对应关系。未返回的属性不会受到影响。将 None 作为值返回会导致使用属性定义中指定的默认值。

系统会先评估初始化程序，然后再评估属性定义中指定的默认值。因此，如果初始化程序签名中的参数包含默认值，则会覆盖属性定义中的默认值（返回 None 除外）。

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

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

对于扩展规则，系统会从子级到祖先依次调用所有初始化程序。每个初始化程序只会传递它知道的公共属性。

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

• FilesToRunProvider（适用于带有 executable=True 的标签属性）
• File（适用于带有 allow_single_file=True 的标签属性）
• Target：适用于所有其他标签属性
• [Target]（适用于所有标签列表属性）

请注意，与 rule()、aspect() 和 repository_rule() 不同，声明的属性不会将 None 转换为默认值。如需使用默认值，调用方必须完全省略该属性。

软件包规范遵循与 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" 值始终可用，"//..." 始终被解释为“当前代码库中的所有软件包”。