常見的 Bazel 樣式指南和最佳做法

總覽

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

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

來源檔案和依附元件清單的本機變數

雖然官方指南不建議使用依附元件變數，但 Fuchsia 允許使用這類變數，以便管理大型共用來源檔案或依附元件清單。請考慮清單是否實質相似，或只是共用幾個常見項目。

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

瀏覽權限

以下是一般準則，適用於 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 中定義的符號、其提供的目標，或使用其建構的目標。

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

請勿使用 Fuchsia Bazel SDK 路徑

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

  • @fuchsia_sdk//

  • @internal_sdk//

  • @rules_fuchsia//fuchsia

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

平台程式碼也應避免使用 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]：

  • Workspace 根套件標籤 (以 //: 開頭的標籤)

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

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

    • 整合第三方程式庫的例外情況很少。

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

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

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

使用 Fuchsia 專屬包裝函式

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

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

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

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

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

  • 前往：@io_bazel_rules_go//go...

  • Python：@rules_python//python...

字串

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

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