本頁面說明 Bazel 的兩種瀏覽權限系統:目標瀏覽權限和負載瀏覽權限。
這兩種可見度設定都能協助其他開發人員區分您的程式庫公開 API 和實作詳細資料,並在您的工作區擴大時協助強制執行結構。淘汰公用 API 時,您也可以使用瀏覽權限,在拒絕新使用者時允許現有使用者。
指定可視度
目標對象瀏覽權限可控管哪些使用者可能會依附目標對象,也就是哪些使用者可能會在 deps
等屬性中使用目標對象的標籤。
如果目標 A
和目標 B
位於同一個套件中,或是 A
授予 B
套件的可見度,A
就會對 B
顯示。因此,套件是決定是否允許存取權的精細單位。如果 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
屬性中重複列出清單。這樣可提高可讀性,並避免清單脫離同步。
規則目標瀏覽權限
規則目標的瀏覽權限如下:
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
目標檢查該依附元件。
如要變更這項行為,請停用 --incompatible_visibility_private_attributes_at_definition
。停用後,系統會將隱含依附元件視為其他依附元件。也就是說,每個規則的例項都必須能看到所依附的目標 (例如 C++ 編譯器)。實際上,這通常表示目標必須具有公開瀏覽權限。
如果您想將規則的使用權限限制在特定套件,請改用載入可見度。
載入瀏覽權限
載入可見度可控制是否可從其他 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()
的檔案一律可從工作區的任何位置載入。建議您在任何新 .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
檔案宣告可見度的工作區中,這項 Lint 就沒有必要。