.bzl 样式指南

本页介绍了 Starlark 的基本样式准则,还介绍了与宏和规则相关的信息。

Starlark 是一种定义软件构建方式的语言,因此它既是一种编程语言,也是一种配置语言。

您将使用 Starlark 来编写 BUILD 文件、宏和构建规则。宏和规则本质上是元语言,它们定义了 BUILD 文件的编写方式。BUILD 文件应简洁且重复。

所有软件的读取频率比写入频率高。对于 Starlark 来说尤其如此,因为工程师会阅读 BUILD 文件来了解其目标的依赖项及其 build 的详细信息。这种读取通常是顺带、匆忙或并行完成其他一些任务时发生的。因此,简洁性和可读性非常重要,以便用户可以快速解析和理解 BUILD 文件。

当用户打开 BUILD 文件时,他们会很快想要知道文件中的目标列表;或者查看该 C++ 库的源代码列表;或从该 Java 二进制文件中移除依赖项。每当添加抽象层时,用户都会更难以执行这些任务。

BUILD 文件也会由许多不同的工具分析和更新。如果您的 BUILD 文件使用了抽象,工具可能无法修改该文件。请尽量简化 BUILD 文件,以便获得更好的工具。随着代码库不断扩大,为了更新库或执行清理,对多个 BUILD 文件进行更改会变得越来越频繁。

总体建议

风格

Python 样式

如有疑问,请尽可能遵循 PEP 8 风格指南。特别是,使用四个(而不是两个)空格进行缩进,以遵循 Python 惯例。

由于 Starlark 不是 Python,因此 Python 样式的某些方面并不适用。例如,PEP 8 建议使用 is 与单例进行比较,后者不是 Starlark 中的运算符。

文档字符串

使用文档字符串记录文件和函数。在每个 .bzl 文件的顶部使用一个文档字符串,并为每个公共函数使用一个文档字符串。

文档规则和切面

应使用 doc 参数记录规则和方面及其属性,以及提供程序及其字段。

命名规范

  • 变量和函数名称使用小写形式,单词用下划线 ([a-z][a-z0-9_]*) 分隔,例如 cc_library
  • 顶级不公开值以一个下划线开头。Bazel 强制不能从其他文件中使用私有值。局部变量不应使用下划线前缀。

行长

BUILD 文件中一样,没有严格的行长度限制,因为标签可以很长。尽可能尝试每行最多 79 个字符(遵循 Python 的样式指南 PEP 8)。请勿严格执行该准则:编辑器应显示的列数应超过 80 列,自动更改通常会引入更长的行,用户不应花费时间来拆分本来已可读取的行。

关键字参数

在关键字参数中,等号前后的空格是首选:

def fct(name, srcs):
    filtered_srcs = my_filter(source = srcs)
    native.cc_library(
        name = name,
        srcs = filtered_srcs,
        testonly = True,
    )

布尔值

对于布尔值(例如在规则中使用布尔值属性时),首选值 TrueFalse(而不是 10)。

请勿在生产代码中使用 print() 函数;该函数仅用于调试用途,且会向您 .bzl 文件的所有直接和间接用户发送垃圾内容。唯一的例外情况是,您可以提交使用 print() 的代码,前提是该代码默认处于停用状态,只能通过修改源代码来启用。例如,如果对 print() 的所有使用均受 if DEBUG: 保护,其中 DEBUG 会硬编码为 False。请注意这些说法是否足以证明其对可读性的影响。

宏是一个函数,用于在加载阶段实例化一条或多条规则。一般情况下,请尽可能使用规则,而不是宏。用户看到的构建图与 Bazel 在构建期间使用的构建图不同 - 宏会在 Bazel 进行任何构建图分析之前展开。

因此,出现问题时,用户需要了解您的宏的实现,以排查构建问题。此外,bazel query 结果可能难以解读,因为结果中显示的目标来自宏扩展。最后,切面无法感知宏,因此根据切面(IDE 和其他)运行的工具可能会失败。

宏的一种安全用途是定义打算在 Bazel CLI 或 BUILD 文件中直接引用的其他目标:在这种情况下,只有这些目标的最终用户才需要了解这些目标,而宏引入的任何构建问题都不会远离其用途。

对于定义生成的目标的宏(不应在 CLI 中引用或取决于未由该宏实例化的目标所依赖的宏的实现详情),请遵循以下最佳实践:

  • 宏应接受 name 参数,并定义具有该名称的目标。该目标将成为该宏的主要目标
  • 生成的目标(即由宏定义的所有其他目标)应该:
    • 用户的名称以 <name>_<name> 为前缀。例如,使用 name = '%s_bar' % (name)
    • 公开范围受限 (//visibility:private),并且
    • 使用 manual 标记以避免在通配符目标(:all...:* 等)中进行扩展。
  • name 只能用于派生由宏定义的目标的名称,而不能用于任何其他用途。例如,请勿使用名称来推导并非由宏本身生成的依赖项或输入文件。
  • 在宏中创建的所有目标都应该以某种方式与主目标相关联。
  • 宏中的参数名称应保持一致。如果将参数作为属性值传递给主目标,请保持其名称不变。如果宏参数的用途与常见规则属性(如 deps)相同,请采用您为该属性指定的名称(见下文)。
  • 调用宏时,请仅使用关键字参数。这与规则一致,并大大提高了可读性。

当相关规则的 Starlark API 不足以满足其特定用例时,工程师往往会编写宏,无论规则是在原生代码中的 Bazel 内定义,还是在 Starlark 中定义。如果您遇到此问题,请询问规则作者是否可以扩展该 API 以实现您的目标。

一般来讲,与规则相似的宏越多越好。

另请参阅

规则

  • 规则、切面及其属性应使用小写名称(“蛇形命名法”)。
  • 规则名称是名词,用于从规则的依赖项(对于叶规则,则为用户)的角度,描述规则生成的主要工件种类。这不一定是文件后缀。例如,一条生成要用作 Python 扩展程序的 C++ 工件的规则可以称为 py_extension。对于大多数语言,典型的规则包括:
    • *_library - 编译单元或“模块”。
    • *_binary - 生成可执行文件或部署单元的目标。
    • *_test - 测试目标。这可能包括多项测试。*_test 目标中的所有测试都应采用同一主题的变体,例如,测试单个库。
    • *_import:用于封装预编译工件(例如 .jar)或编译期间使用的 .dll 的目标。
  • 为属性使用一致的名称和类型。一些普遍适用的属性包括:
    • srcslabel_list,允许文件:源文件,通常是人工编写的文件。
    • depslabel_list,通常不允许文件:编译依赖项。
    • datalabel_list,允许使用以下文件:数据文件,例如测试数据等。
    • runtime_depslabel_list:编译不需要的运行时依赖项。
  • 对于任何行为不明显的属性(例如,具有特殊替代值的字符串模板,或根据特定要求调用的工具),请在属性的声明(attr.label_list() 或类似内容)中使用 doc 关键字参数提供文档。
  • 规则实现函数几乎总是应该为私有函数(以前导下划线命名)。常见的样式是将 myrule 的实现函数命名为 _myrule_impl
  • 使用明确定义的 provider 接口在规则之间传递信息。声明字段和文档提供程序字段。
  • 设计规则时要考虑到可扩展性。请考虑其他规则可能想要与您的规则交互、访问您的提供程序并重复使用您创建的操作。
  • 遵循规则中的效果指南