顯示設定

本頁面將介紹 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 屬性中重複列出清單。這樣可提高可讀性，並避免清單脫離同步。

最佳做法：當您要授予其他團隊專案的瀏覽權限時，請優先使用 __subpackages__ 而非 __pkg__，以免在專案演進及新增子包時，發生不必要的瀏覽權限流失。

規則目標可見度

規則目標的瀏覽權限如下：

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_library 目標中，而不是在 .java 檔案上呼叫 exports_files。一般來說，規則目標應只直接參照位於同一個套件中的來源檔案。

範例

檔案 //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() 的檔案一律可從工作區的任何位置載入。建議您在任何新 .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 建構工具 Lint

當使用者從名為 internal 或 private 的目錄載入檔案時，如果使用者的檔案本身並未位於該目錄的父項下方，就會出現 Buildifier lint 提供的警告。這項 Lint 會在載入可見度功能之前執行，因此在 .bzl 檔案宣告可見度的工作區中，這項 Lint 就沒有必要。