本页面介绍了 Bazel 的两种可见性系统:目标可见性和加载可见性。
这两种可见性都有助于其他开发者区分库的公共 API 及其实现细节,并且有助于在工作区增大时强制实施结构。您还可以在弃用公共 API 时使用可见性功能,以允许当前用户同时拒绝新用户。
目标公开范围
目标公开范围用于控制哪些人员可能依赖于您的目标,即哪些人可在 deps
等属性中使用您的目标的标签。
如果目标 B
位于同一个软件包中,或者如果 A
向 B
的软件包授予了可见性,则目标 A
对其可见。因此,软件包是决定是否允许访问的粒度单位。如果 B
依赖于 A
,但 A
对 B
不可见,则任何尝试构建 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
属性的值(如果已设置);否则目标
BUILD
文件中的package
语句的default_visibility
参数的值(如果存在此类声明);否则//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
用于为这些目标启用可见性检查。为了协助迁移,这也会导致任何未指定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
文件加载 .bzl
文件。
与目标可见性可以保护由目标封装的源代码一样,加载可见性可以保护由 .bzl
文件封装的构建逻辑。例如,BUILD
文件作者可能希望将一些重复的目标定义分解为 .bzl
文件的宏。如果无法确保加载可见性,他们可能会发现同一工作区中的其他协作者重复使用了自己的宏,因此修改该宏会破坏其他团队的构建。
请注意,.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()
的文件始终可以从工作区中的任意位置加载。最好将 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
当用户从名为 internal
或 private
的目录中加载文件时,Buildifier lint 会在用户的文件本身不在该目录的父级下时发出警告。此 lint 早于加载可见性功能,在 .bzl
文件声明可见性的工作区中,此 lint 不是必需的。