常見樣式和最佳做法

總覽

下列樣式和最佳做法適用於 Fuchsia 中的所有 Bazel 檔案。

本頁面是 Bazel 樣式指南和最佳做法的一部分，其中包含特定情境的其他指引。

來源檔案和依附元件清單的區域變數

雖然官方指南不建議使用依附元件變數，但 Fuchsia 允許使用這些變數，以便管理大型共用來源檔案或依附元件清單。請判斷清單是否大致相似，或只是有幾個共同項目。

不扣除：絕不從清單變數中移除項目。

請勿使用 glob()

請勿使用 glob() [SHAC error]。請改為明確列出檔案。

fx build 會透過 Ninja 動作執行 Bazel，而 Ninja 只會追蹤 glob() 上次執行時比對的檔案。如果您新增了 glob() 現在會比對的檔案，Ninja 不會注意到。漸進式建構作業和 fx test 執行作業會繼續使用舊檔案清單。明確列出檔案時，新增檔案表示編輯 BUILD.bazel 檔案，而 Ninja 會追蹤這類檔案。

這項規則僅適用於 Fuchsia。官方 Bazel 樣式指南允許非遞迴 glob，且一旦 Bazel 不再在 Ninja 內執行，可能就會再次允許。

glob() 的現有用途會列在執行檢查的每個存放區根目錄中的 build/bazel/shac/glob_allowlist.json (例如 //build/bazel/shac/glob_allowlist.json 和 //vendor/google/build/bazel/shac/glob_allowlist.json)。未經建構團隊核准，請勿新增項目。系統不會檢查 third_party/ 目錄下的上游程式碼。

請勿使用遞迴 glob

無論是否涉及 Ninja，都不應在任何 Bazel 程式碼中使用遞迴 glob (**)。官方 Bazel 樣式指南禁止來源檔案的遞迴 glob。這類工具會略過含有專屬 BUILD.bazel 檔案的子目錄，因此很難判斷哪些檔案符合條件。此外，與每個目錄中的 BUILD.bazel 檔案相比，快取和平行處理效果也較差。

唯一的例外狀況是第三方資料庫和其他存放區 (例如 //vendor/... 存放區) 的特定情況，在這些情況下，列出每個路徑並不實際。在 third_party/ 目錄以外，這些仍需要加入許可清單。

瀏覽權限

以下是一般指南，適用於 BUILD.bazel 和 .bzl 檔案。各項目的頁面會提供更具體的詳細資料。

盡可能在 BUILD.bazel 和 .bzl 檔案中指定瀏覽權限

唯一支援該屬性且不需指定的情況，是套件 (目錄) 專屬的巨集。

請勿使用公開瀏覽權限

請勿在 bazel_sdk/ 目錄外使用公開瀏覽權限 ("//visibility:public" 或 visibility("public"))。只有在外部存放區使用程式碼時，才適合採用這個存取層級，但不適用於 fuchsia.git 中的非 SDK 程式碼。

瀏覽權限應盡可能縮小範圍，同時允許測試和反向依附元件存取

可見度應僅限於需要和/或應允許使用的目標。保守但務實。舉例來說，如果目標用於 //src 的五個直接子目錄中，建議使用 //src:__subpackages__，以免在新增用途時需要修改可見度。不過，舉例來說，如果目標只能由驅動程式使用，請將其限制為實作驅動程式的套件。

針對常見的非簡單瀏覽權限定義，使用套件群組

如果多個目標的 visibility 應限制為同一組標籤，建議使用 package_group 表示該組標籤。與目標搭配使用時，package_group 也支援負可視度，但與載入可視度搭配使用時則不支援。

請勿混用 SDK 和平台符號及目標

平台目標 (即 AIB 或 IDK 中的所有內容) 不得使用 Fuchsia Bazel SDK 中定義的符號、該 SDK 提供的目標，或使用該 SDK 建構的目標。

反之亦然，使用 Fuchsia Bazel SDK 建構的目標不應依附於平台目標，也不應從平台 .bzl 檔案載入符號。

請勿使用 Fuchsia Bazel SDK 路徑

平台程式碼不應存取包含 bazel_sdk 的檔案路徑，或 Fuchsia Bazel SDK 存放區路徑，例如：

  • @fuchsia_sdk//

  • @internal_sdk//

  • @rules_fuchsia//fuchsia

唯一允許的路徑開頭為 @fuchsia_rules_common/，但只有建構團隊可以直接使用這些路徑。

平台程式碼也應避免使用 bazel_sdk/ 路徑，除非是與 Fuchsia Bazel SDK 共用實作的特定建構規則。

目標和 .bzl 檔案的標籤

參照目標

參照目標時 (例如在 deps 中)，只要不使用禁止的標籤模式，即可使用以下列任何一項開頭的標籤：

從 .bzl 檔案載入

Fuchsia 平台的大多數一般用途巨集和規則，都可以在 //build/bazel/rules/ 中找到。

只要不使用禁止的標籤模式，即可安全地從標籤開頭為下列內容的 .bzl 檔案中 load()：

下列項目也允許使用，但可能只有建構團隊的開發人員會使用：

  • @fuchsia_build_config//:defs.bzl

  • @fuchsia_build_info//:args.bzl

  • @fuchsia_rules_common//

禁止的標籤模式

請勿使用 [SHAC error]：

  • 工作區根套件標籤 (開頭為 //:)

    • 在非常特殊且罕見的情況下，才需要這麼做 (請參閱問題 560343570)，但一般來說，這項操作應只由建構團隊執行。

  • 套件名稱 (即標籤中冒號 (:) 後方的部分) 含有斜線 (/) 的標籤。

    • 整合第三方程式庫時，極少數情況下可能會有例外。

fuchsia_... 檔案和符號位於 Fuchsia Bazel SDK 中

請避免定義名稱開頭為 fuchsia_ 的檔案、巨集和規則。名稱開頭為 fuchsia_ 的現有例項可能屬於 Fuchsia Bazel SDK (請參閱「請勿使用 Fuchsia Bazel SDK 路徑」)，避免使用這類名稱有助於維持區隔。

如需區分 Fuchsia 平台與一般 Bazel 識別碼時使用的模式，請參閱「包裝內建和常見規則、巨集和函式」。

使用 Fuchsia 專屬包裝函式

如果存在 Fuchsia 專屬包裝函式，請使用這些包裝函式，而非外部存放區、巨集等。這有助於確保 Fuchsia 建構設定套用一致。

具體來說，以下語言有包裝函式：

  • C/C++：請使用 //build/bazel/rules/cc/... 中的 fx_cc_...()，而非 @rules_cc// 中的 cc_...。

  • Rust：使用 //build/bazel/rules/rust/... 的 rustc_...()，而非 @rules_rust// 的 rust_...。

Fuchsia 沒有下列語言的包裝函式。請從下列路徑載入，確保一致性：

  • Go：@io_bazel_rules_go//go...

  • Python：@rules_python//python...

字串

字串請使用雙引號，但請避免逸出

根據預設，字串會使用雙引號。不過，如果列印雙引號更合適，且這樣做會涉及逸出雙引號 (\")，請使用單引號來避免逸出。