显示设置

本页面介绍了 Bazel 的两个可见性系统:目标可见性加载可见性

这两种可见性都有助于其他开发者区分库的公共 API 及其实现细节,并有助于在工作区增大时强制执行结构。在弃用公共 API 时,您还可以使用可见性,以允许当前用户同时拒绝新用户。

目标公开范围

目标可见性控制哪些人可能会依赖于您的目标,即哪些人可在 deps 等属性中使用您的目标的标签。

如果目标 B 位于同一个软件包中,或者如果 AB 的软件包授予了可见性,则目标 A 对其可见。因此,软件包是决定是否允许访问的粒度单位。如果 B 依赖于 A,但 AB 不可见,则在分析期间,任何构建 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 属性中重复列出相应的列表。这可以提高可读性,并防止列表不同步。

规则目标的可见性

规则目标的公开范围为:

  1. visibility 属性的值(如果已设置);否则

  2. 目标的 BUILD 文件中的 package 语句的 default_visibility 参数的值(如果存在此类声明);或者

  3. //visibility:private.

最佳实践:避免将 default_visibility 设为公开。对于原型设计或在小型代码库中,这样做可能会很方便,但随着代码库不断扩大,无意中创建公共目标的风险也会增加。最好明确说明哪些目标是软件包的公共接口的一部分。

示例

文件 //frobber/bin/BUILD

# This target is visible to everyone
cc_binary(
    name = "executable",
    visibility = ["//visibility:public"],
    deps = [":library"],
)

# This target is visible only to targets declared in the same package
cc_library(
    name = "library",
    # No visibility -- defaults to private since no
    # package(default_visibility = ...) was used.
)

# This target is visible to targets in package //object and //noun
cc_library(
    name = "subject",
    visibility = [
        "//noun:__pkg__",
        "//object:__pkg__",
    ],
)

# See package group "//frobber:friends" (below) for who can
# access this target.
cc_library(
    name = "thingy",
    visibility = ["//frobber:friends"],
)

文件 //frobber/BUILD

# This is the package group declaration to which target
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
    name = "friends",
    packages = [
        "//fribber/...",
        "//frobber",
    ],
)

生成的文件目标的公开范围

生成的文件目标与生成它的规则目标具有相同的公开范围。

源文件目标可见性

您可以通过调用 exports_files 明确设置源文件目标的可见性。如果没有将任何 visibility 参数传递给 exports_files,会将可见性设为公开。exports_files 不能用于覆盖所生成文件的可见性。

对于 exports_files 调用中未显示的源文件目标,可见性取决于 --incompatible_no_implicit_file_export 标志的值:

  • 如果设置了此标志,则公开范围为私有。

  • 否则,旧版行为适用:公开范围与 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 并未强制要求 select() 的键中引用的 config_setting 目标的可见性。可使用两个标志移除此旧版行为:

  • --incompatible_enforce_config_setting_visibility:用于为这些目标启用可见性检查。为协助迁移,这还会导致任何未指定 visibilityconfig_setting 被视为公开(无论软件包级 default_visibility 如何)。

  • --incompatible_config_setting_private_default_visibility 会导致未指定 visibilityconfig_setting 遵循软件包的 default_visibility 并在私有可见性上回退,就像任何其他规则目标一样。如果未设置 --incompatible_enforce_config_setting_visibility,则该参数为空操作。

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

软件包组目标可见性

package_group 目标没有 visibility 属性。它们始终公开显示。

隐式依赖项的可见性

某些规则具有隐式依赖项 - 这些依赖项未在 BUILD 文件中列出,但该规则的每个实例都存在。例如,cc_library 规则可能会根据每条规则针对表示 C++ 编译器的可执行目标创建隐式依赖项。

目前,出于可见性目的,系统对待这些隐式依赖项的方式与处理任何其他依赖项的方式相同。这意味着所依赖的目标(例如我们的 C++ 编译器)必须对规则的每个实例可见。在实践中,这通常意味着目标必须公开。

您可以通过设置 --incompatible_visibility_private_attributes_at_definition 来更改此行为。启用后,相关目标只需对声明它为隐式依赖项的规则可见。也就是说,它必须对包含定义了规则的 .bzl 文件的软件包可见。在我们的示例中,C++ 编译器可能是专用编译器,只要它与 cc_library 规则的定义位于同一软件包中即可。

加载可见性

加载可见性用于控制是否可以从其他 BUILD.bzl 文件加载 .bzl 文件。

目标可见性可以保护由目标封装的源代码,同样,负载可见性也可以保护由 .bzl 文件封装的构建逻辑。例如,BUILD 文件作者可能希望将一些重复的目标定义分解为 .bzl 文件的宏。如果不保护加载可见性,他们可能会发现同一工作区中的其他协作者重复使用了自己的宏,因此修改宏会破坏其他团队的构建。

请注意,.bzl 文件不一定有相应的源文件目标。如果存在重叠,无法保证加载可见性与目标可见性完全相同。也就是说,同一个 BUILD 文件或许能够加载 .bzl 文件,但不能将其列在 filegroupsrcs 中,反之亦然。这有时会导致希望将 .bzl 文件用作源代码的规则出现问题,例如用于生成或测试文档。

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

加载可见性从 Bazel 6.0 开始提供。

声明加载可见性

如需设置 .bzl 文件的加载可见性,请在该文件中调用 visibility() 函数。visibility() 的参数是软件包规范列表,就像 package_grouppackages 属性一样。不过,visibility() 不接受否定软件包规范。

visibility() 的调用只能对每个文件执行一次,该调用必须在顶级(而不是在函数内),最好紧跟在 load() 语句之后。

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

示例

# //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 构建程序 lint

当用户从名为 internalprivate 的目录加载文件时,当用户的文件本身不在该目录的父级之下时,Buildifier lint 会发出警告。此 lint 早于加载可见性功能,在 .bzl 文件声明可见性的工作区中是不必要的。