建置檔案

回報問題 查看來源

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

根據定義,每個套件都包含 BUILD 檔案,這是一個簡短程式。

BUILD 檔案是使用命令式語言 Starlark 來評估的。

系統會將其視為連續陳述式清單。

一般來說,順序非常重要:例如必須先定義變數才能使用。不過,大部分的 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_*。其中部分函式記錄在 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 規則會針對特定程式設計語言指定單獨編譯的模組。程式庫依附於其他程式庫,而二進位檔和測試則可依附程式庫,而程式庫要有獨立的編譯行為。

標籤 依附元件