Bazel 詞彙表

回報問題 查看來源

動作

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

另請參閱: 規則說明文件

動作快取

對執行中的動作對應至所建立輸出內容的磁碟上快取。快取金鑰稱為「動作金鑰」。Bazel 成效增幅模型的核心元件。快取會儲存在輸出基礎目錄中,因此在 Bazel 伺服器重新啟動後仍會保留。

動作圖表

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

動作圖表查詢 (查詢)

可用來查詢建構動作查詢工具。如此一來,您就能分析「建構規則」如何轉譯至實際工作版本。

動作鍵

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

分析階段

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

構件

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

成果可以是多個動作的輸入,但只能由最多一個動作產生。

檔案目標對應的成果可以使用標籤處理。

長寬比

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

另請參閱: 相關說明文件

長寬比

可組合其他面向的結果的組合機制。舉例來說,可產生供 IDE 使用資訊的部分,可以套用在從 proto 產生 .java 檔案的元素之上。

為了讓 AB 上方套用,Bprovides 屬性中宣傳的供應商必須與其 required_aspect_providers 屬性中 A 宣告的所需內容相符。

屬性

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

.bazelrc

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

Blaze

Google 內部版本的 Bazel。Google 的單體存放區主要建構系統

建立檔案

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

BUILD.bazel 檔案

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

.bzl 檔案

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

建構圖表

Bazel 建構及掃遍以執行建構作業的依附元件圖表。包括目標設定的目標動作構件等節點。如果一組要求的目標所依附的構件都處於最新狀態,系統會將建構作業視為已完成。

建構設定

Starlark 定義的「設定」部分。轉場效果可進行建構設定以變更子圖表的設定。如果以指令列標記的形式向使用者公開,這也稱為建構標記。

乾淨版本

不使用先前版本結果的建構。這通常比漸進式建構慢,但通常視為正確。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動作依附元件

在某些情況下,模型也可以參照外部依附元件;請參閱模組一節。

解碼器

收集遞移依附元件的資料結構。經過最佳化之後,合併 depset 就能兼顧時間和空間效率,因為通常會有非常大的解組 (數十萬個檔案)。基於空間效率考量,可遞迴參照其他資料集。除非規則位於建構圖表頂層,否則規則實作不應藉由將其轉換為清單的方式進行「整併」。整併大型解碼器會產生大量記憶體使用量。也稱為 Bazel 內部實作中的「巢狀集」

另請參閱: Depset 說明文件

磁碟快取

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

骯髒

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

動態執行

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

執行階段

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

執行根目錄

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

檔案

請參閱「構件」一節。

密封

如果建構與建構和測試作業無關,就屬於隱含性質,這有助於確保結果具有確定性且正確。舉例來說,密封建構作業通常會禁止網路存取動作、限制對宣告輸入內容的存取權、使用固定的時間戳記和時區、限制環境變數的存取權,以及針對隨機號碼產生器使用固定種子

漸進式建構

漸進式建構會重複使用先前版本的結果,藉此縮短建構時間和資源使用。依附元件檢查和快取功能旨在針對這類建構作業產生正確的結果。漸進式建構作業與乾淨的建構作業相反。

標籤

目標的 ID。一般來說,格式為 @repo//path/to/package:target,其中 repo 是包含目標的存放區 (父項) 名稱,path/to/package 是包含宣告目標 BUILD 檔案的目錄路徑 (此目錄也稱為「套件」),而 target 是目標本身的名稱。在某些情況下,系統可能會省略這個語法中的部分。

另請參閱標籤

正在載入階段

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

巨集

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

另請參閱: 巨集說明文件

記憶拼音

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

Module

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

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

模組中繼資料會託管於 Bazel 註冊資料庫中。

另請參閱: Bazel 模組

模組擴充功能

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

另請參閱: 模組擴充功能

原生規則

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

輸出底數

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

輸出群組

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

輸出內容的使用者根層級

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

套件

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

套件群組

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

平台

建構期間涉及的「機器類型」。這包括在「主機」平台 (「主機」平台) 上執行的機器建構工具、在「執行」平台上執行的機器建構工具,以及專為「目標平台」而建構的機器目標。

供應商

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

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

查詢 (概念)

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

查詢 (指令)

這個查詢工具會針對版本的載入後 目標圖進行運作。速度相對較快,但無法分析 select()建構旗標構件或建構動作的效果。

另請參閱: 查詢使用指南查詢參考資料

存放區

一個目錄樹狀結構,其根層級有界線標記檔案,其中包含可用於 Bazel 建構作業的來源檔案。通常只有「存放區」即可縮減。

存放區邊界標記檔案可以是 MODULE.bazel (表示這個存放區代表 Bazel 模組)、REPO.bazel,或者在舊版結構定義中的 WORKSPACEWORKSPACE.bazel。任何存放區邊界標記檔案都會表示存放區的邊界;同一個目錄中可以同時存在多個這類檔案。

「主要存放區」是執行目前 Bazel 指令的存放區。

外部存放區的定義方式是在 MODULE.bazel 檔案中指定模組,或是在模組擴充功能中指定存放區規則。也可以隨選擷取到磁碟上預先定義的「磁性」位置。

每個存放區都有不重複的標準化名稱,而在其他存放區中查看時,名稱可能會有所不同。

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

存放區快取

Bazel 為建構作業下載的共用內容定址快取,可在各個工作區之間共用。在初次下載後啟用離線版本。通常用於快取透過存放區規則 (例如 http_archive) 和存放區規則 API (例如 repository_ctx.download) 下載的檔案。只有在下載時有指定 SHA-256 總和檢查碼的檔案,才會快取。

存放區規則

存放區定義的結構定義,用來指示 Bazel 如何具體化 (或「擷取」)存放區。通常只有存放區規則。Bazel 會在內部叫用存放區規則,藉此定義模組支援的存放區,也可以透過模組擴充功能叫用存放區。存放區規則可以存取網際網路或執行檔案 I/O;最常見的存放區規則為 http_archive,以便從網際網路下載內含來源檔案的封存。

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

可複製性

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

規則

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

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

另請參閱: 規則說明文件

規則目標

「目標」是規則例項。對比檔案目標和套件群組。不要與 規則混淆。

執行檔案

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

另請參閱: Runfiles 說明文件

沙箱機制

將執行中的動作隔離在受限的臨時執行根層級中,有助於確保不會讀取未宣告的輸入內容,或寫入未宣告的輸出內容。沙箱可大幅改善完整性,但通常會產生效能成本,且需要作業系統的支援。效能費用會因平台而異。Linux 通常沒有那麼重要,但在 macOS 上,無法使用沙箱功能。

空架

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 (所有規則目標)、:* (所有規則 + 檔案目標)、... (目前的 套件和所有子套件都是週期性的)。舉例來說,//...:* 可以合併使用,代表所有套件中的所有規則和檔案目標,都會從工作區的根層級遞迴。

測試命名空間

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

工具鏈

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

頂層目標

如果 Bazel 指令列要求建構,則建構目標是頂層。舉例來說,如果 //:foo 依附於 //:bar,且呼叫 bazel build //:foo,則針對這項建構作業呼叫 //:foo 是頂層,而 //:bar 也不是頂層,但都必須建構兩個目標。頂層與非頂層目標的重要差異在於,在 Bazel 指令列上設定的指令旗標 (或透過 .bazelrc) 會設定頂層目標的設定,但可透過轉換修改非頂層目標。

轉場

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

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

樹木構件

代表檔案集合的成果。由於這些檔案本身不是成果,因此在其中操作的「動作」必須註冊樹狀結構成果做為其輸入或輸出內容。

顯示設定

防止建構系統中不需要依附元件的其中一種機制:目標瀏覽權限 (用於控制其他目標是否能依賴某個目標);以及載入瀏覽權限,控制 BUILD.bzl 檔案是否可以載入指定的 .bzl 檔案。如果沒有內容,通常「可見度」是指目標可見度。

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

工作區

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

請注意,過去「存放區」和「工作區」的概念已限制;「工作區」一詞經常用於指稱主要存放區,有時也會用來當做「存放區」的同義詞。為求明確,請避免這類用法。