Bazel 詞彙表

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

動作

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

另請參閱: 規則說明文件

動作快取

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

動作圖

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

動作圖表查詢 (aquery)

查詢工具,可針對建構動作執行查詢。這可讓您分析建構規則如何轉換為實際的工作建構作業。

快捷操作鍵

動作的快取鍵。根據動作中繼資料計算而得,這可能包括要在動作中執行的命令、編譯器標記、程式庫位置或系統標頭,具體取決於動作。讓 Bazel 能夠以確定的方式快取或使個別動作失效。

分析階段

建構作業的第二階段。處理 BUILD 檔案中指定的目標圖,產生內存中的動作圖,以決定在執行階段期間要執行的動作順序。這個階段會評估規則實作項目。

構件

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

一個構件可以是多個動作的輸入內容,但必須由最多一個動作產生。

對應至檔案目標的構件可透過標籤處理。

切面

規則的機制,可在依附元件中建立其他動作。舉例來說,如果目標 A 依附於 B,您可以在 A 上套用會沿著上游依附元件邊緣前往 B 的面向,並在 B 中執行其他動作,以產生及收集其他輸出檔案。這些額外動作會快取,並在需要相同特徵的目標之間重複使用。使用 aspect() Starlark Build API 函式建立。可用於產生 IDE 的中繼資料,以及建立 linting 的動作。

另請參閱: Aspects 說明文件

切面上的切面

組合機制,可將各個面向套用至其他面向的結果。舉例來說,如果某個面向可用於 IDE 的資訊產生器,可以套用在從 proto 產生 .java 檔案的面向上。

如果要讓 A 層面套用 B 層面,B 在其 provides 屬性中宣傳的供應者必須與 A 在其 required_aspect_providers 屬性中宣告的供應者相符。

屬性

規則的參數,用於表示每個目標的建構資訊。例如 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>) 的後方指定。旗標可套用至一或多個指令。舉例來說,--configure 是專屬於 bazel 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

用於收集關於傳遞依附元件的資料的資料結構。最佳化,以便合併 depset 時節省時間和空間,因為 depset 通常會非常大 (數十萬個檔案)。實作此方法是為了節省空間,因此會遞迴參照其他 depset。除非規則位於建構圖的頂層,否則規則實作不應透過將依附元件集轉換為清單來「扁平化」依附元件集。將大型 depset 攤平會耗用大量記憶體。在 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 可呼叫項目下,將多個 rule 目標宣告組合在一起的機制。可在 BUILD 檔案中重複使用常見的規則宣告模式。在載入階段擴充至基礎規則目標宣告。

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

Mnemonic

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

模組

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

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

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

另請參閱: Bazel 模組

模組擴充

可執行的邏輯片段,可透過讀取 模組依附元件圖表中的輸入內容,並叫用存放區規則來產生 repos。模組擴充功能的功能類似於 repo 規則,可讓模組存取網際網路、執行檔案 I/O 等。

另請參閱: 模組擴充功能

原生規則

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

輸出基礎

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

輸出群組

在 Bazel 完成建構目標時,預期會建構的一組檔案。規則會將通常的輸出內容放入「預設輸出群組」(例如 java_library.jar 檔案、.a.socc_library 目標)。預設輸出群組是輸出群組,當您在指令列上要求目標時,系統會建構構件。規則可定義更多具名輸出群組,並在 BUILD 檔案 (filegroup 規則) 或指令列 (--output_groups 旗標) 中明確指定這些群組。

輸出使用者根目錄

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

套件

BUILD 檔案定義的目標集合。套件的名稱是 BUILD 檔案相對於 repo 根目錄的路徑。套件可包含子套件,或包含 BUILD 檔案的子目錄,進而形成套件階層。

套件群組

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

平台

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

供應商

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

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

查詢 (概念)

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

查詢 (指令)

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

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

存放區

目錄樹狀結構,根目錄含有邊界標記檔案,內含可用於 Bazel 建構作業的原始碼檔案。通常會縮寫為 repo

Repo 邊界標記檔案可以是 MODULE.bazel (表示此 repo 代表 Bazel 模組)、REPO.bazel,或在舊版情境中為 WORKSPACEWORKSPACE.bazel。任何 repo 邊界標記檔案都會標示 repo 的邊界;多個此類檔案可同時存在於一個目錄中。

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

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

每個 repo 都有一個不重複的常數標準名稱,且在其他 repo 中顯示的顯示名稱可能不同。

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

存放區快取

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

存放區規則

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

參考資料: 專案設定規則說明文件

可複製性

建構或測試的屬性,表示建構或測試的輸入組合每次都會產生相同的輸出組合,不受時間、方法或環境影響。請注意,這並不一定表示輸出內容是「正確」或所需的輸出內容。

規則

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

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

另請參閱: 規則說明文件

規則目標

目標:規則的例項。與檔案目標和套件群組形成對比。請勿與「規則」混淆。

執行檔

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

參閱Runfiles 說明文件

沙箱機制

這是一種隔離技巧,可在受限制且暫時的執行根目錄中隔離執行中的動作,有助於確保該動作不會讀取未宣告的輸入內容或寫入未宣告的輸出內容。沙箱可大幅提升密封性,但通常會造成效能成本,且需要作業系統的支援。效能成本取決於平台。在 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 檔案中定義的物件,並以標籤識別。從使用者角度來看,目標代表工作區的可建構單位。

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

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

系統會在載入階段期間發現目標。在分析階段,目標會與建構設定建立關聯,形成已設定的目標

目標圖表

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

目標模式

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

測試命名空間

規則 目標是從測試規則例項化,因此包含可執行的測試。執行檔完成後傳回的零代表測試成功。Test Encyclopedia 會說明 Bazel 與測試之間的確切合約,例如測試環境變數、測試結果收集方法。

工具鏈

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

頂層目標

如果在 Bazel 指令列上要求建構目標,則該目標為頂層。舉例來說,如果 //:foo 依賴 //:bar,且 bazel build //:foo 已呼叫,則對於這個版本,//:foo 是頂層,而 //:bar 不是頂層,但兩個目標都需要建構。頂層和非頂層目標之間的重要差異在於,在 Bazel 指令列 (或透過 .bazelrc) 設定的指令標記會為頂層目標設定設定,但可能會因非頂層目標的轉換而有所修改。

轉移

設定狀態從一個值對應至另一個值。讓建構圖中的目標具有不同的設定,即使這些目標是從相同規則實例化也一樣。轉換的常見用途是分割轉換,其中 目標圖表的特定部分會分支,並為每個分支提供不同的設定。舉例來說,您可以使用單一版本中的分割轉場,為 ARM 和 x86 編譯原生二進位檔,進而建構 Android APK。

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

樹狀結構成果

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

顯示設定

這是在建構系統中防止不必要依附元件的兩種機制之一:目標可見度可用於控制其他目標是否可以依附目標載入可見度可用於控制 BUILD.bzl 檔案是否可以載入特定 .bzl 檔案。在沒有上下文的情況下,「可見度」通常是指目標可見度。

另請參閱: 顯示度說明文件

工作區

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

請注意,過去「存放區」和「工作區」的概念經常會混淆;「工作區」一詞經常用來指主要存放區,有時甚至會用作「存放區」的同義詞。為了避免造成混淆,應避免使用這類用法。