可见性

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

本页介绍了 Bazel 的三种可见性系统： 目标可见性、 传递可见性和 加载可见性。

这些类型的可见性有助于其他开发者区分库的公共 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"],
)

配置设置可见性

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

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

  • --incompatible_config_setting_private_default_visibility 会导致未指定 config_setting 的 visibility 遵循 软件包的 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 文件的软件包）。 但是，对于在符号宏中创建的目标，位置是包含宏定义（my_macro = macro(...) 语句）的 .bzl 文件的软件包。当在多个嵌套目标中创建目标时，始终使用最内层符号宏的定义。

系统使用相同的方式来确定要针对给定依赖项的可见性检查哪个位置。如果使用方目标是在宏内创建的，我们会查看最内层宏的定义，而不是使用方目标所在的软件包。

这意味着，在同一软件包中定义代码的所有宏都会自动成为彼此的“好友”。无论宏实际在哪个软件包中实例化，从 //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() 的旧版宏也无法看到此类目标。

传递可见性

传递可见性 是一种限制哪些用户可以依赖于目标的方式，包括当依赖项仅是间接依赖项时。它与普通目标可见性系统分开应用，因此即使依赖项链中的每个链接都有效，也可能会发生传递可见性错误。这样，目标作者就可以与一组可信的客户端目标共享该目标，同时防止无意中将其泄露给构建的其余部分。

传递可见性在软件包级别声明，使用 [package][package] 函数的 transitive_visibility 参数。此声明适用于软件包中的所有目标。该参数采用 package_group 的单个标签，该标签指定其目标可以传递依赖于此软件包的目标的软件包。

# //third_party/sensitive_dep/BUILD
package(
    # This must be explicitly listed
    transitive_visibility = [":sensitive_dep_users"]
)

package_group(
    name = "sensitive_dep_users",
    packages = [
        "//third_party/sensitive_dep/...", # has to include itself
        "//allowed",
    ],
)

sh_library(
    name = "sensitive_dep"
)

# //not_allowed/BUILD
sh_binary(
    name = "bad",
    deps = ["//third_party/sensitive_dep:sensitive_dep"]
)

构建依赖于 //third_party/sensitive_dep:sensitive_dep 但不属于其 transitive_visibility 的 //not_allowed:bad 会导致以下错误：

Transitive visibility error: //third_party/sensitive_dep:sensitive_dep is not transitively visible from ///not_allowed:bad. //"//third_party/sensitive_dep:sensitive_dep inherits a transitive_visibility declaration from its package or one of its dependencies that does not allow //not_allowed:bad.

transitive_visibility 中使用的软件包组不得 include 其他软件包组。

请注意，如果目标具有传递可见性限制的传递依赖项，则该目标本身会继承该限制，并将其传递给依赖于它的目标。如果目标具有多个具有传递可见性限制的传递依赖项，则必须满足所有限制。

传递可见性也适用于在符号宏中声明的目标。但是，与普通目标可见性不同，它仅考虑这些目标所在的软件包，而不考虑定义符号宏的软件包。

加载可见性

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

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

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

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

加载可见性自 Bazel 6.0 起可用。

声明加载可见性

如需设置 .bzl 文件的加载可见性，请从该文件中调用 visibility() 函数。visibility() 的实参是软件包规范列表，就像 packages 的 package_group 属性一样。但是，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 文件可能需要对由多个较小的许可名单组成的许可名单可见。这类似于 a 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 文件声明可见性的工作区中是不必要的。