Bazel 詞彙表

回報問題 查看來源 Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

動作

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

另請參閱: 規則說明文件

動作快取

磁碟上的快取,用於儲存已執行動作與所建立輸出的對應關係。快取鍵稱為「動作鍵」。Bazel 遞增模型的核心元件。快取會儲存在輸出基準目錄中,因此在 Bazel 伺服器重新啟動後仍會存在。

動作圖

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

動作圖形查詢 (aquery)

查詢工具,可查詢建構動作。 這項功能可讓您分析建構規則如何轉換為實際建構作業。

快捷操作鍵

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

分析階段

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

構件

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

構件可做為多個動作的輸入內容,但最多只能由一個動作產生。

檔案目標對應的構件可透過標籤定址。

切面

規則可在依附元件中建立其他動作的機制。舉例來說,如果目標 A 依附於 B,則可對 A 套用某個方面,該方面會向上遍歷依附元件邊緣至 B,並在 B 中執行額外動作,以產生及收集額外輸出檔案。這些額外動作會經過快取,並在需要相同層面的目標之間重複使用。使用 aspect() Starlark Build API 函式建立。例如,可用於產生 IDE 的中繼資料,以及建立 Lint 動作。

另請參閱: 構面說明文件

切面與切面

組合機制,可將層面套用至其他層面的結果。舉例來說,產生 IDE 可用資訊的層面,可以套用至從 Proto 產生 .java 檔案的層面。

如要讓層面 A 適用於層面 BBprovides 屬性中宣傳 B供應商必須與 Arequired_aspect_providers 屬性中聲明的需求相符。

屬性

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

.bazelrc

Bazel 的設定檔用於變更啟動旗標指令旗標的預設值,以及定義常見的選項群組,然後使用 --config 旗標在 Bazel 指令列上一起設定這些選項。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 shutdown 明確停止)。將 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 產生動作依附元件

在特定情況下,這也可能指外部依附元件;請參閱模組

Depset

用於收集遞移依附元件資料的資料結構。經過最佳化,因此合併依附元件集既省時又省空間,因為依附元件集通常非常龐大 (數十萬個檔案)。為提高空間效率而實作,可遞迴參照其他 depsets。規則實作項目不應將 depsets 轉換為清單來「扁平化」,除非規則位於建構圖的頂層。扁平化大型 depsets 會耗用大量記憶體。在 Bazel 的內部實作中,也稱為「巢狀集合」。

另請參閱: Depset 說明文件

磁碟快取

遠端快取功能的本機磁碟上 Blob 儲存空間。可搭配實際的遠端 Blob 儲存空間使用。

Distdir

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

動態執行

執行策略會根據各種啟發式方法,在本機和遠端執行之間進行選擇,並使用較快成功方法的執行結果。某些動作在本機執行速度較快 (例如連結),其他動作則在遠端執行速度較快 (例如高度可平行化的編譯)。動態執行策略可盡量縮短遞增和乾淨建構時間。

執行階段

建構的第三個階段。執行在分析階段建立的動作圖表中的動作。這些動作會叫用可執行檔 (編譯器、指令碼),以讀取及寫入構件衍生策略可控管這些動作的執行方式,例如在本機、遠端、動態、沙箱或 Docker 中執行。

執行根目錄

工作區輸出基本目錄中的目錄,用於在非沙箱建構作業中執行本機動作。目錄內容大多是工作區中輸入 構件的符號連結。執行根目錄也包含外部存放區的符號連結 (做為其他輸入內容),以及用於儲存輸出的 bazel-out 目錄。在載入階段準備,方法是建立代表建構作業所依附套件遞移封閉的目錄符號連結樹狀結構。可透過指令列的 bazel info execution_root 存取。

檔案

請參閱「構件」一文。

Hermeticity

如果建構和測試作業不受外部影響,建構作業就是密封的,這有助於確保結果是確定的且正確。舉例來說,密封建構通常會禁止動作存取網路、限制存取已宣告的輸入內容、使用固定的時間戳記和時區、限制存取環境變數,以及使用固定的隨機數產生器種子

漸進式建構

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

標籤

目標的 ID。通常採用 @repo//path/to/package:target 形式,其中 repo 是包含目標的存放區 (顯而易見) 名稱,path/to/package 是包含宣告目標的 BUILD 檔案的目錄路徑 (這個目錄也稱為套件),而 target 是目標本身的名稱。視情況而定,這個語法的部分內容可能會省略。

另請參閱標籤

載入階段

建構的第一個階段,Bazel 會執行 BUILD 檔案來建立套件。系統會在這一階段評估巨集和特定函式,例如 glob()。與建構的第二階段交錯,即分析階段,以建構目標圖表

舊版巨集

一種巨集,會宣告為一般 Starlark 函式,並在執行 BUILD 檔案時以副作用的形式執行。

舊版巨集可以執行函式可執行的任何動作。這類字體很方便,但可能較難閱讀、書寫及使用。舊版巨集可能會意外變動引數,或在收到 select() 或型別錯誤的引數時失敗。

符號巨集形成對比。

另請參閱: 舊版巨集說明文件

巨集

這項機制可將多個規則目標宣告組合在一起,並放在單一 Starlark 可呼叫項目下。啟用後,即可在 BUILD 檔案中重複使用常見的規則宣告模式。在載入階段期間,擴充至基礎規則目標宣告。

巨集有兩種形式:符號巨集 (自 Bazel 8 起) 和舊版巨集

助記符

規則作者選取的人類可讀簡短字串,可快速瞭解規則中動作的作用。助記符可用於識別產生策略選取項目。動作助記符的範例包括 Java 規則中的 Javac、C++ 規則中的 CppCompile,以及 Android 規則中的 AndroidManifestMerger

Module

Bazel 專案可有多個版本,每個版本可依附於其他模組。這與其他依附元件管理系統中的常見概念類似,例如 Maven 構件、npm 套件、Go 模組或 Cargo Crate Crate。模組是 Bazel 外部依附元件管理系統的骨幹。

每個模組都由 存放區支援,且根目錄中都有 MODULE.bazel 檔案。這個檔案包含模組本身的中繼資料 (例如名稱和版本)、直接依附元件,以及各種其他資料,包括工具鍊註冊和模組擴充功能輸入內容。

模組中繼資料會代管在 Bazel 登錄檔中。

另請參閱: Bazel 模組

模組擴充功能

這段邏輯可讀取整個模組依附元件圖的輸入內容,並叫用repo 規則,藉此產生 repo。模組擴充功能的功能類似於 repo 規則,可存取網際網路、執行檔案 I/O 等。

另請參閱: 模組擴充功能

原生規則

Bazel 內建的規則,以 Java 實作。這類規則會以原生模組中的函式形式 (例如 native.cc_librarynative.java_library) 出現在 .bzl 檔案中。使用者定義規則 (非原生) 是使用 Starlark 建立。

輸出底座

儲存 Bazel 輸出檔案的工作區專屬目錄。用於將輸出內容與工作區的來源樹狀結構 (主要存放區) 分開。位於輸出使用者根目錄中。

輸出群組

這組檔案會在 Bazel 完成目標建構作業時建構。規則會將一般輸出內容放在「預設輸出群組」中 (例如 java_library.a.so.jar 檔案,適用於 cc_library 目標)。當您在指令列要求目標時,系統會建構預設輸出群組的構件。規則可以定義更多具名輸出群組,這些群組可在 BUILD 檔案 (filegroup 規則) 或指令列 (--output_groups 旗標) 中明確指定。

輸出使用者根目錄

用於儲存 Bazel 輸出的使用者專屬目錄。目錄名稱是根據使用者的系統使用者名稱而來。如果多位使用者同時在系統上建構同一個專案,這項功能可避免輸出檔案發生衝突。包含與個別工作區建構輸出內容對應的子目錄,也稱為「輸出基礎」

套件

BUILD 檔案定義的一組目標。套件名稱是相對於 repo 根目錄的 BUILD 檔案路徑。套件可以包含子套件,或包含 BUILD 檔案的子目錄,因此會形成套件階層。

套件群組

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

平台

建構作業中涉及的「機器類型」。這包括 Bazel 執行的機器 (「主機」平台)、建構工具執行的機器 (「執行」平台),以及建構目標的機器 (「目標平台」)。

供應商

這個結構定義描述要沿著依附元件關係在規則目標之間傳遞的資訊單位。通常包含編譯器選項、遞移來源或輸出檔案,以及建構中繼資料等資訊。通常會搭配 depset 使用,有效儲存累積的遞移資料。內建供應商的範例為 DefaultInfo

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

查詢 (概念)

分析建構圖表的程序,瞭解目標屬性和依附元件結構。Bazel 支援三種查詢變體:querycqueryaquery

查詢 (指令)

查詢工具,可在建構的載入後階段 目標圖形上運作。這項作業相對快速,但無法分析 select()建構標記構件或建構動作的效果。

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

存放區

目錄樹狀結構,根目錄中含有邊界標記檔案,內含可用於 Bazel 建構作業的來源檔案。通常會簡稱為「repo」

存放區界線標記檔案可以是 MODULE.bazel (表示這個存放區代表 Bazel 模組)、REPO.bazel,或在舊版環境中為 WORKSPACEWORKSPACE.bazel。任何存放區界線標記檔案都會標示存放區的界線;這類檔案可同時存在於目錄中。

主要存放區是指目前正在執行 Bazel 指令的存放區。

外部存放區的定義方式是在 MODULE.bazel 檔案中指定 modules,或在模組擴充功能中叫用 存放區規則。可視需求擷取至磁碟上預先決定的「神奇」位置。

每個存放區都有專屬的常數標準名稱,從其他存放區查看時,可能會有不同的顯示名稱。

另請參閱外部依附元件總覽

存放區快取

Bazel 為建構作業下載的檔案共用內容可定址快取,可跨工作區共用。啟用離線建構功能 (需先完成初始下載)。通常用於快取透過存放區規則 (例如 http_archive) 下載的檔案,以及存放區規則 API (例如 repository_ctx.download)。只有在下載時指定檔案的 SHA-256 總和檢查碼,系統才會快取檔案。

存放區規則

存放區定義的結構定義,可告知 Bazel 如何具體化 (或「擷取」) 存放區。通常會簡稱為「存放區規則」。 Bazel 會在內部叫用存放區規則,定義由模組支援的存放區,或由模組擴充功能叫用。Repo 規則可以存取網際網路或執行檔案 I/O;最常見的 repo 規則是 http_archive,可從網際網路下載包含來源檔案的封存檔。

另請參閱: 存放區規則說明文件

可複製性

建構或測試的屬性,即建構或測試的一組輸入內容每次都會產生相同的輸出內容,無論時間、方法或環境為何。請注意,這不一定代表輸出內容正確或符合需求。

規則

用於在 BUILD 檔案中定義規則目標的結構定義,例如 cc_library。從 BUILD 檔案作者的角度來看,規則包含一組屬性和黑箱邏輯。這項邏輯會告知規則目標如何產生輸出構件,並將資訊傳遞至其他規則目標。從.bzl作者的角度來看,規則是擴充 Bazel 的主要方式,可支援新的程式設計語言和環境。

系統會在載入階段例項化規則,以產生規則目標。在分析階段,規則目標會以供應器的形式,將資訊傳達給下游依附元件,並註冊動作,說明如何產生輸出構件。這些動作會在執行階段執行。

另請參閱: 規則說明文件

規則目標

規則的執行個體目標。與檔案目標和套件群組形成對比。請勿與規則混淆。

Runfiles

可執行目標的執行階段依附元件。通常,可執行檔是測試規則的可執行輸出內容,而執行檔是測試的執行階段資料依附元件。在叫用可執行檔之前 (在 bazel 測試期間),Bazel 會根據來源目錄結構,準備執行檔樹狀結構和測試可執行檔。

另請參閱: 執行檔說明文件

沙箱機制

這項技術可將正在執行的動作隔離在受限的暫時執行根目錄中,確保動作不會讀取未宣告的輸入內容,也不會寫入未宣告的輸出內容。沙箱可大幅提升密封性,但通常會影響效能,且需要作業系統支援。效能成本取決於平台。 在 Linux 上影響不大,但在 macOS 上可能會導致無法使用沙箱。

Skyframe

Skyframe 是 Bazel 的核心平行、函式和增量評估架構。

沖壓

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

Starlark

用於編寫規則巨集的擴充功能語言。Python 的受限子集 (語法和文法),適用於設定用途,並可提升效能。使用 .bzl 檔案擴充功能。BUILD 檔案使用更受限制的 Starlark 版本 (例如沒有 def 函式定義),先前稱為 Skylark。

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

啟動旗標

bazel指令之間指定的一組旗標,例如 bazel --host_jvm_debug build。這些標記會修改 Bazel 伺服器的設定,因此啟動標記的任何修改都會導致伺服器重新啟動。啟動旗標不屬於任何指令。

符號巨集

這類 巨集是使用類似規則屬性結構定義宣告,可隱藏自有套件中宣告的內部目標,並對巨集宣告的目標強制執行可預測的命名模式。旨在避免大型舊版巨集程式碼集中的某些問題。

另請參閱: 符號巨集說明文件

目標

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

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

除了規則目標,還有檔案目標和套件群組目標。檔案目標對應於 BUILD 檔案中參照的構件。在特殊情況下,任何套件的 BUILD 檔案一律視為該套件中的來源檔案目標。

目標是在載入階段中探索到的。在分析階段,目標會與建構設定建立關聯,形成已設定的目標

目標圖表

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

目標模式

在指令列中指定一組目標的方式。常用的模式包括 :all (所有規則目標)、:* (所有規則 + 檔案目標)、... (目前的套件和所有子套件 (遞迴))。可合併使用,例如 //...:* 表示從工作區根目錄遞迴的所有套件中,所有規則和檔案目標。

測試命名空間

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

工具鏈

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

頂層目標

如果建構目標是在 Bazel 命令行中要求,就會成為頂層目標。舉例來說,如果 //:foo 依附於 //:bar,且呼叫了 bazel build //:foo,則在這個建構作業中,//:foo 是頂層,而 //:bar 不是頂層,但這兩個目標都需要建構。頂層目標和非頂層目標之間的重要差異在於,在 Bazel 指令列 (或透過 .bazelrc) 設定的指令標記會為頂層目標設定設定,但可能會由非頂層目標的轉換修改。

轉移

從一個值到另一個值的設定狀態對應。即使是從同一個規則例項化,也能在建構圖中為目標啟用不同的設定。轉換的常見用途是搭配「分割」轉換,其中目標圖表的特定部分會分叉,每個分叉都有不同的設定。舉例來說,您可以在單一建構作業中,使用分割轉換功能,建構包含為 ARM 和 x86 編譯的原生二進位檔的 Android APK。

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

樹狀結構構件

代表檔案集合的構件。由於這些檔案本身並非構件,因此對這些檔案執行的動作必須改為將樹狀結構構件註冊為輸入或輸出內容。

顯示設定

防止建構系統中出現不必要依附元件的兩種機制之一:目標可見度,用於控管其他目標是否可依附於目標;以及載入可見度,用於控管 BUILD.bzl 檔案是否可載入特定 .bzl 檔案。如果沒有脈絡,通常「瀏覽權限」是指目標瀏覽權限。

另請參閱: 可見度說明文件

工作區

所有從相同主要存放區執行的 Bazel 指令都會共用環境。

請注意,從歷史來看,「存放區」和「工作區」的概念一直混淆不清;「工作區」一詞通常是指主要存放區,有時甚至用做「存放區」的同義詞。為求清楚明瞭,請避免使用這類用法。