定义 Bazel 规则、宏和函数

概览

本页包含 Fuchsia 特有的样式以及编写规则、宏和函数的最佳实践。这些始终在 .bzl 文件中定义,并且这些文件的指南也适用于此处。此外,与 BUILD.bazel 文件中的目标相关的指南也适用于由规则和宏定义的目标。

本页面是 Bazel 样式指南和最佳实践的一部分。

考虑新宏和函数是否合适

与 Bazel 样式指南一样,Fuchsia 更倾向于使用 DAMP(描述性和有意义的短语)BUILD 文件,而不是 DRY(不要重复)。

具体而言,与在 GN 中使用此类模板相比,Fuchsia build 在 Bazel 中使用特定于区域的宏和函数的频率要低得多。

使用共享的静态列表,其中内容必须保持同步(例如常见依赖项),而不是编写特定于区域的宏。

虽然特定于区域的模板可以减少在初始创建目标时输入的内容,但它们会成为维护和迁移问题,尤其是对于自动化工具,因为各个目标会被特定于区域的宏隐藏。如果您认为使用特定于区域的宏和函数会带来很大好处,请咨询构建团队(根据以往的经验,标准很高)。

尽可能优先使用现有宏和规则

随着此类宏或规则的潜在使用范围扩大,这一点的重要性也随之增加。

特别是,如果您的需求仅限于以下方面,请考虑是否可以使用现有宏和/或规则来实现:

  • 正在生成元数据

  • 强制执行属性值

  • 例如,尽量减少调用方必须指定的属性数量

尤其是在前两种情况下,请考虑 Bazel 查询、SHAC 规则、测试或其他机制是否可以满足您的需求。Bazel 查询可以在依赖项树或目录树中定义的所有目标上运行。你能编写一个测试来运行查询并检查结果吗?如果您的用例需要额外属性,请考虑使用标记。

使用现有规则和宏的原因包括:

  • 更易于理解,开发者的磨合期更短

    • 熟悉 Bazel 的开发者可以快速上手并理解目标。

    • 团队中某个部分的开发者可以了解代码库其他部分中的目标。

  • AI 更有可能理解和生成使用常见规则和宏的 Bazel 文件

  • 需要更少的 load() 语句

    • 内置标识符不需要任何 load 语句。

    • 其他目标可能已加载到文件中的其他目标。

  • 减少出现 bug 的机会

    • 例如,只有当切面遍历所有相关目标时,它们才能正常工作。自定义宏或规则可能会引入不会被遵循的路径。请参阅使用标准属性名称。

首选符号宏,而非旧版宏

建议编写符号宏(使用 macro() 定义),而不是旧版宏(使用 def 定义的类似 Python 的函数,用于创建目标)。符号宏可提供更清晰的属性及其类型文档,对属性执行类型检查,并确保在调用网站上评估标签。它们还支持属性继承(通过 inherit_attrs)。如需了解更多背景信息,请参阅为什么不应使用旧版宏。

切勿在符号宏的实现函数中为实参指定默认值,因为默认值由 attrs 条目定义,并且系统会为每个属性提供一个值。

在某些情况下,有必要在符号宏周围使用旧版宏封装容器,但对于大多数开发者来说,这种情况应该非常罕见。

对宏中定义的目标进行可见性和访问权限检查

概览

为了便于理解可见性,您可以将旧版宏视为在实例化时内嵌展开。在 BUILD.bazel 文件中使用时,由旧版宏定义的目标实际上是在该文件中定义的。因此:

  • 所定义目标的默认 visibility 与实例化软件包相同,包括软件包 default_visibility(如果已指定)。

  • 宏可以使用(例如,添加到 deps)对实例化软件包可见的任何目标。

    • 定义旧版宏的 .bzl 文件的位置无关紧要。

不过,出于可见性考虑,请将符号宏定义的目标视为在与定义宏的 .bzl 文件位于同一软件包(目录)中的 BUILD.bazel 文件中定义。因此:

  • 所定义目标的默认 visibility 是包含 .bzl 文件的软件包(目录)。

  • 宏可以使用(例如,添加到 deps)对包含 .bzl 文件的软件包(目录)可见的任何目标。

    • 例如,这对于 fidl_library() 添加的 FIDL 绑定支持库非常有用。

    • 但对于 HLCPP 支持库许可清单等内容,这会带来问题。

    • 如需了解详情,请参阅问题 446911800。

为宏中定义的目标指定公开范围

公开目标

将传递给宏的 visibility 属性转发给宏定义的主要目标(即 name 传递到的目标)。visibility 属性也可能会根据需要转发到宏的 doc 字符串中提及的其他已定义公共目标。

私有目标

在符号宏中,定义的所有其他目标的公开范围默认为 ["//visibility:private"]。不过,对于旧版宏,您必须为旧版宏定义的所有目标指定可见性。

为旧版宏定义的所有目标指定公开范围

为不使用传递给宏的 visibility 属性的所有目标指定 visibility = ["//visibility:private"]。这是为了防止它们默认使用软件包的 default_visibility(如果已指定)。

使用标准属性名称

在宏和规则中使用标准属性名称。例如,使用 "deps"、"data" 甚至 "tools",而不是 "images" 或 "scripts"。请参阅一些通常适用的属性。

原因包括:

  • 为了提高可读性,以及出于与尽可能优先使用现有宏和规则中类似的其他原因。

  • 切面只有在遍历所有相关目标时才能正常运行,并且宏通常会配置为应用于 "deps" 和其他常见属性(视情况而定)。不过,他们不太可能知道 "rust_deps" 等属性,如果未能应用于该属性,可能会排除与该方面相关的目标。

需要具名实参

公共函数和旧版宏(一种特殊类型的函数)通常应声明仅限关键字的实参(所有实参都在 *, 之后声明)。如果函数最多只有几个实参,且实参可以从符号名称中清楚地看出,并且实参不会在错误的位置被误用(包括由于重构/重新排序),则可以例外。布尔值参数和具有默认值的参数应始终出现在 * 之后。

虽然这对于要由代码库的其他部分使用的符号最为重要,但也适用于所有 .bzl 文件中的公共符号。

这有助于强制执行 Bazel .bzl 样式指南的指导,即“调用宏时,仅使用关键字实参。这与规则一致,并大大提高了可读性。”

声明宏使用的所有实参

如果宏(可选)使用实参,请在宏实现的形参列表中明确声明该实参,而不是从 kwargs 中提取。例如,请避免以下情况:

# Do NOT do this:
testonly = kwargs.get("testonly", False),

声明实参可以更清楚地表明哪些实参与宏实现相关(例如,与它调用的宏相比),并提供一个查看默认值的位置。对于旧版宏,它还可确保记录实参。(这主要与 Fuchsia Bazel SDK 相关。)

与任何其他参数一样,但尤其是所有 build 规则通用的属性和所有测试规则通用的属性 (_test),您必须确保将该参数传递给支持它的所有宏和规则,因为这些宏和规则不会在 **kwargs 中。

符号宏中的可配置属性

在符号宏中,属性默认可配置,这意味着调用方可以传递 select() 表达式。对于可选属性,省略或 None 实参会解析为属性的默认值(将 None 传递给 mandatory = True 属性会被视为省略并失败)。对于可配置属性,Bazel 会自动将每个非 None 解析值(包括非 None 默认值,例如 False、"" 或 [])封装到 select() (SelectorList) 中,然后再将其传递给宏的 implementation 函数(而不可配置属性(例如 configurable = False、attr.output() 和 attr.output_list())会接收具体值)。只有默认值为 None 的可配置属性 - attr.label()(没有默认值或 default = None)和通过 inherit_attrs 继承的非强制性属性(其默认值被替换为 None,除非在 attrs 中被替换为非 None 默认值)- 在省略或传递 None 时会作为 None 到达(而传递 select({"//conditions:default": None}) 会传递 SelectorList)。

由于 select() 值在 Starlark 中始终为真,与具体值不相等(例如,attr == [] 始终为 False),并且无法迭代、编入索引、设置格式或放置在列表或字典字面量中,因此请勿对可配置属性或 select() 值执行需要具体值的操作 [SHAC 错误]:

  • 布尔值求值:请勿使用 if attr:、not attr、attr or default 或 bool(attr)。使用 attr == None 或 attr != None 检查是否省略了默认值为 None 的可配置属性(没有非 None 默认值或非强制继承属性的 attr.label())或传递了 None。对于具有非 None 默认值的可配置属性(例如 attr.bool()、attr.string() 或 attr.string_list()),Bazel 会将默认值封装在 select() 中,因此 attr == None 始终为 False。

  • 容器字面量和迭代:请勿将可配置属性放在列表、元组或字典字面量(例如 [attr] 或 {"key": attr})中,也不要对其进行迭代 (for x in attr) 或将其传递给序列函数(len(attr)、list(attr))。使用 + 串联列表,使用 | 合并字典。

  • 值比较、字符串格式设置和方法调用:请勿将可配置属性与非 None 值 (attr == "foo") 进行比较、设置其格式("%s" % attr 或 "{}".format(attr))、对其调用方法,或将其传递给不可配置属性(例如 name、tags、testonly 或 visibility)。

如果宏实现必须检查、设置格式、迭代或分支属性值,或将其传递给不可配置的属性,请在 attrs 中使用 configurable = False 声明该属性。

评论

  • 为所有公共函数(不以下划线开头的函数)提供函数级注释。

  • 为所有规则和宏提供 doc 字符串。

  • 为所有规则和宏属性提供 doc 字符串。

    • 对于私有属性(以下划线开头的属性),如果其含义从 default 值中显而易见,则可以省略 doc 字符串。

文档字符串

  • 在 Fuchsia 平台中,doc 字符串应在源文件中读取,而不是在某些生成的文档中读取。因此,请优先考虑针对该情况进行优化,而不是考虑某些生成的文档可能是什么样子。

  • 长 doc 字符串:

    • 在合理的情况下,最好将顶级单句说明完全写在与 doc= 相同的行中。

    • Bazel 中没有严格的行长度限制。

    • 如果需要多行,请使用三引号编写多行字符串。

    • 避免附加常规字符串。

  • 多行 doc 字符串

    • 在与 doc 实参 (doc = """Begin the comment...) 相同的行上开始多行字符串。

    • 后续行从 doc 中的 d 下方开始,类似于 Python 注释从第一个 " 下方开始下一行。

    • 这可以优化一致性和可读性,同时接受它不适合生成文本的事实。

    • 多行字符串应以三引号 (""") 结尾,且三引号应单独成行并与 doc 对齐。

规则和宏实现函数名称

为 rule() 和 macro() 实例的 implementation 函数命名时,请使用前导下划线,后跟规则或函数的名称,并以 _impl 结尾。

在宏中引用目标名称时使用变量

如果宏定义了一个目标,然后在另一个目标中依赖该目标,请使用前一个目标的名称定义一个变量,并将其用于其 name 属性和后一个目标的 deps 中。

这可以明确地关联两个目标,尤其是在基于其他目标名称存在多个级别的目标名称的复杂情况下,并且更易于突出显示和搜索。

请勿对内部未使用的目标使用变量,除非这样做可以提高可读性,例如在同一位置定义所有目标名称时。

封装内置和常用规则、宏和函数

在编写宏以替换 Fuchsia 平台代码库中的常见 Bazel 规则、宏或函数时,请在封装的名称前加上 fx_。例如,应使用 fx_cc_library(),而不是 cc_library()。 “Common”包括 Bazel 中内置的符号(包括 native.*)以及常见代码库(例如 rules_cc)中的符号。对于其他冲突(例如与 package 无关的 fx_package()),也请使用此前缀。请勿使用 fuchsia_ 前缀,因为 fuchsia_... 文件和符号位于 Fuchsia Bazel SDK 中。

添加新的 C/C++ 或 Rust 封装容器宏或规则时,请参阅 //build/bazel/rules/cc/README.md 或 //build/bazel/rules/rust/README.md,了解有关更新 bazel_fuchsia_wrappers SHAC 检查和相关文档的说明。

避免配置转换

Fuchsia 平台目标应该已经以正确的配置进行构建。如果您认为自己需要过渡,那么您很可能不需要。请与 Build 团队联系;只有 Build 团队可以添加转换或新平台。

将工具作为可执行标签属性传递

运行工具的规则应将其作为 attr.label(executable = True, cfg = "exec") 并使用 ctx.executable 读取。

反模式

  • 正在通过PATH查找工具。Infra 沙盒不会设置它,Bazel 无法跟踪它不知道的工具。而是将该工具作为可执行标签属性传递。

  • 将嵌入标签的 JSON 或字典 blob 传递到规则或宏中。Bazel 只能看到标签类型属性中的标签,因此不会构建或跟踪这些依赖项。请改用标签属性和提供程序。

  • 通过 bazel-bin 符号链接查找 build 输出。它指向一个配置,而转换可以将您想要的输出放入不同的 bazel-out 目录中。通过提供程序传递输出或明确报告其路径。

  • 依赖于上游规则集的实现细节,例如 rules_cc 使用的 _solib_ 目录前缀。当规则集更新时,它们会发生变化,恕不另行通知。

避免缓存或远程处理大型工件

请参阅避免缓存大型工件。