建置檔案

先前各節說明套件、目標和標籤,以及建構依附元件圖表。本節說明用於定義套件的具體語法。

根據定義,每個套件都包含 BUILD 檔案,這是很簡短的程式。系統會使用命令式語言 Starlark 評估 BUILD 檔案。

系統會將這些文字解讀為一份連續的陳述清單。

一般而言,順序非常重要:例如,您必須先定義變數才能使用變數。不過,大部分的 BUILD 檔案僅包含建構規則的宣告,且這些陳述式的相對順序並不重要;所有重要的都是在時間套件評估完成後宣告的規則以及含有哪些值的值。

執行建構規則函式 (例如 cc_library) 時,會在圖表中建立新的目標。您之後可以使用標籤參照這個目標。

在簡單的 BUILD 檔案中,您可以自由調整規則宣告順序,不必變更行為。

為鼓勵程式碼與資料分開,BUILD 檔案不能包含函式定義、for 陳述式或 if 陳述式 (但可以列出理解和 if 運算式)。您可以改為在 .bzl 檔案中宣告函式。此外,BUILD 檔案不允許使用 *args**kwargs 引數,請改為明確列出所有引數。

至關重要的一點是,Starlark 中的程式無法執行任何 I/O。這個非變化版本讓 BUILD 檔案的解譯,僅依賴已知的輸入組合,這是確保建構可重現性的關鍵。詳情請參閱密封度

BUILD 檔案應只使用 ASCII 字元編寫,但嚴格來說,系統會使用 Latin-1 字元集解讀。

由於 BUILD 檔案在基礎程式碼的依附元件變更時都必須更新,因此通常由多個團隊人員維護。BUILD 檔案作者應自由加上註解,記錄每個建構目標的角色 (無論是否為公開使用),並記錄套件本身的角色。

正在載入擴充功能

Bazel 副檔名是結尾為 .bzl 的檔案。使用 load 陳述式從擴充功能匯入符號。

load("//foo/bar:file.bzl", "some_library")

這個程式碼會載入 foo/bar/file.bzl 檔案,並將 some_library 符號新增至環境。可用於載入新規則、函式或常數 (例如字串或清單)。您可以使用其他引數對 load 呼叫來匯入多個符號。引數必須是字串常值 (無變數),且 load 陳述式必須顯示在頂層,不得放在函式主體中。

load 的第一個引數是識別 .bzl 檔案的標籤。如果是相對標籤,則會與包含目前 bzl 檔案的套件 (而非目錄) 達成解析。load 陳述式中的相對標籤應在開頭使用 :

load 也支援別名,因此您可以為匯入的符號指派不同的名稱。

load("//foo/bar:file.bzl", library_alias = "some_library")

您可以在一個 load 陳述式中定義多個別名。此外,引數清單可包含別名和一般符號名稱。以下範例完全合法 (請注意使用引號的時機)。

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

開頭為 _ 的符號在 .bzl 檔案中不會匯出,也無法從其他檔案載入。

您可以使用載入瀏覽權限,限制能載入 .bzl 檔案的人員。

建構規則類型

大多數的建構規則都屬於系列產品,並按照語言分組。舉例來說,cc_binarycc_librarycc_test 分別是 C++ 二進位檔、程式庫和測試的建構規則。其他語言則使用相同的命名配置,前置字串不同,例如為 Java 使用 java_*。其中部分函式列載於建構百科全書中,但任何人都能建立新的規則。

  • *_binary 規則會以指定語言建構可執行程式。建構後,執行檔會位於建構工具的二進位輸出樹狀結構中,位於規則標籤的對應名稱,因此 //my:program 會顯示在 $(BINDIR)/my/program (例如) 處。

    在某些語言中,這類規則也會建立執行檔案目錄,其中包含規則中 data 屬性提及的所有檔案,或依附元件傳輸過程中的任何規則。這組檔案會集中聚在一起,以便輕鬆部署至實際工作環境。

  • *_test 規則是 *_binary 規則的特殊認證,用於自動化測試。測試只是在成功時傳回零的計畫。

    與二進位檔一樣,測試也會執行檔案樹狀結構,而且只有測試可能在執行階段合法開啟的檔案。舉例來說,程式 cc_test(name='x', data=['//foo:bar']) 在執行期間可能會開啟並讀取 $TEST_SRCDIR/workspace/foo/bar。(每個程式設計語言都有用來存取 $TEST_SRCDIR 值的專屬公用程式函式,但全都相當於直接使用環境變數。)未能觀察到規則會導致在遠端測試主機上執行測試失敗。

  • *_library 規則會以指定的程式設計語言指定個別編譯的模組。程式庫可以依附其他程式庫,而二進位檔和測試可能會依附於程式庫,具有預期的獨立編譯行為。

標籤 依附元件