.bzl 文件样式指南和最佳实践

概览

Fuchsia 项目遵循官方 Bazel .bzl 样式指南，但有少数例外情况。本页面上的指导是对常见 Bazel 样式指南和最佳实践的补充。

.bzl 文件最常用于定义规则、宏和函数，这方面有额外的指南。

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

公开范围

加载可见性

与 .gni 文件不同，.bzl 文件支持加载可见性，以限制它们的加载来源。默认情况下，没有限制。

始终在 .bzl 文件中指定 visibility：

• 对于并非专门用于软件包外部的任何 .bzl 文件，请使用 visibility("private")。

  • 尤其是当软件包包含公共和私有 .bzl 文件时，将后者放在 private/ 目录中可能更有意义。Bazel 具有限制加载此类目录中的文件的机制。

• 否则，请使用 visibility([...]) 指定可以使用它的软件包（目录）。

加载 visibility 使用的语法与目标 visibility 不同：

• 仅路径相当于 :__pkg__。

• /... 所遵循的路径相当于 :__subpackages__。

对于真正打算在整个代码库中使用的非常常见的目标，可以使用 "//..."。请勿使用公开可见性 (visibility("public"))。不过，在大多数情况下，一组顶级和/或二级目录（例如 "//src/..." 和 "//sdk/lib/..."）就足够了。

符号显示状态

在 .bzl 文件中，为符号名称添加下划线前缀，以将访问权限限制在 .bzl 文件内，从而防止其他文件（即使在同一软件包 [目录] 内）使用这些符号名称。

不创建 defs.bzl 文件

虽然您可能会看到这种情况，尤其是在第三方代码库中，但定义或导出多个不确定是否会一起使用的符号（如 defs.bzl 文件中经常出现的情况）是一种反模式。请参阅限制每个 .bzl 文件导出的符号数量。在所有情况下，请选择更具描述性的文件名。