BUILD.bazel 文件

概览

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

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

公开范围

避免使用软件包 default_visibility

最好为必须在软件包外部访问的每个目标指定公开范围，而不是声明软件包 default_visibility。一般来说，在目标定义中指定公开范围时，BUILD.bazel 文件更容易理解。此外，使用 default_visibility 意味着私有目标默认具有一定程度的公开范围。

只有在 BUILD.bazel 文件中的每个目标（无论是现在还是将来）都应具有相同的公开范围时，才应使用 default_visibility。这意味着 BUILD.bazel 文件中没有定义私有帮助程序目标。例如，当定义了许多 widget 并且它们都需要对另一个软件包（目录）中的 widget 加载器或 widget 测试可见时，可能会出现这种情况。

请勿对 //visibility:public 和其他广泛的公开范围（例如 //:__subpackages__ 或 //src:__subpackages__）使用 default_visibility 。

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

目标公开范围

概览

在 Bazel 中：

  • 公开范围位于软件包（目录）级别。无法将公开范围限制为同一软件包或另一个软件包中的特定目标。

    • 如果需要这样做，请考虑将目标重构到子目录中，这些子目录可以单独引用。

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

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

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

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

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

对于熟悉 GN 的用户

  • Bazel 目标默认是私有的，而在 GN 中，它们默认是公开的。

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

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

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

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

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

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

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

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

每个目标的 visibility 都应尽可能缩小范围。

请勿使用公开范围 ("//visibility:public")。对于真正打算 在整个代码库中使用的非常常见的目标，"//:__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 中的主机工具及其依赖项是必需的。

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