Bazel 模組

7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel 模組是可擁有多個版本的 Bazel 專案,每個版本都會發布關於所依附其他模組的中繼資料。這類似於其他依附元件管理系統中的熟悉概念,例如 Maven 構件、npm 套件、Go 模組或 Cargo crate

模組的存放區根目錄 (在 WORKSPACE 檔案旁邊) 須有 MODULE.bazel 檔案。此檔案是模組的資訊清單,會宣告模組的名稱、版本、直接依附元件清單和其他資訊。基本範例:

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

為了執行模組解析,Bazel 會先讀取根模組的 MODULE.bazel 檔案,然後從 Bazel 登錄處重複要求任何依附元件的 MODULE.bazel 檔案,直到發現整個相依關係圖為止。

根據預設,Bazel 會選取每個模組的一個版本來使用。Bazel 會使用一個存放區代表每個模組,並再次參考註冊中心,瞭解如何定義每個存放區。

版本格式

Bazel 擁有多元的生態系統,專案會使用各種版本管理方案。目前最受歡迎的是 SemVer,但也有知名專案使用其他配置,例如 Abseil (其版本是以日期為準,例如 20210324.2)。

因此,Bzlmod 採用了較為寬鬆的 SemVer 規格版本。差異包括:

  • SemVer 規定版本的「發布」部分必須包含 3 個部分:MAJOR.MINOR.PATCH。在 Bazel 中,這項要求會放寬,因此可以允許任意數量的區隔。
  • 在 SemVer 中,「release」部分的每個區段都必須只包含數字。在 Bazel 中,這項限制已放寬,因此也允許使用字母,且比較語意會與「預發布」部分的「ID」相符。
  • 此外,系統不會強制執行主要、次要和修補程式版本的語意。不過,請參閱「相容性等級」一文,進一步瞭解我們如何標示回溯相容性。

任何有效的 SemVer 版本都是有效的 Bazel 模組版本。此外,如果兩個 SemVer 版本 ab 以 Bazel 模組版本比較,則只有在兩者相同時,才能比較 a < b

選擇版本

請考慮鑽石依附元件問題,也就是版本化依附元件管理空間中的基石。假設您有一個依附關係圖:

       A 1.0
      /     \
   B 1.0    C 1.1
     |        |
   D 1.0    D 1.1

應使用哪個版本的 D?為解決這個問題,Bzlmod 使用 Go 模組系統中引進的最小版本選取 (MVS) 演算法。MVS 會假設模組的所有新版本都具有回溯相容性,因此請選擇任何相依項目指定的最高版本 (在本例中為 D 1.1)。之所以稱為「最小」版本,是因為 D 1.1 是可滿足我們需求的早期版本,即使 D 1.2 或更新版本也存在,我們也不會選取這些版本。使用 MVS 可建立高保真度可重現的版本選擇程序。

已撤銷的版本

如果應避免使用特定版本 (例如存在安全漏洞),登錄可以將其宣告為已撤銷。選取模組的撤銷版本時,Bazel 會擲回錯誤。如要修正這個錯誤,請升級至較新的非撤銷版本,或是使用 --allow_yanked_versions 標記明確允許撤銷版本。

相容性等級

在 Go 中,MVS 對回溯相容性的假設是有效的,因為它會將不相容的模組版本視為獨立模組。就 SemVer 而言,這表示 A 1.xA 2.x 視為不同的模組,可在已解析的依附元件圖表中並存。反過來說,這項功能是透過在 Go 的套件路徑中編碼主要版本而實現,因此不會發生任何編譯或連結時間衝突。

不過,Bazel 無法提供這類保證,因此需要「主要版本」編號才能偵測回溯不相容的版本。這個數字稱為相容性層級,由各模組版本在其 module() 指令中指定。有了這項資訊,Bazel 就能在偵測到已解析依附元件圖形中存在不同相容性等級的同一個模組版本時,擲回錯誤。

覆寫

MODULE.bazel 檔案中指定覆寫值,即可變更 Bazel 模組解析的行為。只有根模組的覆寫值會生效。如果模組用於依附元件,系統會忽略其覆寫值。

每個覆寫值都會指定特定模組名稱,並影響依附元件圖表中的所有版本。雖然只有根模組的覆寫會生效,但可能適用於根模組不會直接依附的遞移依附元件。

單一版本覆寫

single_version_override 可用於多種用途:

  • 使用 version 屬性,即可將依附元件固定在特定版本,無論依附元件圖中要求的依附元件版本為何。
  • 透過 registry 屬性,您可以強制這個依附元件來自特定登錄檔,而非遵循一般的登錄檔選取程序。
  • 您可以使用 patch* 屬性,指定要套用至下載模組的一系列修補程式。

這些屬性皆為選用,且可相互搭配使用。

多版本覆寫

您可以指定 multiple_version_override,讓同一個模組的多個版本在已解析的依附元件圖表中共存。

您可以明確指定模組的允許版本清單,這些版本必須在解析前出現在依附元件圖表中,且必須存在某些傳遞依附元件,取決於每個允許版本。解析後,系統只會保留允許的模組版本,而 Bazel 則會在相同相容性等級,將模組的其他版本升級至最接近的更高版本。如果沒有相同相容性等級的較高版本,Bazel 會擲回錯誤。

舉例來說,如果在解析前,依附元件圖表中存在 1.11.31.51.72.0 版本,且主要版本為相容性層級:

  • 允許 1.31.72.0 的多版本覆寫值會導致 1.1 升級至 1.31.5 升級至 1.7,其他版本則保持不變。
  • 允許 1.52.0 的多版本覆寫值會導致錯誤,因為 1.7 沒有可升級至相同相容性等級的較高版本。
  • 允許 1.92.0 的多重版本覆寫會導致錯誤,因為在解析前,依附元件圖表中未顯示 1.9

此外,使用者也可以使用 registry 屬性覆寫登錄,類似於單一版本覆寫。

非登錄覆寫值

非登錄檔覆寫值會從版本解析中完全移除模組。Bazel 不會從註冊表要求這些 MODULE.bazel 檔案,而是從儲存庫本身要求。

Bazel 支援下列非登錄檔覆寫:

存放區名稱和嚴格依附元件

支援模組的存放區標準名稱module_name~version (例如 bazel_skylib~1.0.3)。如果模組具有非登錄機制覆寫值,請將 version 部分替換為字串 override。請注意,標準名稱格式並非您應依賴的 API,且隨時可能會變更。

為模組提供直接依附元件的 repo 的顯示名稱預設為模組名稱,除非 bazel_dep 指令的 repo_name 屬性另有規定。請注意,這表示模組只能找到直接的依附元件。這有助於避免因傳遞式依附元件變更而導致意外中斷。

模組擴充功能也可以將其他存放區引入模組的可見範圍。