動作
建構期間執行的指令,例如呼叫編譯器,將構件做為輸入內容,並產生其他構件做為輸出內容。包括指令列引數、動作鍵、環境變數,以及已宣告的輸入/輸出構件等中繼資料。
另請參閱: 規則說明文件
動作快取
磁碟快取,用於儲存已執行的動作與其建立的輸出內容之間的對應關係。快取鍵稱為「動作鍵」。Bazel 增量模型的核心元件。快取會儲存在輸出基準目錄中,因此在 Bazel 伺服器重新啟動後仍會存在。
動作圖
動作的記憶體內圖表,以及這些動作讀取和產生的構件。圖表可能包含以來源檔案形式存在的構件 (例如在檔案系統中),以及 BUILD
檔案中未提及的產生中繼/最終構件。在分析階段產生,並在執行階段使用。
動作圖形查詢 (aquery)
查詢工具,可查詢建構動作。 這有助於分析建構規則如何轉換為實際建構作業。
快捷操作鍵
動作的快取金鑰。根據動作中繼資料計算,可能包括要在動作中執行的指令、編譯器標記、程式庫位置或系統標頭 (視動作而定)。讓 Bazel 能夠確定個別動作的快取或失效狀態。
分析階段
建構作業的第二階段。處理 BUILD
檔案中指定的目標圖表,產生記憶體內動作圖表,決定執行階段要執行的動作順序。這個階段會評估規則的實作情況。
構件
來源檔案或產生的檔案。也可以是檔案目錄,稱為樹狀結構構件。
構件可做為多個動作的輸入內容,但最多只能由一個動作產生。
與檔案目標對應的構件可透過標籤定址。
切面
規則可在依附元件中建立其他動作的機制。舉例來說,如果目標 A 依附於 B,則可對 A 套用某個方面,該方面會向上遍歷依附元件邊緣至 B,並在 B 中執行其他動作,以產生及收集其他輸出檔案。這些額外動作會經過快取,並在需要相同層面的目標之間重複使用。使用 aspect()
Starlark Build API 函式建立。例如,可用於產生 IDE 的中繼資料,以及建立 Lint 動作。
另請參閱: 構面說明文件
切面與切面
組合機制,可將層面套用至其他層面的結果。舉例來說,產生 IDE 可用資訊的層面,可以套用至從 Proto 產生 .java
檔案的層面。
如要讓層面 A
適用於層面 B
,B
在 provides
屬性中宣傳的供應商必須與 A
在 required_aspect_providers
屬性中聲明的需求相符。
屬性
規則的參數,用於表示每個目標的建構資訊。例如 srcs
、deps
和 copts
,分別宣告目標的來源檔案、依附元件和自訂編譯器選項。特定目標可用的屬性取決於規則類型。
.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
build
、bazel test
、bazel run
和 bazel query
。
指令旗標
一組專屬於指令的旗標。指令旗標是在指令 (bazel build <command flags>
) 之後指定。旗標可適用於一或多個指令。舉例來說,--configure
是 bazel sync
指令專用的旗標,但 --keep_going
適用於 sync
、build
、test
等。旗標通常用於設定,因此旗標值變更時,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 中執行。
執行根目錄
workspace 的輸出基本目錄中的目錄,用於在非沙箱建構作業中執行本機動作。目錄內容大多是工作區中輸入 構件的符號連結。執行根目錄也包含外部存放區的符號連結,做為其他輸入內容和 bazel-out
目錄,用於儲存輸出內容。在載入階段準備,方法是建立代表建構作業所依附套件遞移封閉的目錄符號連結樹狀結構。可透過指令列的 bazel info
execution_root
存取。
檔案
請參閱「構件」一文。
密封性
如果建構和測試作業不受外部影響,建構作業就是密封的,這有助於確保結果是確定性的,且正確無誤。舉例來說,密封建構通常會禁止動作存取網路、限制存取已宣告的輸入內容、使用固定的時間戳記和時區、限制存取環境變數,以及使用固定的隨機數產生器種子
漸進式建構
漸進式建構會重複使用先前建構作業的結果,以縮短建構時間並減少資源用量。依附元件檢查和快取作業的目標,是為這類建構作業產生正確結果。漸進式建構與清除建構相反。
標籤
目標的 ID。完整標籤 (例如 //path/to/package:target
) 包含 //
(用於標記工作區根目錄)、path/to/package
(做為包含宣告目標的 BUILD
檔案的目錄),以及 :target
(做為上述 BUILD
檔案中宣告的目標名稱)。也可以加上 @my_repository//<..>
前置字元,表示目標是在名為 my_repository
的外部存放區中宣告。
載入階段
建構的第一個階段,Bazel 會剖析 WORKSPACE
、BUILD
和 .bzl
檔案,建立套件。系統會在這一階段評估巨集和特定函式 (例如 glob()
)。與建構的第二個階段交錯進行的分析階段,可建構目標圖表。
巨集
這項機制可將多個規則目標宣告組合在一起,並放在單一 Starlark 函式下。啟用後,即可在 BUILD
檔案中重複使用常見的規則宣告模式。在載入階段,擴展至基礎規則目標聲明。
另請參閱: 巨集說明文件
助記符
規則作者選取的人類可讀簡短字串,可快速瞭解規則中動作的作用。助記符可用於識別產生策略選項。動作助記符的範例包括 Java 規則中的 Javac
、C++ 規則中的 CppCompile
,以及 Android 規則中的 AndroidManifestMerger
。
原生規則
Bazel 內建的規則,以 Java 實作。這類規則會以原生模組中的函式形式 (例如 native.cc_library
或 native.java_library
) 出現在 .bzl
檔案中。使用者定義規則 (非原生) 是使用 Starlark 建立。
輸出底座
儲存 Bazel 輸出檔案的工作區專屬目錄。用於將輸出內容與工作區的來源樹狀結構分開。位於輸出使用者根目錄中。
輸出群組
當 Bazel 完成目標建構時,預期會建構的一組檔案。規則會將一般輸出內容放在「預設輸出群組」中 (例如 cc_library
目標的 java_library
、.a
和 .so
的 .jar
檔案)。當您在指令列要求目標時,系統會建構預設輸出群組的構件。規則可以定義更多具名輸出群組,這些群組可在 BUILD
檔案 (filegroup
規則) 或指令列 (--output_groups
旗標) 中明確指定。
輸出使用者根目錄
用於儲存 Bazel 輸出的使用者專屬目錄。目錄名稱是根據使用者的系統使用者名稱衍生而來。如果多位使用者同時在系統上建構同一個專案,這項功能可避免輸出檔案發生衝突。包含與個別工作區建構輸出內容對應的子目錄,也稱為「輸出基礎」。
套件
由 BUILD
檔案定義的一組目標。套件名稱是相對於工作區根目錄的 BUILD
檔案路徑。套件可以包含子套件,或包含 BUILD
檔案的子目錄,進而形成套件階層。
套件群組
代表一組套件的目標。通常用於 visibility
屬性值。
平台
建構作業中涉及的「機器類型」。這包括 Bazel 執行的機器 (「主機」平台)、建構工具執行的機器 (「執行」平台),以及建構目標的機器 (「目標平台」)。
供應商
這個結構定義描述要沿著依附元件關係在規則目標之間傳遞的資訊單位。通常包含編譯器選項、遞移來源或輸出檔案,以及建構中繼資料等資訊。通常會搭配 depset 使用,有效儲存累積的遞移資料。內建供應商的範例為 DefaultInfo
。
另請參閱: 供應商說明文件
查詢 (概念)
分析建構圖表的程序,瞭解目標屬性和依附元件結構。Bazel 支援三種查詢變體:query、cquery 和 aquery。
查詢 (指令)
查詢工具,可在建構的載入後階段 目標圖形上運作。這項作業相對快速,但無法分析 select()
的影響、建構標記、構件或建構動作。
存放區快取
Bazel 為建構作業下載的檔案共用內容可定址快取,可跨工作區共用。啟用離線建構功能 (需先完成初始下載)。通常用於快取透過存放區規則 (例如 http_archive
) 下載的檔案,以及存放區規則 API (例如 repository_ctx.download
)。只有在下載時指定檔案的 SHA-256 檢查碼,系統才會快取檔案。
可複製性
建構或測試的屬性,一組建構或測試的輸入內容每次都會產生相同的輸出內容,無論時間、方法或環境為何。請注意,這不一定代表輸出內容正確或符合需求。
規則
用於在 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
(所有規則目標)、:*
(所有規則 + 檔案目標)、...
(目前的套件和所有子套件 (遞迴))。可合併使用,例如 //...:*
表示從工作區根目錄遞迴的所有套件中,所有規則和檔案目標。
測試命名空間
規則 targets 是從測試規則例項化的,因此包含測試可執行檔。可執行檔完成時傳回的零值表示測試成功。Bazel 與測試之間的確切合約 (例如測試環境變數、測試結果收集方法) 會在測試百科全書中指定。
工具鏈
這組工具可為語言建構輸出內容。一般來說,工具鍊包含編譯器、連結器、解譯器和/或 Linter。工具鍊也可能因平台而異,也就是說,即使工具鍊適用於同一種語言,Unix 編譯器工具鍊的元件也可能與 Windows 變體不同。為平台選取合適的工具鍊,稱為工具鍊解析。
頂層目標
如果建構目標是在 Bazel 命令行中要求,則為頂層目標。舉例來說,如果 //:foo
依附於 //:bar
,且呼叫了 bazel build //:foo
,則在這個建構作業中,//:foo
是頂層,而 //:bar
不是頂層,但這兩個目標都需要建構。頂層目標和非頂層目標之間的重要差異在於,在 Bazel 指令列 (或透過 .bazelrc) 設定的指令標記會為頂層目標設定設定,但可能會由非頂層目標的轉換修改。
轉移
從一個值到另一個值的設定狀態對應。即使是從同一個規則例項化,也能在建構圖中為目標啟用不同設定。轉換的常見用途是搭配「分割」轉換,其中目標圖表的特定部分會分叉,每個分叉都有不同的設定。舉例來說,您可以在單一建構作業中,使用分割轉換功能,建構包含為 ARM 和 x86 編譯的原生二進位檔的 Android APK。
另請參閱: 使用者定義的轉場效果
樹狀結構構件
代表檔案集合的構件。由於這些檔案本身並非構件,因此對這些檔案執行的動作必須改為將樹狀結構構件註冊為輸入或輸出內容。
顯示設定
防止建構系統中出現不必要依附元件的兩種機制之一:目標顯示狀態,用於控管其他目標是否可依附於目標;以及載入顯示狀態,用於控管 BUILD
或 .bzl
檔案是否可載入特定 .bzl
檔案。如果沒有脈絡,通常「瀏覽權限」是指目標瀏覽權限。
另請參閱: 可見度說明文件
工作區
包含 WORKSPACE
檔案和要建構軟體的原始碼的目錄。以 //
開頭的標籤與工作區目錄相關。
WORKSPACE 檔案
將目錄定義為工作區。這個檔案可以空白,但通常會包含外部存放區宣告,以便從網路或本機檔案系統擷取其他依附元件。