.bzl 文件

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

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

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

为了使某个规则（例如 some_rule）定位到的内容对某个方面可见，some_rule 必须宣传至少一个必需提供商列表中的所有提供商。例如，如果某方面的 required_providers 为 [[FooInfo], [BarInfo], [BazInfo, QuxInfo]]，则该方面可以查看 some_rule 目标，前提是 some_rule 提供 FooInfo、或 BarInfo、或 BazInfo 和 QuxInfo 两者。

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

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

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

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

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

默认值为 false。

• 字段列表：
  

  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 = ...)

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

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

列表中的每个元素都是 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]

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