.bzl 檔案樣式指南和最佳做法

總覽

Fuchsia 專案遵循官方 Bazel .bzl 樣式指南，但有幾項例外情況。本頁的指南是常見的 Bazel 樣式指南和最佳做法的補充說明。

.bzl 檔案最常用於定義規則、巨集和函式，這方面有額外的指引。

本頁是 Bazel 樣式指南和最佳做法的一部分。

瀏覽權限

載入瀏覽權限

與 .gni 檔案不同，.bzl 檔案支援載入瀏覽權限，可限制載入來源。根據預設，系統不會設下任何限制。

請務必在 .bzl 檔案中指定 visibility：

• 如果 .bzl 檔案並非專為在套件外部使用而設計，請使用 visibility("private")。

  • 如果套件包含公開和私有 .bzl 檔案，建議將私有檔案放在 private/ 目錄中。Bazel 具有相關機制，可限制載入這類目錄中的檔案。

• 否則，請使用 visibility([...]) 指定可能使用該項目的套件 (目錄)。

載入 visibility 使用的語法與目標 visibility 不同：

• 路徑等同於 :__pkg__。

• /... 遵循的路徑等同於 :__subpackages__。

對於真正要在整個程式碼集使用的常見目標，可以使用 "//..."。請勿使用公開可見度 (visibility("public"))。不過在多數情況下，一組頂層和/或第二層目錄 (例如 "//src/..." 和 "//sdk/lib/...") 就已足夠。

符號顯示設定

在 .bzl 檔案中，請在符號名稱加上底線前置字元，限制只能在 .bzl 檔案內存取，防止其他檔案使用 (即使位於相同套件 (目錄) 內)。

請勿建立 defs.bzl 檔案

雖然您可能會看到這些符號 (尤其是在第三方存放區中)，但定義或匯出不確定會一起使用的多個符號 (通常是 defs.bzl 檔案中的情況) 是一種反模式。請參閱「限制每個 .bzl 檔案匯出的符號」。無論如何，請選擇更具描述性的檔案名稱。