可见性

本页介绍了 Bazel 的两个可见性系统：目标可见性和加载可见性。

这两种可见性有助于其他开发者区分库的公共 API 和实现详情，并有助于在工作区不断扩大的情况下强制执行结构。您还可以在弃用公共 API 时使用可见性，以允许当前用户使用该 API，同时拒绝新用户使用。

目标可见性

目标可见性用于控制哪些人可以依赖您的目标，也就是说，哪些人可以在属性（例如 deps）中使用目标的标签。如果目标违反了其某个依赖项的公开范围，则在分析阶段将无法构建。

一般来说，如果目标 A 与目标 B 位于同一位置，或者 A 授予了对 B 位置的查看权限，则 A 对 B 可见。如果没有符号宏，“位置”一词可以简化为“软件包”；如需详细了解符号宏，请参阅下文。

通过列出允许的软件包来指定可见性。允许某个软件包并不一定意味着也允许其子软件包。如需详细了解软件包和子软件包，请参阅概念和术语。

对于原型设计，您可以通过设置标志 --check_visibility=false 来停用目标可访问性强制执行。在提交的代码中，不应在生产环境中使用此方法。

控制可见性的主要方法是使用规则的 visibility 属性。 以下各子部分介绍了该属性的格式、如何将其应用于各种目标，以及可见性系统与符号宏之间的互动。

公开范围规范

所有规则目标都具有 visibility 属性，该属性接受标签列表。每个标签都具有以下形式之一。除了最后一种形式之外，这些都只是语法占位符，不对应于任何实际目标。

• "//visibility:public"：授予对所有软件包的访问权限。

• "//visibility:private"：不授予任何额外的访问权限；只有此位置信息软件包中的目标可以使用此目标。

• "//foo/bar:__pkg__"：授予对 //foo/bar（但不是其子软件包）的访问权限。

• "//foo/bar:__subpackages__"：授予对 //foo/bar 及其所有直接和间接子软件包的访问权限。

• "//some_pkg:my_package_group"：授予对给定 package_group 中所有软件包的访问权限。

  • 软件包组使用不同的语法来指定软件包。在软件包组中，形式 "//foo/bar:__pkg__" 和 "//foo/bar:__subpackages__" 分别替换为 "//foo/bar" 和 "//foo/bar/..."。同样，"//visibility:public" 和 "//visibility:private" 只是 "public" 和 "private"。

例如，如果 //some/package:mytarget 的 visibility 设置为 [":__subpackages__", "//tests:__pkg__"]，则 //some/package/... 源树中的任何目标以及在 //tests/BUILD 中声明的目标都可以使用它，但 //tests/integration/BUILD 中定义的目标不能使用它。

最佳实践：为了让同一组软件包看到多个目标，请使用 package_group，而不是在每个目标的 visibility 属性中重复该列表。这样可以提高可读性，并防止列表不同步。

最佳实践：在向其他团队的项目授予查看权限时，请优先选择 __subpackages__ 而不是 __pkg__，以避免因该项目不断发展并添加新的子软件包而导致不必要的查看权限变动。

规则目标公开范围

规则目标的可见性由其 visibility 属性（如果没有，则使用合适的默认值）以及声明目标的位置确定。对于未在符号宏中声明的目标，如果软件包指定了 default_visibility，则使用此默认值；对于所有其他软件包以及在符号宏中声明的目标，默认值仅为 ["//visibility:private"]。

# //mypkg/BUILD

package(default_visibility = ["//friend:__pkg__"])

cc_library(
    name = "t1",
    ...
    # No visibility explicitly specified.
    # Effective visibility is ["//friend:__pkg__", "//mypkg:__pkg__"].
    # If no default_visibility were given in package(...), the visibility would
    # instead default to ["//visibility:private"], and the effective visibility
    # would be ["//mypkg:__pkg__"].
)

cc_library(
    name = "t2",
    ...
    visibility = [":clients"],
    # Effective visibility is ["//mypkg:clients, "//mypkg:__pkg__"], which will
    # expand to ["//another_friend:__subpackages__", "//mypkg:__pkg__"].
)

cc_library(
    name = "t3",
    ...
    visibility = ["//visibility:private"],
    # Effective visibility is ["//mypkg:__pkg__"]
)

package_group(
    name = "clients",
    packages = ["//another_friend/..."],
)

最佳实践：避免将 default_visibility 设置为公开。这对于原型设计或小型代码库可能很方便，但随着代码库的增长，意外创建公开目标的风险也会增加。最好明确指出哪些目标是软件包公共接口的一部分。

生成文件的目标公开范围

生成的文件的目标与生成它的规则目标具有相同的可见性。

# //mypkg/BUILD

java_binary(
    name = "foo",
    ...
    visibility = ["//friend:__pkg__"],
)

# //friend/BUILD

some_rule(
    name = "bar",
    deps = [
        # Allowed directly by visibility of foo.
        "//mypkg:foo",
        # Also allowed. The java_binary's "_deploy.jar" implicit output file
        # target the same visibility as the rule target itself.
        "//mypkg:foo_deploy.jar",
    ]
    ...
)

源文件目标公开范围

可以使用 exports_files 显式声明源文件目标，也可以通过在规则的标签属性（在符号宏之外）中引用其文件名来隐式创建源文件目标。与规则目标一样，对 exports_files 的调用位置或引用输入文件的 BUILD 文件始终会自动附加到文件的可见性中。

通过 exports_files 声明的文件可以通过该函数的 visibility 参数设置其可见性。如果未提供此参数，则公开范围为“公开”。

对于未在对 exports_files 的调用中显示的文件，其可见性取决于标志 --incompatible_no_implicit_file_export 的值：

• 如果标志为 true，则公开范围为“私享”。

• 否则，应用旧版行为：公开范围与 BUILD 文件的 default_visibility 相同；如果未指定默认公开范围，则为私享。

避免依赖旧版行为。只要源文件目标需要非私密的可视性，就始终写入 exports_files 声明。

最佳实践：尽可能优先公开规则目标，而不是源文件。例如，不要对 .java 文件调用 exports_files，而是将该文件封装在非私有的 java_library 目标中。一般来说，规则目标应仅直接引用位于同一软件包中的源文件。

示例

文件 //frobber/data/BUILD：

exports_files(["readme.txt"])

文件 //frobber/bin/BUILD：

cc_binary(
  name = "my-program",
  data = ["//frobber/data:readme.txt"],
)

配置设置可见性

过去，对于在 select() 的键中引用的 config_setting 目标，Bazel 不会强制执行可见性。有两个标志可用于移除此旧版行为：

• --incompatible_enforce_config_setting_visibility 可针对这些目标启用可见性检查。为了帮助进行迁移，它还会导致任何未指定 visibility 的 config_setting 被视为公开（无论软件包级 default_visibility 如何）。

• --incompatible_config_setting_private_default_visibility 会导致未指定 visibility 的 config_setting 遵循软件包的 default_visibility 并回退到私有可见性，就像任何其他规则目标一样。如果未设置 --incompatible_enforce_config_setting_visibility，则此方法不执行任何操作。

避免依赖旧版行为。如果软件包尚未指定合适的 default_visibility，则任何打算在当前软件包之外使用的 config_setting 都应具有明确的 visibility。

软件包组目标可见性

package_group 目标缺少 visibility 属性。它们始终公开显示。

隐式依赖项的可见性

有些规则具有隐式依赖项，即未在 BUILD 文件中明确列出，但对于该规则的每个实例而言都是固有的依赖项。例如，cc_library 规则可能会从其每个规则目标创建到表示 C++ 编译器的可执行目标的隐式依赖项。

系统会根据包含 .bzl 文件（其中定义了规则或方面）的软件包来检查此类隐式依赖项的公开范围。在我们的示例中，只要 C++ 编译器与 cc_library 规则的定义位于同一软件包中，就可以是私有的。作为后备方案，如果从定义中看不到隐式依赖项，则会针对 cc_library 目标进行检查。

如果您想将规则的使用限制为仅限某些软件包，请改用加载可见性。

可见性和符号宏

本部分介绍了可见性系统如何与符号宏互动。

符号宏中的位置

可见性系统的一个关键细节是我们如何确定声明的位置。对于未在符号宏中声明的目标，位置只是目标所在的软件包（即 BUILD 文件的软件包）。但对于在符号宏中创建的目标，位置是包含 .bzl 文件的软件包，该文件包含宏的定义（my_macro = macro(...) 语句）。如果目标是在多个嵌套目标内创建的，则始终使用最内层符号宏的定义。

该系统还用于确定要检查哪些位置才能确定给定依赖项的可见性。如果使用方目标是在宏内创建的，我们会查看最内层宏的定义，而不是使用方目标所在的软件包。

这意味着，在同一软件包中定义的所有宏都会自动成为彼此的“好友”。由 //lib:defs.bzl 中定义的宏直接创建的任何目标都可以从 //lib 中定义的任何其他宏中看到，无论这些宏实际实例化在哪些软件包中。同样，它们可以查看直接在 //lib/BUILD 及其旧版宏中声明的目标，也可以被这些目标查看。相反，如果至少有一个目标是由符号宏创建的，那么位于同一软件包中的目标不一定能看到彼此。

在符号宏的实现函数中，visibility 形参的有效值是宏的 visibility 属性在附加调用宏的位置后的值。宏将其某个目标导出到调用方的标准方式是将此值转发到目标的声明，如 some_rule(..., visibility = visibility) 中所示。如果目标省略此属性，则宏的调用者将无法看到这些目标，除非调用者恰好与宏定义位于同一软件包中。这种行为是组合式的，也就是说，对子宏的一系列嵌套调用可以各自传递 visibility = visibility，从而在每个级别将内部宏的导出目标重新导出到调用方，而不会暴露任何宏的实现细节。

将权限委托给子宏

此可见性模型具有一项特殊功能，可让宏将其权限委托给子宏。这对于分解和组合宏非常重要。

假设您有一个宏 my_macro，它使用来自另一个软件包的规则 some_library 创建依赖关系边：

# //macro/defs.bzl
load("//lib:defs.bzl", "some_library")

def _impl(name, visibility, ...):
    ...
    native.genrule(
        name = name + "_dependency"
        ...
    )
    some_library(
        name = name + "_consumer",
        deps = [name + "_dependency"],
        ...
    )

my_macro = macro(implementation = _impl, ...)

# //pkg/BUILD

load("//macro:defs.bzl", "my_macro")

my_macro(name = "foo", ...)

//pkg:foo_dependency 目标没有指定 visibility，因此仅在 //macro 中可见，这对于使用目标来说没有问题。现在，如果 //lib 的作者将 some_library 重构为使用宏来实现，会发生什么情况？

# //lib:defs.bzl

def _impl(name, visibility, deps, ...):
    some_rule(
        # Main target, exported.
        name = name,
        visibility = visibility,
        deps = deps,
        ...)

some_library = macro(implementation = _impl, ...)

进行此更改后，//pkg:foo_consumer 的位置现在是 //lib 而不是 //macro，因此它对 //pkg:foo_dependency 的使用违反了依赖项的可见性。不能要求 my_macro 的作者为了解决此实现细节问题而将 visibility = ["//lib"] 传递给依赖项的声明。

因此，当目标的依赖项也是声明该目标的宏的属性值时，我们会根据宏的位置（而不是使用目标的位置）检查依赖项的可见性。

在此示例中，为了验证 //pkg:foo_consumer 是否能看到 //pkg:foo_dependency，我们发现 //pkg:foo_dependency 也作为输入传递给了 my_macro 内对 some_library 的调用，因此我们改为根据此调用的位置 //macro 检查依赖项的可见性。

只要目标或宏声明位于另一个符号宏内，并且该符号宏在其某个标签类型属性中采用依赖项的标签，此过程就可以递归重复。

最终确定者

在规则最终确定器（带有 finalizer = True 的符号宏）中声明的目标，除了遵循通常的符号宏可见性规则看到目标之外，还可以查看对最终确定器目标的软件包可见的所有目标。

换句话说，如果您将基于 native.existing_rules() 的旧版宏迁移到终结器，则由终结器声明的目标仍将能够看到其旧依赖项。

可以定义终结器可以使用 native.existing_rules() 内省的目标，但这些目标在可见性系统下不能用作依赖项。例如，如果宏定义的目标对其自己的软件包或最终确定器宏的定义不可见，并且未委托给最终确定器，则最终确定器无法看到此类目标。不过请注意，基于 native.existing_rules() 的旧版宏也无法看到此类目标。

加载可见性

加载可见性用于控制是否可以从当前软件包之外的其他 BUILD 或 .bzl 文件加载 .bzl 文件。

与目标可见性保护由目标封装的源代码的方式类似，加载可见性保护由 .bzl 文件封装的 build 逻辑。例如，BUILD 文件作者可能希望将一些重复的目标声明分解为 .bzl 文件中的宏。如果没有负载可见性保护，他们可能会发现自己的宏被同一工作区中的其他协作者重复使用，从而导致修改宏会破坏其他团队的 build。

请注意，.bzl 文件可能具有也可能不具有对应的源文件目标。 如果确实如此，则无法保证负载可见性和目标可见性一致。也就是说，同一个 BUILD 文件可能能够加载 .bzl 文件，但无法在 filegroup 的 srcs 中列出该文件，反之亦然。这有时会给希望将 .bzl 文件作为源代码使用的规则（例如用于生成文档或进行测试）带来问题。

对于原型设计，您可以通过设置 --check_bzl_visibility=false 来停用加载可见性强制执行。与 --check_visibility=false 一样，不应针对已提交的代码执行此操作。

自 Bazel 6.0 起，即可使用加载可见性。

声明加载可见性

如需设置 .bzl 文件的加载公开范围，请从该文件内调用 visibility() 函数。visibility() 的实参是一个软件包规范列表，与 package_group 的 packages 属性一样。不过，visibility() 不接受负的软件包规范。

对 visibility() 的调用必须仅在每个文件中发生一次，位于顶层（不在函数内），最好紧跟在 load() 语句之后。

与目标公开范围不同，默认加载公开范围始终为公开。不调用 visibility() 的文件始终可以从工作区中的任何位置加载。最好在任何并非专门用于在软件包外部使用的新 .bzl 文件的顶部添加 visibility("private")。

示例

# //mylib/internal_defs.bzl

# Available to subpackages and to mylib's tests.
visibility(["//mylib/...", "//tests/mylib/..."])

def helper(...):
    ...

# //mylib/rules.bzl

load(":internal_defs.bzl", "helper")
# Set visibility explicitly, even though public is the default.
# Note the [] can be omitted when there's only one entry.
visibility("public")

myrule = rule(
    ...
)

# //someclient/BUILD

load("//mylib:rules.bzl", "myrule")          # ok
load("//mylib:internal_defs.bzl", "helper")  # error

...

加载可见性实践

本部分介绍有关管理负载可见性声明的提示。

公开范围的因式分解

如果多个 .bzl 文件应具有相同的可见性，则将它们的软件包规范纳入一个通用列表会很有帮助。例如：

# //mylib/internal_defs.bzl

visibility("private")

clients = [
    "//foo",
    "//bar/baz/...",
    ...
]

# //mylib/feature_A.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

# //mylib/feature_B.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

这有助于防止各种 .bzl 文件的可见性出现意外偏差。当 clients 列表较大时，此方法也更易于阅读。

组合公开范围

有时，.bzl 文件可能需要对由多个较小的许可名单组成的许可名单可见。这类似于 package_group 如何通过其 includes 属性来纳入其他 package_group。

假设您要弃用一个广泛使用的宏。您希望它仅对现有用户和您自己团队拥有的软件包可见。您可以这样写：

# //mylib/macros.bzl

load(":internal_defs.bzl", "our_packages")
load("//some_big_client:defs.bzl", "their_remaining_uses")

# List concatenation. Duplicates are fine.
visibility(our_packages + their_remaining_uses)

使用软件包组进行去重

与目标可见性不同，您无法以 package_group 的形式定义加载可见性。如果您想针对目标可见性和加载可见性重复使用同一许可名单，最好将软件包规范列表移至 .bzl 文件中，以便两种声明都可以引用该列表。在上面的分解可见性示例的基础上，您可以编写以下代码：

# //mylib/BUILD

load(":internal_defs", "clients")

package_group(
    name = "my_pkg_grp",
    packages = clients,
)

仅当列表不包含任何负软件包规范时，此方法才有效。

保护单个符号

名称以下划线开头的任何 Starlark 符号都无法从其他文件加载。这样一来，您就可以轻松创建私密符号，但无法与一组有限的可信文件共享这些符号。另一方面，加载可见性可让您控制其他软件包可以看到哪些 .bzl file，但不允许您阻止加载任何非下划线符号。

幸运的是，您可以结合使用这两项功能，从而实现精细控制。

# //mylib/internal_defs.bzl

# Can't be public, because internal_helper shouldn't be exposed to the world.
visibility("private")

# Can't be underscore-prefixed, because this is
# needed by other .bzl files in mylib.
def internal_helper(...):
    ...

def public_util(...):
    ...

# //mylib/defs.bzl

load(":internal_defs", "internal_helper", _public_util="public_util")
visibility("public")

# internal_helper, as a loaded symbol, is available for use in this file but
# can't be imported by clients who load this file.
...

# Re-export public_util from this file by assigning it to a global variable.
# We needed to import it under a different name ("_public_util") in order for
# this assignment to be legal.
public_util = _public_util

bzl-visibility Buildifier lint

如果用户从名为 internal 或 private 的目录加载文件，但用户的文件本身不在该目录的父目录下，则 Buildifier lint 会发出警告。此 lint 早于加载可见性功能，在 .bzl 文件声明可见性的工作区中是不必要的。