建置檔案

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

根據定義,每個套件都包含 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_binarycc_librarycc_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 規則會在指定的程式設計語言中指定個別編譯的模組。程式庫可以依附其他程式庫,而二進位檔和測試可以依附程式庫,並採用預期的個別編譯行為。

標籤 依附元件