BUILD.bazel 文件

概览

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

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

公开范围

避免使用软件包 default_visibility

最好为必须在软件包外部访问的每个目标指定可见性，而不是声明软件包 default_visibility。通常，如果在目标定义中指定了公开范围，BUILD.bazel 文件会更易于理解。此外，使用 default_visibility 意味着不公开目标默认具有一定程度的公开可见性。

default_visibility 只能在极少数情况下使用，即 BUILD.bazel 文件中的每个目标（现在和将来）都应具有相同的可见性。这意味着 BUILD.bazel 文件中未定义任何私有辅助程序目标。例如，当定义了许多 widget 且它们都需要对另一个软件包（目录）中的 widget 加载器或 widget 测试可见时。

请勿将 default_visibility 用于 //visibility:public 和其他广泛可见性（例如 //:__subpackages__ 或 //src:__subpackages__）[SHAC 错误]。

在 GN 术语中，在 BUILD.bazel 文件中使用 default_visibility = [...] 相当于将 visibility = [...] 放在 BUILD.gn 文件的顶部。在这两种情况下，您都需要确保为每个内部目标指定不公开的 visibility。

目标可见度

概览

在 Bazel 中：

  • 可见性在软件包（目录）级别。无法将公开范围限制为特定目标（无论是在同一软件包中还是在其他软件包中）。

    • 如果需要，请考虑将目标重构为子目录，以便单独引用。

  • 默认情况下，目标是软件包私有的，这意味着它们对同一软件包（BUILD.bazel 文件）中的其他目标可见。

    • 这相当于 visibility = [ ":__pkg__" ]。

    • 虽然可见性可以扩展（见下文），但无法阻止同一软件包（BUILD.bazel 文件）中的其他目标使用。

    • 如果需要，请考虑将其他目标重构到子目录中。

  • 必须指定目标 visibility，以便在定义它们的软件包（目录）之外访问它们。

对于熟悉 GN

  • Bazel 目标默认不公开，而在 GN 中，目标默认公开。

    • BUILD.bazel 文件中的默认公开范围相当于在每个 BUILD.gn 文件的顶部放置 visibility = [":*"]。

  • ...:__pkg__ 相当于 "...:*"

  • ...:__subpackages__ 相当于 ".../*"

  • 在 Bazel 中，目标始终对同一软件包（目录）中的其他目标可见，且无法更改。

    • 在 GN 中，这相当于 visibility 始终包含 ":*"。

    • 在具有相互依赖的目标的 BUILD.bazel 文件上使用 bazel2gn 时，您可能需要将 ":__pkg__", 显式添加到 BUILD.bazel 文件中的 visibility，即使 Bazel 不需要这样做。

    • 添加此类条目时，请添加引用 bazel2gn 的注释，以便在移除 GN 目标时移除这些条目。

为每个目标使用适当的公开范围

每个目标的 visibility 应尽可能限定在较小的范围内。

请勿使用公开可见性 ("//visibility:public") [SHAC 错误]。对于真正要在整个代码库中使用的非常常见的目标，"//:__subpackages__" 是合适的字符串。不过，最好指定几个顶级目录（例如 ["//sdk/lib:__subpackages__", "//src:__subpackages__"]）。

酌情使用 __pkg__ 和 __subpackages__。

如果需要软件包或私有可见性，请省略 visibility 属性，因为这是默认设置。

非明显定位类型的可见性

config_setting() 和 exports_files() 与任何其他目标一样支持可见性，但默认情况下它们是公开的。即使 Bazel 不需要，也请始终为这些文件指定 visibility。

target_compatible_with

主机目标

主机目标（例如主机工具、主机测试和仅限主机的库）应指定 target_compatible_with = HOST_OS_CONSTRAINTS（从 //build/bazel/platforms:constraints.bzl 加载）。这会将兼容性限制为主机操作系统，而与 CPU 架构无关，从而使开发者能够交叉编译工具，并且对于 IDK 中的主机工具及其依赖项来说是必需的。

除非在极少数情况下由 Build 团队使用，否则不应使用 @platforms//host:constraints.bzl 中的 HOST_CONSTRAINTS。