前幾節以抽象方式說明套件、目標和標籤,以及建構依附元件圖表。本節說明用於定義套件的具體語法。
根據定義,每個套件都包含 BUILD
檔案,這是一個簡短的程式。
系統會使用命令式語言 Starlark 來評估 BUILD
檔案。
系統會將這些項目解讀為一連串的陳述式。
一般來說,順序很重要:變數必須先定義,才能使用。不過,大多數 BUILD
檔案只包含建構規則的宣告,這些陳述式的相對順序並不重要;重要的是,在套件評估完成時,系統會宣告哪些規則,以及這些規則的值。
執行建構規則函式 (例如 cc_library
) 時,會在圖表中建立新目標。這個目標日後可透過標籤參照。
在簡單的 BUILD
檔案中,您可以自由重新排序規則宣告,而不會影響行為。
為鼓勵程式碼和資料之間的明確分隔,BUILD
檔案不得包含函式定義、for
陳述式或 if
陳述式 (但允許清單理解和 if
運算式)。您可改為在 .bzl
檔案中宣告函式。此外,BUILD
檔案不允許使用 *args
和 **kwargs
引數,請改為明確列出所有引數。
至關重要的一點是,Starlark 中的程式無法任意執行 I/O。這個不變量可讓 BUILD
檔案的解讀作業保持密封,只依賴一組已知的輸入內容,這對於確保可重現建構作業至關重要。詳情請參閱「Hermeticity」一文。
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_binary
、cc_library
和 cc_test
分別是 C++ 二進位檔、程式庫和測試的建構規則。其他語言使用相同的命名慣例,但前置字串不同,例如 Java 的 java_*
。Build Encyclopedia 中記錄了部分這些函式,但任何人都可以建立新規則。
*_binary
規則會使用特定語言建構可執行的程式。建構完成後,可執行檔會位於建構工具的二進位輸出樹狀結構中,並使用規則標籤的對應名稱,因此//my:program
會顯示在 (例如)$(BINDIR)/my/program
中。在某些語言中,這類規則也會建立執行檔目錄,其中包含規則所屬
data
屬性中提及的所有檔案,或其依附元件的傳遞閉包中的任何規則;這組檔案會集中在一個位置,方便部署至實際環境。*_test
規則是*_binary
規則的特殊化,用於自動化測試。測試是成功傳回零的程式。和二進位檔一樣,測試也包含執行檔案樹狀結構,而測試以外的檔案是唯一在執行階段合法開啟的檔案。舉例來說,程式
cc_test(name='x', data=['//foo:bar'])
可能會在執行期間開啟及讀取$TEST_SRCDIR/workspace/foo/bar
。(每種程式設計語言都有自己的公用函式,可用於存取$TEST_SRCDIR
的值,但這些函式都等同於直接使用環境變數。)如果未遵循規則,在遠端測試主機上執行測試時,測試就會失敗。*_library
規則會在指定的程式設計語言中指定個別編譯的模組。程式庫可以依附其他程式庫,而二進位檔和測試可以依附程式庫,並採用預期的個別編譯行為。
標籤 | 依附元件 |