本頁涵蓋 Starlark 基本樣式規範, 巨集和規則的相關資訊
Starlark 是 定義軟體的建構方式,因此 以及設定語言
您將使用 Starlark 編寫 BUILD
檔案、巨集和建構規則。巨集和
規則基本上就是一種中繼語言,用來定義 BUILD
檔案的編寫方式。
BUILD
檔案的設計重點在於簡單重複。
所有軟體的讀取頻率都高於寫入的頻率。這對客戶來說尤其重要
Starlark,當工程師讀取 BUILD
檔案以瞭解其依附元件的依附元件時
目標和建構作業的細節這種讀數通常發生在通過
有時也能同時完成其他工作因此
簡單性和可讀性至關重要
快速理解 BUILD
檔案。
使用者開啟 BUILD
檔案時,會希望快速知道自己在
檔案;或查看該 C++ 程式庫的來源清單。或移除
與該 Java 二進位檔的依附元件每次新增一層抽象化層時
讓使用者難以執行上述工作
此外,許多不同的工具也會分析及更新 BUILD
個檔案。工具可能無法
可以編輯使用抽象的 BUILD
檔案。已啟用「BUILD
」
檔案可讓您輕鬆取得更出色的工具隨著程式碼集不斷擴增
更頻繁地變更許多 BUILD
檔案,
更新程式庫或執行清理作業
通用建議
樣式
Python 樣式
如有疑問,請遵循 PEP 8 格式指南。 請特別使用 4 個空格 (而不是兩個空格) 進行縮排,以遵循 Python 的命名慣例
開始時間
Starlark 不是 Python,
Python 樣式的某些部分並不適用。舉例來說,PEP 8 建議
比較與單例模式時,可以使用 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()
會受 if DEBUG:
保護,其中 DEBUG
的硬式編碼為
False
。請留意這些陳述是否實用,足以證明回覆內容的合理性
對可讀性的影響
巨集
巨集是在載入期間將一或多項規則執行個體化的函式 事實上,Gartner 的資料顯示 只有一半的企業機器學習專案通過前測階段一般來說,請盡可能使用規則,而不要使用巨集。建構作業 使用者看到的圖表與 Bazel 在測試期間使用的圖表不同 建構 - 巨集會在 Bazel 執行任何建構圖形分析之前展開。
因此發生問題時
巨集的實作,以排解建構問題。此外,bazel
query
的結果可能難以解讀,因為結果中顯示的目標會
來自巨集展開。最後,任何部分都不會偵測到巨集,因此使用工具
某些切面 (IDE 和其他項目) 可能會失敗。
巨集的一種用法是,定義其他目標 可在 Bazel CLI 或 BUILD 檔案中直接參照:在這種情況下, 使用者需要瞭解這些目標對象,以及任何建構問題 巨集所佔的比例與用法之間有落差
用於定義所產生目標的巨集 (巨集的實作詳情) 這些物件不應在 CLI 參照,或取決於目標 沒有由該巨集例項化),請遵循以下最佳做法:
- 巨集應使用
name
引數,並使用該名稱定義目標。 該目標就會成為該巨集的主要目標。 - 產生的目標 (也就是巨集定義的所有其他目標) 應符合下列條件:
- 名稱前方加上
<name>
或_<name>
。舉例來說,使用name = '%s_bar' % (name)
。 - 瀏覽權限受到限制 (
//visibility:private
),且 - 設定
manual
標記,避免萬用字元目標 (:all
、...
、:*
等)。
- 名稱前方加上
name
只能用來衍生由 巨集,對其他設定的影響。例如,請勿使用 並非由巨集本身產生的依附元件或輸入檔案。- 您在巨集中建立的所有目標,都應以某種方式 主要目標。
- 原則上,定義巨集時應優先使用
name
。 - 巨集中的參數名稱必須一致。如果傳遞參數
做為主要目標的屬性值,請使用相同的名稱。如果巨集
參數的用途與一般規則屬性相同,例如
deps
,名稱為屬性的名稱 (如下所示)。 - 呼叫巨集時,只能使用關鍵字引數。這與 也能大幅改善可讀性
當 Starlark API 相關規則的 沒有限制,不論規則 可在原生程式碼的 Bazel 中 或 Starlark 內定義面對這個 問題,詢問規則作者是否能擴充 API 來達成您的 但縝密健全的倫理程序 也有助於達到產品開發目標
原則上,與規則相似的巨集越多越好。
另請參閱巨集。
規則
- 規則、切面及其屬性應使用小寫名稱 (「蛇」) 大小寫)。
- 規則名稱是用來描述
而對於分葉規則來說
使用者)。不一定是檔案後置字串。例如,有一項規則
產生用於在 Python 擴充功能可能被呼叫的 C++ 構件
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
。 - 使用定義明確的規則,在規則之間傳遞資訊 provider 介面。宣告和文件供應器 只要使用來自這些領域的 小型資料集訓練即可
- 設計規則時,請務必將擴充性納入考量。提醒您,其他規則 想要與您的規則互動、存取您的供應商,並且重複使用您的規則 您建立的動作
- 請遵循規則中的效能指南。