常见的 Bazel 样式指南和最佳实践

概览

以下样式和最佳实践适用于 Fuchsia 中的所有 Bazel 文件。

本页是 Bazel 样式指南和最佳实践的一部分，其中包含针对特定场景的更多指导。

用于存储源文件和依赖项列表的局部变量

虽然官方指南不建议使用依赖变量，但 Fuchsia 允许使用它们来管理大型共享的源文件或依赖项列表。练习：考虑一下这些列表是基本相似，还是仅共享一些共同的项目。

不减去：绝不从列表变量中移除项。

公开范围

以下是一般准则，适用于 BUILD.bazel 和 .bzl 文件。如需了解更具体的详情，请参阅相应页面。

尽可能在 BUILD.bazel 和 .bzl 文件中指定可见性

该属性唯一受支持的场景是，不需要指定该属性的宏是软件包（目录）私有的宏。

请勿使用公开范围

请勿在 bazel_sdk/ 目录之外使用公开范围（"//visibility:public" 或 visibility("public")）。只有当代码由外部代码库使用时，这种访问权限级别才适用，但 fuchsia.git 中的非 SDK 代码不属于这种情况。

应尽可能缩小可见性范围，同时仍允许测试和反向依赖项进行访问

可见性应仅限于需要该权限和/或应允许使用该权限的目标。保守但实用。例如，如果目标是在 //src 的五个直接子目录中使用，请考虑使用 //src:__subpackages__，以免在添加新用途时需要修改可见性。不过，如果目标仅供驱动程序使用，则将其限制为实现驱动程序的软件包。

使用软件包组实现常见的非平凡可见性定义

如果多个目标的 visibility 应限制为同一组标签，请考虑使用 package_group 表示该组标签。package_group 在与目标搭配使用时还支持负可见性，但与加载可见性搭配使用时不支持。

请勿混用 SDK 和平台符号及目标

平台目标（即 AIB 或 IDK 中的所有内容）不得使用 Fuchsia Bazel SDK 中定义的符号、其提供的目标或使用其构建的目标。

反之亦然，使用 Fuchsia Bazel SDK 构建的目标不应依赖于平台目标，也不应从平台 .bzl 文件加载符号。

不使用 Fuchsia Bazel SDK 路径

平台代码绝不应访问包含 bazel_sdk 或 Fuchsia Bazel SDK 代码库路径（例如以下路径）的文件路径：

  • @fuchsia_sdk//

  • @internal_sdk//

  • @rules_fuchsia//fuchsia

唯一允许的此类路径以 @fuchsia_rules_common/ 开头，但只有 Build 团队可以直接使用这些路径。

平台代码还应避免使用 bazel_sdk/ 路径，除非是与 Fuchsia Bazel SDK 共享实现的特定 build 规则。

目标和 .bzl 文件的标签

引用目标

在引用目标（例如在 deps 中）时，只要不使用禁止的标签模式，便允许使用以以下任意字符开头的标签：

  • :

    • 仅对同一软件包（BUILD.bazel 文件）中的目标使用相对标签。

  • //

  • @platforms//

从 .bzl 文件加载

Fuchsia 平台的大多数通用宏和规则都可以在 //build/bazel/rules/ 中找到。

只要不使用禁止的标签模式，就可以安全地从标签以以下内容开头的 .bzl 文件中 load()：

以下内容也允许使用，但只有 Build 团队的开发者可能会使用：

  • @fuchsia_build_config//:defs.bzl

  • @fuchsia_build_info//:args.bzl

  • @fuchsia_rules_common//

禁止的标签格式

请勿使用 [SHAC 错误]：

  • Workspace 根软件包标签（以 //: 开头的标签）

    • 在非常特殊且极少见的情况下，需要这样做（请参阅问题 560343570），但一般情况下，只有 build 团队才应这样做。

  • 在软件包名称（即冒号 [:] 后面的标签部分）中包含斜杠 (/) 的标签。

    • 在极少数情况下，可以集成第三方库。

fuchsia_… 文件和符号位于 Fuchsia Bazel SDK 中

避免定义名称以 fuchsia_ 开头的文件、宏和规则。以 fuchsia_ 开头的现有实例名称可能属于 Fuchsia Bazel SDK（请参阅请勿使用 Fuchsia Bazel SDK 路径），避免使用此类名称有助于保持这种分离。

如需了解在需要区分 Fuchsia 平台与常规 Bazel 标识符时使用的一种模式，请参阅封装内置规则、常见规则、宏和函数。

使用特定于 Fuchsia 的封装容器

如果存在特定于 Fuchsia 的封装容器，请使用这些封装容器，而不是外部代码库、宏等。这有助于确保 Fuchsia build 配置得到一致应用。

具体来说，有以下语言的封装容器：

  • C/C++：使用 //build/bazel/rules/cc/... 中的 fx_cc_...()，而不是 @rules_cc// 中的 cc_...。

  • Rust：使用 //build/bazel/rules/rust/... 中的 rustc_...()，而不是 @rules_rust// 中的 rust_...。

Fuchsia 没有以下语言的封装容器。从以下路径加载，以保持一致性：

  • Go：@io_bazel_rules_go//go...

  • Python：@rules_python//python...

字符串

使用双引号表示字符串，但为了避免转义

默认情况下，使用双引号表示字符串。不过，如果打印双引号更合适，但这样做需要对双引号进行转义 (\")，请使用单引号以避免转义。