本頁面說明 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
應僅用於衍生由巨集定義的目標名稱,而不適用於其他項目。舉例來說,請勿使用名稱衍生出並非由巨集本身產生的依附元件或輸入檔案。- 在巨集中建立的所有目標都應以某種方式與主要目標結合。
- 請保持巨集中的參數名稱一致。如果將參數做為屬性值傳遞至主要目標,請使用相同的名稱。如果巨集參數的用途與一般規則屬性 (例如
deps
) 相同,請使用屬性的名稱 (請參閱下文)。 - 呼叫巨集時,請只使用關鍵字引數。這與規則一致,可大幅提高可讀性。
不論規則是在原生程式碼的 Bazel 或 Starlark 中定義,當相關規則的 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
:編譯不需要的執行階段依附元件。
- 針對具有非明顯行為的屬性 (例如具有特殊替代行為的字串範本,或是依特定要求叫用的工具),請在屬性的宣告 (
attr.label_list()
或類似) 中使用doc
關鍵字引數來提供說明文件。 - 規則實作函式在絕大部分都是私人函式 (以底線命名)。常見的樣式是將
myrule
的實作函式命名為_myrule_impl
。 - 使用明確定義的 provider 介面,在規則之間傳遞資訊。宣告和文件提供者欄位。
- 設計規則時,請考量擴充性。請考慮其他規則可能會想與您的規則互動、存取提供者,並重複使用您建立的動作。
- 遵守規則中的成效指南。