建置檔案

回報問題 查看來源

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

根據定義,每個套件都包含 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_*。其中一些函式已記錄在建構百科全書中,但任何人都可以建立新規則。

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

    在部分語言中,這類規則還會建立一個執行檔案目錄,其中包含該規則的 data 屬性或依附元件遞移性閉合中提及的所有檔案。這組檔案集中收集起來,以便部署至實際工作環境。

  • *_test 規則是 *_binary 規則的特殊化,用於自動化測試。測試是成功傳回零的程式。

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

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

標籤 依附元件