.bzl 樣式指南

本頁涵蓋 Starlark 基本樣式規範，巨集和規則的相關資訊

Starlark 是定義軟體的建構方式，因此以及設定語言

您將使用 Starlark 編寫 BUILD 檔案、巨集和建構規則。巨集和規則基本上就是一種中繼語言，用來定義 BUILD 檔案的編寫方式。 BUILD 檔案的設計重點在於簡單重複。

所有軟體的讀取頻率都高於寫入的頻率。這對客戶來說尤其重要 Starlark，當工程師讀取 BUILD 檔案以瞭解其依附元件的依附元件時目標和建構作業的細節這種讀數通常發生在通過有時也能同時完成其他工作因此簡單性和可讀性至關重要快速理解 BUILD 檔案。

使用者開啟 BUILD 檔案時，會希望快速知道自己在檔案；或查看該 C++ 程式庫的來源清單。或移除與該 Java 二進位檔的依附元件每次新增一層抽象化層時讓使用者難以執行上述工作

此外，許多不同的工具也會分析及更新 BUILD 個檔案。工具可能無法可以編輯使用抽象的 BUILD 檔案。已啟用「BUILD」檔案可讓您輕鬆取得更出色的工具隨著程式碼集不斷擴增更頻繁地變更許多 BUILD 檔案，更新程式庫或執行清理作業

通用建議

使用建構工具轉換成格式化器和 Linter
按照測試規範操作。

樣式

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 介面。宣告和文件供應器只要使用來自這些領域的小型資料集訓練即可
設計規則時，請務必將擴充性納入考量。提醒您，其他規則想要與您的規則互動、存取您的供應商，並且重複使用您的規則您建立的動作
請遵循規則中的效能指南。