本页介绍了 Starlark 的基本样式准则,还介绍了与宏和规则相关的信息。
Starlark 是一种定义软件构建方式的语言,因此它既是一种编程语言,也是一种配置语言。
您将使用 Starlark 来编写 BUILD
文件、宏和构建规则。宏和规则本质上是元语言,它们定义了 BUILD
文件的编写方式。BUILD
文件应简洁且重复。
所有软件的读取频率比写入频率高。对于 Starlark 来说尤其如此,因为工程师会阅读 BUILD
文件来了解其目标的依赖项及其 build 的详细信息。这种读取通常是顺带、匆忙或并行完成其他一些任务时发生的。因此,简洁性和可读性非常重要,以便用户可以快速解析和理解 BUILD
文件。
当用户打开 BUILD
文件时,他们会很快想要知道文件中的目标列表;或者查看该 C++ 库的源代码列表;或从该 Java 二进制文件中移除依赖项。每当添加抽象层时,用户都会更难以执行这些任务。
BUILD
文件也会由许多不同的工具分析和更新。如果您的 BUILD
文件使用了抽象,工具可能无法修改该文件。请尽量简化 BUILD
文件,以便获得更好的工具。随着代码库不断扩大,为了更新库或执行清理,对多个 BUILD
文件进行更改会变得越来越频繁。
总体建议
- 使用 Buildifier 作为格式设置和 linter。
- 遵循测试指南。
风格
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,
)
布尔值
对于布尔值(例如在规则中使用布尔值属性时),首选值 True
和 False
(而不是 1
和 0
)。
仅将输出用于调试
请勿在生产代码中使用 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
的目标。
- 为属性使用一致的名称和类型。一些普遍适用的属性包括:
srcs
:label_list
,允许文件:源文件,通常是人工编写的文件。deps
:label_list
,通常不允许文件:编译依赖项。data
:label_list
,允许使用以下文件:数据文件,例如测试数据等。runtime_deps
:label_list
:编译不需要的运行时依赖项。
- 对于任何行为不明显的属性(例如,具有特殊替代值的字符串模板,或根据特定要求调用的工具),请在属性的声明(
attr.label_list()
或类似内容)中使用doc
关键字参数提供文档。 - 规则实现函数几乎总是应该为私有函数(以前导下划线命名)。常见的样式是将
myrule
的实现函数命名为_myrule_impl
。 - 使用明确定义的 provider 接口在规则之间传递信息。声明字段和文档提供程序字段。
- 设计规则时要考虑到可扩展性。请考虑其他规则可能想要与您的规则交互、访问您的提供程序并重复使用您创建的操作。
- 遵循规则中的效果指南。