Bazel 詞彙表

回報問題 查看來源

動作

要在建構期間執行的指令,例如呼叫編譯器,將 Artifacts 做為輸入內容,並產生其他構件做為輸出內容。包括指令列引數、動作金鑰、環境變數和宣告的輸入/輸出成果等中繼資料。

另請參閱: 規則說明文件

動作快取

磁碟快取,將已執行動作的對應關係儲存到其建立的輸出內容。快取金鑰稱為「動作鍵」。Bazel 成效增幅模型的核心元件。快取會儲存在輸出基本目錄中,因此在 Bazel 伺服器重新啟動後仍然有效。

動作圖表

記憶體內圖表顯示這些動作讀取及產生的動作構件。圖表可能包含以來源檔案形式存在的構件 (例如檔案系統中),以及未提及於 BUILD 檔案中產生的中繼/最終成果。在分析階段產生並在執行階段中使用。

動作圖表查詢 (查詢)

可查詢建構動作查詢工具。如此一來,就能分析建構規則如何轉換成實際工作建構作業。

動作鍵

動作的快取金鑰。根據動作中繼資料計算,其中可能包含要在動作、編譯器標記、程式庫位置或系統標頭中執行的指令 (視動作而定)。讓 Bazel 能確定個別動作的快取或撤銷。

分析階段

建構的第二個階段。處理 BUILD 檔案中指定的目標圖表,產生記憶體內操作圖表,此圖表會決定執行階段中的動作執行順序。這就是評估規則實作的階段。

構件

來源檔案或產生的檔案。也可以是檔案目錄,也稱為「樹狀構件」

構件可能是多個動作的輸入項目,但最多只能由一個動作產生。

檔案目標相對應的成果可以透過標籤解決。

切面

讓規則在依附元件中建立其他動作的機制。舉例來說,如果目標 A 依附 B,一個可以在 A 上套用能夠掃遍 B 依附元件邊緣至 B 的 A,並在 B 中執行其他動作,以產生及收集額外的輸出檔案。系統會快取這些額外動作,並在需要相同切面的目標之間重複使用。使用 aspect() Starlark Build API 函式建立。例如產生 IDE 的中繼資料,以及建立程式碼檢查動作。

另請參閱: 切面說明文件

長寬比

一種組合機制,可將切面套用至其他切面的結果。舉例來說,從 IDE 產生 .java 檔案的切面,可套用產生資訊供 IDE 使用的切面。

對於要套用於 B 的切面 A,在 provides 屬性中刊登 B供應商必須符合其 required_aspect_providers 屬性中所需宣告的 A

屬性

規則的參數,用於表示每個目標的建構資訊。例如 srcsdepscopts 可分別宣告目標的來源檔案、依附元件和自訂編譯器選項。特定目標可用的特定屬性取決於其規則類型。

.bazelrc

Bazel 的設定檔,用來變更啟動標記指令標記的預設值,以及定義通常可在 Bazel 指令列上使用 --config 標記一起設定的常用選項群組。Bazel 可合併多個 bazelrc 檔案的設定 (全系統、每個工作區、每位使用者或從自訂位置),而 bazelrc 檔案也可能會從其他 bazelrc 檔案匯入設定。

Blaze

Google 內部的 Bazel 版本。Google 的主要建構系統 適用於單一存放區

BUILD 檔案

BUILD 檔案是主要設定檔,用於告知 Bazel 要建構哪些軟體輸出內容、其依附元件,以及如何建構這些軟體。Bazel 會將 BUILD 檔案做為輸入內容,並使用該檔案建立依附元件圖表,並導出必須完成的動作,以建構中繼和最終軟體輸出內容。BUILD 檔案會將不含 BUILD 檔案的目錄和任何子目錄標示為「套件」,且可包含由規則建立的目標。您也可以將檔案命名為 BUILD.bazel

BUILD.bazel 檔案

請參閱 BUILD 檔案一節。優先順序高於同一目錄中的 BUILD 檔案。

.bzl 檔案

定義規則、巨集和以 Starlark 編寫的常數的檔案。接著,您可以使用 load() 函式將這些檔案匯入 BUILD 檔案

建構圖表

Bazel 會建構及遍歷執行建構作業的依附關係圖。包括目標設定的目標動作成果等節點。如果所有要求的目標依附於一組成果,且這些成果均經過驗證為最新,即代表建構已完成。

版本設定

Starlark 定義的設定部分。轉換可以調整建構設定,變更子圖表的設定。如以指令列標記的形式向使用者公開,也稱為建構標記。

清除版本

不使用先前建構結果的版本。這通常比漸進式建構作業慢,但通常會被視為正確。Bazel 能保證簡潔和漸進式建構作業一律正確

用戶端與伺服器模型

bazel 指令列用戶端會自動在本機電腦上啟動背景伺服器,以執行 Bazel 指令。伺服器會在執行指令後持續運作,但會在閒置一段時間後 (或透過 Bazel 關閉) 自動停止。將 Bazel 分割到伺服器和用戶端,有助於調節 JVM 啟動時間,並支援更快速的漸進式建構作業,因為動作圖表會在各指令的記憶體中留在記憶體中。

指令

在指令列中使用用來叫用不同的 Bazel 函式,例如 bazel buildbazel testbazel runbazel query

指令旗標

一組指令專屬的標記。您可以在指令 (bazel build <command flags>)之後指定指令標記。旗標可用於一或多個指令。舉例來說,--configurebazel sync 指令專用的標記,但 --keep_going 適用於 syncbuildtest 等。標記通常用於設定,因此標記值的變更可能會導致 Bazel 將記憶體內的圖表失效,並重新啟動分析階段

設定

規則定義以外的資訊會影響規則產生動作的方式。每個版本至少都有一項設定,會指定目標平台、動作環境變數和指令列建構標記轉換可能會建立其他設定,例如主機工具或跨編譯。

另請參閱: 設定

設定裁剪

此程序僅包含目標實際所需的設定部分。舉例來說,如果您使用 C++ 依附元件 //:c 建構 Java 二進位檔 //:j,在 //:c 的設定中加入 --javacopt 值會浪費時間,因為變更 --javacopt 會不必要的中斷 C++ 建構可快取性。

已設定的查詢 (cquery)

一種查詢工具,可根據已設定的目標執行查詢 (在分析階段完成之後)。這表示結果中會準確反映 select()建構旗標 (例如 --platforms)。

另請參閱: Cquery 說明文件

已設定的目標

使用設定評估目標的結果。在「分析階段」,您可以將建構選項與需要建構的目標結合,產生上述情況。舉例來說,如果 //:foo 在同一個建構中為兩個不同的架構建構,它就會有兩個已設定的目標:<//:foo, x86><//:foo, arm>

正確性

如果建構作業的輸出內容確實反映了遞移輸入的狀態,代表建構正確無誤。為達成正確的建構作業,Bazel 致力於達到語義、可重現,並使建構分析動作執行具有確定性。

依附元件

兩個目標之間的導向邊緣。如果 //:foo 的屬性值包含 //:bar 的參照,目標 //:foo 就在目標 //:bar 上具有目標依附元件。如果 //:foo 中的動作依附於 //:bar 中動作建立的輸入構件,則 //:foo 具有 //:bar動作依附元件

偏移

收集遞移依附元件資料的資料結構。已經過最佳化,讓合併的解碼器能夠同時具有時間和空間效率,因為共存有數十萬個檔案是很常見的情況。為了降低空間效率,系統在實作時以遞迴方式參照其他解碼器。規則實作不應藉由轉換為清單來「扁平」依附元件,除非規則位於建構圖表頂層。壓平合併大型解碼器會導致記憶體用量過大。在 Bazel 內部實作中也稱為「巢狀集合」

另請參閱: Depset 說明文件

磁碟快取

用於遠端快取功能的本機 blob 儲存庫。可與實際的遠端 blob 儲存庫搭配使用。

泥土

唯讀目錄,其中包含 Bazel 會使用存放區規則從網際網路擷取的檔案。讓建構作業完全離線執行。

動態執行

此執行策略會根據各種經驗法則選擇本機和遠端執行作業,並採用較快成功方法的執行結果。某些動作會在本機快速執行 (例如連結),而其他動作的遠端執行速度較快 (例如可高度平行的編譯)。動態執行策略可以盡可能提供最佳的增量建構時間。

執行階段

建構的第三個階段。執行在分析階段中建立的操作圖表中的動作。這些動作會叫用執行檔 (編譯器、指令碼) 來讀取及寫入成果。「縮減策略」可控管這些動作的執行方式,例如本機、遠端、動態、沙箱機制、docker 等。

執行根目錄

工作區「輸出基礎」目錄中的目錄,其中會在非採用沙箱機制的建構作業中執行本機動作。目錄內容主要是來自工作區的輸入構件的符號連結。執行根目錄還包含連至外部存放區的符號連結作為其他輸入,以及用於儲存輸出的 bazel-out 目錄。在載入階段執行準備,方法是建立目錄的符號連結樹系,用於代表建構所依附的套件遞移。可透過指令列中的 bazel info execution_root 存取。

檔案

請參閱「成果」。

遺傳

如果建構與測試作業沒有任何外部影響,就代表建構作業是密封的,有助於確保結果具有確定性且正確。例如,密封建構作業通常會禁止網路存取動作、限制存取宣告的輸入內容、使用固定的時間戳記和時區、限制對環境變數的存取權,以及針對隨機號碼產生器使用固定種子

漸進式建構

漸進式建構作業會重複使用先前版本的結果,以縮短建構時間和資源用量。依附元件檢查和快取目標是產生正確的這類型建構結果。漸進式建構作業與乾淨的建構作業相反。

標籤

目標的 ID。像 //path/to/package:target 這類的完整標籤會包含 // 來標記工作區根目錄,path/to/package 則是包含宣告目標的 BUILD 檔案 的目錄,以及 :target 做為上述 BUILD 檔案中宣告的目標名稱。我們也能加上 @my_repository//<..> 的前置字串,表示目標已在名為 my_repository 的「外部存放區」中宣告。

正在載入階段

建構的第一階段,Bazel 會剖析 WORKSPACEBUILD.bzl 檔案來建立套件。這個階段會評估巨集glob() 等特定函式。與建構的第二個階段 (即「分析階段」) 交錯,藉此建構目標圖表

巨集

在單一 Starlark 函式下組合多個規則目標宣告的機制。可在 BUILD 檔案中重複使用通用規則宣告模式。在載入階段中,擴展至基礎規則目標宣告。

另請參閱: 巨集說明文件

記憶音

規則作者選取的簡短字串,使用者可快速瞭解規則中的「動作」。Mnemonics 可做為基礎策略選項的 ID。動作記憶法的例子包括 Java 規則的 Javac、C++ 規則的 CppCompile,以及 Android 規則的 AndroidManifestMerger

原生規則

Bazel 內建的規則,並透過 Java 實作。這類規則會在 .bzl 檔案中顯示為原生模組中的函式 (例如 native.cc_librarynative.java_library)。如要建立使用者定義的規則 (非原生),則可以使用 Starlark 建立。

輸出基數

用來儲存 Bazel 輸出檔案的工作區專屬目錄。用於將輸出內容與工作區的來源樹狀結構分隔開來。這個路徑位於輸出使用者根目錄中。

輸出群組

當 Bazel 完成建構目標時,預計會建構的一組檔案。規則會將一般的輸出內容放在「預設輸出群組」(例如 cc_library 目標的 java_library.a.so.jar 檔案)。預設的輸出群組是輸出群組,此群組會在指令列要求目標時建構 artifacts。規則可以定義更多已命名的輸出群組,您可以在 BUILD 檔案 (filegroup 規則) 或指令列 (--output_groups 標記) 中明確指定。

輸出使用者根目錄

用於儲存 Bazel 輸出內容的使用者特定目錄。目錄名稱衍生自使用者的系統使用者名稱。如果多位使用者同時在系統中建構相同專案,會防止輸出檔案衝突。包含與個別工作區建構輸出內容相對應的子目錄,也稱為「輸出基礎」

套件

BUILD 檔案定義的目標組合。套件名稱為 BUILD 檔案與工作區根目錄的相對路徑。套件可包含子套件或包含 BUILD 檔案的子目錄,因此形成套件階層。

套件群組

代表一組套件的目標。通常用於 visibility 屬性值。

平台

建構中的「機器類型」。這包括在 (「主機」平台) 上執行的機器、機器建構工具在 (「exec」平台) 上執行的機器建構工具,以及針對 (「目標平台」) 建構機器目標。

提供者

結構定義,用於說明在依附關係關係在規則目標之間傳遞的資訊單位。一般來說,這包含編譯器選項、遞移來源或輸出檔案,以及建構中繼資料等資訊。經常與依附元件搭配使用,以便有效率地儲存累積的遞移資料。內建供應器的範例為 DefaultInfo

另請參閱: 供應商說明文件

查詢 (概念)

分析建構圖表的程序,以瞭解「目標」屬性和依附元件結構。Bazel 支援三種查詢變化版本:querycquerya 查詢

查詢 (指令)

適用於建構作業的載入後 目標圖表執行的「查詢」工具。相關作業速度相對較快,但無法分析 select()建構標記構件或建構動作的效果。

另請參閱: 查詢操作說明查詢參考資料

存放區快取

由 Bazel 下載的檔案共用可定址快取,可跨工作區共用。初次下載後,啟用離線建構功能。通常會用來快取透過 http_archive 等存放區規則和 repository_ctx.download 等存放區規則 API 下載的檔案。只有在下載檔案指定 SHA-256 檢查碼時,系統才會快取檔案。

可複製性

建構或測試的屬性,無論時間、方法或環境為何,每次建構或測試的輸入內容一律都會產生同一組輸出內容。請注意,這並不表示輸出結果是「正確」或所需的輸出內容。

規則

BUILD 檔案中定義規則目標的結構定義,例如 cc_library。從 BUILD 檔案作者的角度來看,規則包含一組「屬性」和黑色方塊邏輯。邏輯會指示規則目標如何產生輸出 Artifacts,並將資訊傳送至其他規則目標。從 .bzl 作者的角度來看,規則是擴充 Bazel 以支援新程式設計語言和環境的主要方式。

規則會在載入階段中執行個體化,以產生規則目標。在分析階段規則目標中,會以提供者的形式向下游依附元件傳遞資訊,並註冊動作,說明如何產生輸出內容構件。這些動作會在執行階段執行。

另請參閱: 規則說明文件

規則目標

代表規則例項的目標。與檔案目標和套件群組的差異不要與規則混淆。

執行檔案

可執行目標的執行階段依附元件。大多數情況下,執行檔是測試規則的可執行輸出,而執行檔案是測試的執行階段資料依附元件。在叫用執行檔 (Bazel 測試期間) 之前,Bazel 會根據來源目錄結構,準備執行檔案的樹狀結構以及測試執行檔。

另請參閱: Runfiles 說明文件

沙箱機制

在受限和臨時的執行根層級中隔離執行中動作的技術,有助於確保其不會讀取未宣告的輸入內容,或寫入未宣告的輸出內容。沙箱可大幅改善遺傳性,但通常有效能成本,而且需要作業系統支援。效能費用視平台而定。在 Linux 上這並不重要,但在 macOS 上可能會使沙箱無法使用。

SkyFrame

SkyFrame 是 Bazel 的核心平行、功能及漸進式評估架構。

沖壓

將額外資訊嵌入 Bazel 建構的成果的功能。舉例來說,這項資訊可用於控管發布子版本的原始碼控管、建構時間,以及其他工作區或環境相關資訊。透過支援戳記屬性的 --workspace_status_command 標記和規則啟用。

史塔拉克

用於編寫規則巨集的擴充功能語言。部分 Python (語法和文法上) 受限的子集,旨在用於設定,且可提高效能。使用 .bzl 檔案副檔名。BUILD 檔案使用更受限制的 Starlark 版本 (例如沒有 def 函式定義),以前稱為 Skylark。

另請參閱: Starlark 語言說明文件

啟動標記

bazel指令之間指定的一組標記,例如 bazel --host_jvm_debug 版本。這些標記會修改 Bazel 伺服器的設定,因此只要啟動標記,伺服器就會重新啟動。啟動標記並非專屬於任何指令。

目標

BUILD 檔案中定義的物件,並以標籤識別。目標代表從使用者的角度來看,可建構的工作區單元。

規則執行個體化而宣告的目標稱為「規則目標」。視規則而定,這些目標可能可以執行 (例如 cc_binary) 或可測試 (例如 cc_test)。規則目標一般會透過其屬性 (例如 deps) 依附其他目標,這些依附元件則構成目標圖表的基礎。

除了規則目標之外,還有檔案目標和套件群組目標。檔案目標會對應至 BUILD 檔案內參照的成果。做為特殊情況,任何套件的 BUILD 檔案一律視為該套件中的來源檔案目標。

載入階段期間,系統會探索目標。在分析階段,目標會與建構設定相關聯,形成設定的目標

目標圖表

目標及其依附元件的記憶體內圖表。在載入階段產生,並做為分析階段的輸入內容。

目標模式

在指令列中指定一組目標的方法。常用的模式包括 :all (所有規則目標)、:* (所有規則 + 檔案目標)、... (目前的「套件」和所有子套件會以遞迴方式進行)。舉例來說,//...:* 可以合併使用,代表從 workspace 的根目錄以遞迴方式使用所有套件中的所有規則和檔案目標。

測試命名空間

從測試規則執行個體化的目標,因此包含測試執行檔。執行檔完成後傳回零的傳回碼,表示測試成功。Bazel 和測試之間的確切合約 (例如測試環境變數、測試結果收集方法) 是在「測試百科全書」中指定。

工具鏈

一組可建構語言輸出內容的工具。工具鍊通常包含編譯器、連結器、解譯器或/和 Linter。工具鍊可能因平台而異,也就是說,即使工具鍊使用同一語言,Unix 編譯器工具鍊的元件可能與 Windows 變化版本不同。為平台選擇合適的工具鍊稱為工具鍊解析度。

頂層目標

如果透過 Bazel 指令列要求建構「目標」,則為頂層。舉例來說,如果 //:foo 依附 //:bar,並呼叫 bazel build //:foo,則在這項建構中,//:foo 是頂層,//:bar 不是頂層,不過這兩個目標都需要建構。頂層目標與非頂層目標之間的重要差異,在於 Bazel 指令列 (或透過 .bazelrc) 設定的「指令標記」會為頂層目標設定設定,但您可能會透過「轉換」針對非頂層目標進行修改。

轉移

設定狀態從某個值之間的對應。讓建構圖表中的目標具有不同的設定,即使這些目標是透過相同規則執行個體化也一樣。轉場效果的常見用途是「分割」轉換,也就是目標圖表的某些部分是分支,每個叉子都有不同的設定。舉例來說,您可以在單一建構作業中使用分割轉場功能,使用針對 ARM 和 x86 編譯的原生二進位檔建構 Android APK。

另請參閱: 使用者定義的轉場效果

樹木構件

代表一組檔案的構件。由於這些檔案本身不是成果,因此在這些檔案上執行的「動作」必須改為將樹狀結構成果註冊為輸入或輸出。

顯示設定

防止建構系統中不適用依附元件的兩種機制之一:目標瀏覽權限 (用於控制目標是否能由其他目標依附);以及載入瀏覽權限,用於控制 BUILD.bzl 檔案是否可以載入指定的 .bzl 檔案。在沒有背景脈絡的情況下,「能見度」通常是指目標瀏覽權限。

另請參閱: 瀏覽權限說明文件

Workspace

包含 WORKSPACE 檔案和要建構軟體原始碼的目錄。開頭為 // 的標籤與工作區目錄相關。

WORKSPACE 檔案

將目錄定義為工作區。雖然檔案可以空白,但通常包含外部存放區宣告,會從網路或本機檔案系統擷取其他依附元件。