.bzl 樣式指南

7.3 · 7.2 · 7.1 · 7.0 · 6.5

本頁面說明 Starlark 的基本樣式規範，並提供巨集和規則相關資訊。

Starlark 是一種定義軟體建構方式的語言，因此同時也是一種程式設計和設定語言。

您將使用 Starlark 編寫 BUILD 檔案、巨集和建構規則。巨集和規則基本上是元語言，用於定義 BUILD 檔案的寫入方式。BUILD 檔案應簡單且重複。

所有軟體的讀取次數都高於寫入次數。這對 Starlark 尤其適用，因為工程師會讀取 BUILD 檔案，瞭解目標的依附元件和建構的詳細資料。這種情況通常會在匆忙中、趕時間時，或在完成其他工作時發生。因此，簡單易讀非常重要，這樣使用者才能快速剖析及瞭解 BUILD 檔案。

使用者開啟 BUILD 檔案時，希望能快速瞭解檔案中的目標清單；或查看該 C++ 程式庫的來源清單；或從該 Java 二進位檔中移除依附元件。每次新增抽象層，都會讓使用者更難執行這些工作。

BUILD 檔案也會由許多不同的工具進行分析和更新。如果 BUILD 檔案使用抽象項目，工具可能無法編輯該檔案。簡化 BUILD 檔案可讓您取得更優質的工具。隨著程式碼集的成長，您需要越來越頻繁地變更許多 BUILD 檔案，才能更新程式庫或進行清理作業。

通用建議

樣式

Python 樣式

如有疑問，請盡可能遵循 PEP 8 樣式指南。具體來說，為遵守 Python 慣例，請使用四而非兩個空格進行縮排。

由於 Starlark 並非 Python，因此 Python 樣式的某些部分不適用。舉例來說，PEP 8 建議使用 is 比較單例，但 is 並非 Starlark 中的運算子。

Docstring

使用 docstrings 記錄檔案和函式。 請在每個 .bzl 檔案頂端使用 docstring，為每個公開函式使用 docstring。

文件規則和層面

請使用 doc 引數記錄規則和條件及其屬性，以及提供者及其欄位。

命名慣例

  • 變數和函式名稱使用小寫字詞，並以底線 ([a-z][a-z0-9_]*) 分隔字詞，例如 cc_library。
  • 頂層私有值會以一個底線開頭。Bazel 會強制執行私人值不得從其他檔案使用。本機變數不應使用底線前置字元。

文行長度

如同 BUILD 檔案，標籤可以很長，因此沒有嚴格的行長限制。盡可能讓每行最多使用 79 個字元 (遵循 Python 的樣式指南 PEP 8)。請勿嚴格強制執行這項規範：編輯器應顯示超過 80 個資料欄，自動化變更通常會使用較長的行，且使用者不應花費時間分割已可讀取的行。

關鍵字引數

在關鍵字引數中，建議在等號兩側加上空格：

def fct(name, srcs):
    filtered_srcs = my_filter(source = srcs)
    native.cc_library(
        name = name,
        srcs = filtered_srcs,
        testonly = True,
    )

布林值

如要使用布林值 (例如在規則中使用布林屬性)，請優先使用 True 和 False 值 (而非 1 和 0)。

請勿在正式版程式碼中使用 print() 函式，因為這項函式僅供偵錯使用，且會向 .bzl 檔案的所有直接和間接使用者傳送垃圾郵件。唯一例外狀況是，如果 print() 預設為停用，且只能透過編輯來源啟用，您可以提交使用 print() 的程式碼。舉例來說，如果 print() 的所有用途都受到 if DEBUG: 保護，而 DEBUG 已硬編為 False，請注意，這些陳述是否足夠實用，以便評估其對可讀性的影響。

巨集

巨集是在載入階段將一或多項規則執行個體化的函式。一般來說，請盡量使用規則，而非巨集。使用者看到的建構圖與 Bazel 在建構期間使用的圖不同，因為宏會在 Bazel 進行任何建構圖分析前擴充。

因此在發生問題時，使用者必須瞭解巨集的導入方式，才能排解建構問題。此外，bazel query 結果可能難以解讀，因為結果中顯示的目標來自巨集展開。最後，Aspects 無法辨識巨集，因此依賴 Aspects 的工具 (IDE 和其他工具) 可能會失敗。

巨集的安全用途是定義其他目標，供直接在 Bazel CLI 或 BUILD 檔案中直接參照：在此情況下，只有這些目標的「使用者」需要知道這些目標，而巨集引起的建構問題也遠離使用方法。

如果是定義已產生目標的巨集 (這不應在 CLI 中參照巨集的實作詳細資料，或仰賴不由該巨集例項化的目標依附)，請按照下列最佳做法操作：

  • 巨集應使用 name 引數，並使用該名稱定義目標。該目標會成為該巨集的主要目標。
  • 產生的目標 (也就是巨集定義的所有其他目標) 應符合下列條件：
    • 名稱前方加上 <name> 或 _<name>。例如使用 name = '%s_bar' % (name)。
    • 曝光度受限 (//visibility:private)，且
    • 使用 manual 標記，避免在萬用字元目標 (:all、...、:* 等) 中展開。
  • name 應僅用於衍生由巨集定義的目標名稱，而不適用於其他項目。舉例來說，請勿使用名稱來衍生非由巨集本身產生的依附元件或輸入檔案。
  • 在巨集中建立的所有目標都應以某種方式與主要目標配對。
  • 依慣例，定義巨集時，name 應為第一個引數。
  • 請保持巨集中的參數名稱一致。如果將參數做為屬性值傳遞至主要目標，請使用相同的名稱。如果巨集參數的用途與一般規則屬性 (例如 deps) 相同，請使用屬性的名稱 (請參閱下文)。
  • 呼叫巨集時，只能使用關鍵字引數。這與規則一致，可大幅提高可讀性。

無論是使用原生程式碼還是 Starlark 在 Bazel 中定義規則，如果相關規則的 Starlark API 不足以滿足特定用途，工程師通常會編寫巨集。如果您遇到這個問題，請詢問規則作者是否能擴充 API 來達成您的目標。

一般來說，巨集越貼近規則，效果越好。

另請參閱巨集。

規則

  • 規則、層面和相關屬性應使用小寫名稱 (「蛇形大小寫」)。
  • 規則名稱是名詞，可從依附元件的角度 (或葉規則的使用者) 說明規則產生的成果類型。這不一定是檔案後置字串。舉例來說，產生 C++ 構件 (用於做為 Python 擴充功能) 的規則可能會稱為 py_extension。對於大多數語言，常見的規則包括：
    • *_library - 編譯單元或「模組」。
    • *_binary：產生可執行檔或部署單位的目標。
    • *_test - 測試目標。這可能包括多項測試。*_test 目標中的所有測試都應為同一主題的變化版本，例如測試單一程式庫。
    • *_import：封裝預先編譯的構件 (例如 .jar) 或編譯期間使用的 .dll 的目標。
  • 請使用一致的屬性名稱和類型。一些普遍適用的屬性包括：
    • srcs：label_list，允許檔案：來源檔案，通常由人編寫。
    • deps：label_list，通常不允許檔案：編譯依附元件。
    • data：label_list，允許檔案：資料檔案，例如測試資料等。
    • runtime_deps：label_list：編譯不需要的執行階段依附元件。
  • 如果屬性具有不明顯的行為 (例如含有特殊替換字串範本，或會在特定需求下叫用的工具)，請使用 doc 關鍵字引數，為屬性宣告 (attr.label_list() 或類似項目) 提供說明文件。
  • 規則實作函式幾乎一律應為私人函式 (名稱開頭為底線)。常見的風格是為 myrule 的實作函式命名為 _myrule_impl。
  • 使用明確定義的提供者介面，在規則之間傳遞資訊。宣告並記錄提供者欄位。
  • 設計規則時，請考量擴充性。請考量其他規則可能會想與您的規則互動、存取您的供應工具，以及重複使用您建立的動作。
  • 遵守規則中的成效指南。