定義 Bazel 規則、巨集和函式

總覽

本頁面包含 Fuchsia 專屬樣式,以及編寫規則、巨集和函式的最佳做法。這些一律定義在 .bzl 檔案中,相關指南也適用於此。此外,BUILD.bazel 檔案中與目標相關的指南,也適用於規則和巨集定義的目標。

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

評估新巨集和函式是否合適

如同 Bazel 樣式指南,Fuchsia 偏好 DAMP (描述性和有意義的詞組) BUILD 檔案,而非 DRY (不要重複)。

具體來說,Fuchsia 建構作業在 Bazel 中使用特定區域巨集和函式的頻率,遠低於在 GN 中使用這類範本的頻率。

如果必須同步處理某些項目 (例如常見依附元件),請使用共用的靜態清單,而非編寫區域專屬巨集。

雖然區域專屬範本可在初始建立目標時減少輸入內容,但會造成維護和遷移問題,尤其是自動化工具,因為個別目標會被區域專屬巨集隱藏。如果您認為使用特定區域的巨集和函式,能大幅提升效率,請諮詢建構團隊 (根據過往經驗,這項標準很高)。

盡可能使用現有的巨集和規則

這類巨集或規則的潛在用途越廣,這項工作就越重要。

特別是如果您的需求僅限於下列情況,請考慮是否可以使用現有的巨集和/或規則來完成:

  • 生成中繼資料

  • 強制執行屬性值

  • 例如,盡量減少呼叫端必須指定的屬性數量

特別是在前兩種情況下,請考慮 Bazel 查詢、SHAC 規則、測試或其他機制是否能滿足您的需求。Bazel 查詢可在依附元件樹狀結構或目錄樹狀結構中定義的所有目標上執行。你能寫出執行查詢並檢查結果的測試嗎?如果您的用途需要額外屬性,建議使用標記。

使用現有規則和巨集的原因包括:

  • 更容易理解,開發人員可更快上手

    • 熟悉 Bazel 的開發人員可以立即瞭解目標。

    • 團隊中某部分的開發人員可以瞭解程式碼集中其他部分的目標。

  • AI 較能理解並產生使用常見規則和巨集的 Bazel 檔案

  • load() 陳述式數量過多

    • 內建 ID 不需要任何載入陳述式。

    • 其他目標可能已載入其他目標。

  • 減少錯誤

    • 舉例來說,只有在切面周遊所有相關目標時,才能正常運作。自訂巨集或規則可能會引入不會遵循的路徑。請參閱「使用標準屬性名稱」。

建議使用符號巨集,而非舊版巨集

建議您編寫符號巨集 (使用 macro() 定義),而非舊版巨集 (使用 def 定義的 Python 函式,用於建立目標)。符號巨集可提供更清楚的屬性及其類型說明文件、對屬性執行類型檢查,並確保在呼叫網站評估標籤。此外,也支援屬性繼承 (透過 inherit_attrs)。如需進一步瞭解,請參閱「為什麼不應使用舊版巨集」。

請勿在符號巨集的實作函式中指定引數的預設值,因為預設值是由 attrs 項目定義,且每個屬性都會提供值。

在某些情況下,您必須在符號巨集周圍使用舊版巨集包裝函式,但對大多數開發人員來說,這種情況應該非常罕見。

巨集內定義目標的瀏覽權限和存取權檢查

總覽

就可見度而言,舊版巨集就像是在例項化的位置內嵌展開。在 BUILD.bazel 檔案中使用時,舊版巨集定義的目標實際上是在該檔案中定義。因此:

  • 定義目標的預設 visibility 與例項化套件相同,包括指定的套件 default_visibility。

  • 巨集可以使用 (例如新增至 deps) 例項化套件可見的任何目標。

    • 定義舊版巨集的 .bzl 檔案位置並不重要。

不過,為了提高瀏覽權限,請將符號巨集定義的目標視為定義在與定義巨集的 .bzl 檔案相同套件 (目錄) 的 BUILD.bazel 檔案中。因此:

  • 定義目標的預設 visibility 是包含 .bzl 檔案的套件 (目錄)。

  • 巨集可以使用 (例如新增至 deps) 包含 .bzl 檔案的套件 (目錄) 可見的任何目標。

    • 舉例來說,這項功能適用於 fidl_library() 新增的 FIDL 繫結支援程式庫。

    • 但對於 HLCPP 支援程式庫許可清單等項目,這會造成問題。

    • 詳情請參閱問題 446911800。

為巨集中定義的目標指定瀏覽權限

公開目標

將傳遞至巨集的 visibility 屬性轉送至巨集定義的主要目標,也就是 name 傳遞至的目標。visibility 屬性也可能視情況轉送至巨集 doc 字串中提及的其他已定義公開目標。

私人目標

在符號巨集中,所有其他定義目標的可見度預設為 ["//visibility:private"]。不過,如果是舊版巨集,您必須為舊版巨集定義的所有目標指定可見度。

為舊版巨集定義的所有目標指定瀏覽權限

針對所有未使用傳遞至巨集的 visibility 屬性的目標,指定 visibility = ["//visibility:private"]。這是為了避免 在指定 時,預設為套件的 default_visibility。

使用標準屬性名稱

在巨集和規則中使用標準屬性名稱。例如,使用 "deps"、"data",甚至是 "tools",而不是 "images" 或 "scripts"。請參閱一些一般適用的屬性。

可能原因如下:

  • 為了提高可讀性,以及其他類似於「盡可能使用現有的巨集和規則」中的原因。

  • 只有在遍歷所有相關目標時,Aspect 才能正常運作,而巨集通常會設定為套用至 "deps" 和其他常見屬性 (視情況而定)。不過,他們可能不知道 "rust_deps" 等屬性,如果未套用至該屬性,可能會排除與該面向相關的目標。

需要具名引數

公開函式和舊版巨集 (一種特殊函式) 通常應宣告僅限關鍵字的引數 (所有引數都在 *, 後宣告)。如果函式最多只有幾個引數,且引數可從符號名稱中清楚辨識,且引數不會誤用在錯誤的位置 (包括因重構/重新排序),則可例外。布林引數和具有預設值的引數應一律顯示在 * 之後。

雖然這對要由程式碼集其他部分使用的符號最重要,但也適用於所有 .bzl 檔案中的公開符號。

這有助於強制執行 Bazel .bzl 風格指南的指引:「呼叫巨集時,請僅使用關鍵字引數。這與規則一致,且能大幅提升可讀性。

宣告巨集使用的所有引數

如果巨集 (選擇性) 使用引數,請在巨集實作的參數清單中明確宣告該引數,而不是從 kwargs 擷取。舉例來說,請避免以下做法:

# Do NOT do this:
testonly = kwargs.get("testonly", False),

宣告引數可更清楚瞭解哪些引數與巨集實作相關 (例如與其呼叫的巨集相比),並提供單一位置查看預設值。如果是舊版巨集,這項規則也會確保引數有記錄。(這主要與 Fuchsia Bazel SDK 相關)。

與任何其他引數一樣,但特別是所有建構規則通用的屬性和所有測試規則通用的屬性 (_test),您必須確保將引數傳遞至所有支援的巨集和規則,因為這些不會在 **kwargs 中。

符號巨集中的可設定屬性

在符號巨集中,屬性預設為可設定,也就是說,呼叫端可以傳遞 select() 運算式。在選用屬性上,省略或 None 引數會解析為屬性的預設值 (將 None 傳遞至 mandatory = True 屬性會視為省略並失敗)。對於可設定的屬性,Bazel 會自動將每個非 None 解析值 (包括非 None 預設值,例如 False、"" 或 []) 包裝成 select() (SelectorList),然後再傳遞至巨集的 implementation 函式 (而不可設定的屬性,例如 configurable = False、attr.output() 和 attr.output_list(),則會接收具體值)。只有預設值為 None - attr.label() (沒有預設值或 default = None) 的可設定屬性,以及透過 inherit_attrs 繼承的非強制屬性 (其預設值會覆寫為 None,除非在 attrs 中覆寫為非 None 預設值),在省略或傳遞 None 時,會以 None 的形式傳遞 (而傳遞 select({"//conditions:default": None}) 則會傳遞 SelectorList)。

由於 select() 值在 Starlark 中一律為 truthy,與具體值不相等 (例如 attr == [] 一律為 False),且無法疊代、索引、格式化或置於清單或字典常值中,因此請勿對可設定屬性或 select() 值執行需要具體值的作業 [SHAC 錯誤]:

  • 布林值評估:請勿使用 if attr:、not attr、attr or default 或 bool(attr)。使用 attr == None 或 attr != None 檢查是否省略或傳遞 None 預設的可設定屬性 (attr.label() 沒有非 None 預設或非強制繼承屬性)。None。對於預設值非 None 的可設定屬性 (例如 attr.bool()、attr.string() 或 attr.string_list()),Bazel 會將預設值包裝在 select() 中,因此 attr == None 一律為 False。

  • 容器常值和疊代:請勿將可設定屬性放在清單、元組或字典常值 (例如 [attr] 或 {"key": attr}) 中、對其進行疊代 (for x in attr),或將其傳遞至序列函式 (len(attr)、list(attr))。請使用 + 串連清單,並使用 | 合併字典。

  • 值比較、字串格式設定和方法呼叫:請勿將可設定屬性與非 None 值 (attr == "foo") 進行比較、設定其格式 ("%s" % attr 或 "{}".format(attr))、呼叫其方法,或將其傳遞至不可設定屬性 (例如 name、tags、testonly 或 visibility)。

如果巨集實作必須檢查、格式化、疊代或分支屬性值,或將其傳遞至不可設定的屬性,請在 attrs 中使用 configurable = False 宣告屬性。

留言

  • 為所有公開函式 (不以底線開頭的函式) 提供函式層級註解。

  • 為所有規則和巨集提供 doc 字串。

  • 為所有規則和巨集屬性提供 doc 字串。

    • 如果私有屬性 (以底線開頭) 的含義可從 default 值中清楚推導,則可省略 doc 字串。

文件字串

  • 在 Fuchsia 平台中,doc 字串應在來源檔案中讀取,而不是在產生的說明文件中讀取。因此,請優先針對這點進行最佳化,而非著重於產生的說明文件外觀。

  • 長 doc 字串:

    • 建議您在合理的情況下,將頂層單句說明完全寫在與 doc= 相同的行中。

    • Bazel 並未嚴格限制行長度。

    • 如需多行,請使用三引號撰寫多行字串。

    • 避免附加一般字串。

  • 多行 doc 字串

    • 在與 doc 引數 (doc = """Begin the comment...) 相同的行上開始多行字串。

    • 後續各行則從 doc 中 d 的下方開始,類似於 Python 註解從第一個 " 下方開始下一行。

    • 這項做法可確保一致性和可讀性,但可能不適合用於生成的文字。

    • 多行字串結尾應使用三引號 ("""),並與 doc 對齊。

規則和巨集實作函式名稱

如要為 rule() 和 macro() 執行個體命名 implementation 函式,請在開頭加上底線,接著輸入規則或函式名稱,並以 _impl 結尾。

在巨集中參照目標名稱時使用變數

如果巨集定義了目標,然後在另一個目標中依附該目標,請使用前一個目標的名稱定義變數,並將該變數用於其 name 屬性和後一個目標的 deps。

這可明確連結兩個目標,尤其是在複雜的情況下,有多個層級的目標名稱是以其他目標名稱為基礎,且更容易醒目顯示及搜尋。

除非能提高可讀性 (例如在同一個位置定義所有目標名稱),否則請勿對內部未使用的目標使用變數。

包裝內建和常見規則、巨集和函式

編寫巨集來取代 Fuchsia 平台程式碼集中的常見 Bazel 規則、巨集或函式時,請在包裝名稱前加上 fx_。例如,請使用 fx_cc_library(),而非 cc_library()。「Common」包含 Bazel 內建的符號 (包括 native.*),以及 rules_cc 等常見存放區中的符號。這個前置字元也適用於其他衝突,例如與 package 無關的 fx_package()。請勿使用 fuchsia_ 前置字元,因為 fuchsia_... 檔案和符號位於 Fuchsia Bazel SDK。

新增 C/C++ 或 Rust 包裝函式巨集或規則時,請參閱 //build/bazel/rules/cc/README.md 或 //build/bazel/rules/rust/README.md,瞭解如何更新 bazel_fuchsia_wrappers SHAC 檢查和相關說明文件。

避免設定轉換

Fuchsia 平台目標應已在正確的設定中建構。如果您認為需要轉換,通常其實不需要。請與建構團隊聯絡,只有建構團隊才能新增轉換或新平台。

將工具做為可執行的標籤屬性傳遞

執行工具的規則應將其視為 attr.label(executable = True, cfg = "exec"),並使用 ctx.executable 讀取。

反面模式

  • 正在透過 PATH 查詢工具。Infra 沙箱不會設定這項功能,而 Bazel 無法追蹤未知的工具。請改為將工具做為可執行的標籤屬性傳遞。

  • 傳遞 JSON 或 dict blob,將標籤嵌入規則或巨集。Bazel 只會查看標籤類型屬性中的標籤,因此不會建構或追蹤這些依附元件。請改用標籤屬性和供應器。

  • 透過 bazel-bin 符號連結尋找建構輸出內容。它會指向一個設定,而轉換作業可以將您想要的輸出內容放入不同的 bazel-out 目錄。透過供應商傳遞輸出內容,或明確回報其路徑。

  • 依賴上游規則集的實作詳細資料,例如 rules_cc 使用的 _solib_ 目錄前置字元。規則集更新時,這些規則會變更,恕不另行通知。

避免快取或遠端處理大型構件

請參閱「避免快取大型構件」。