Bazel 註冊資料庫

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

Bzlmod 會向 Bazel 登錄檔 (Bazel 模組資料庫) 要求依附元件資訊，目前 Bzlmod 僅支援索引登錄檔，也就是遵循特定格式的本機目錄或靜態 HTTP 伺服器。

索引登錄

索引登錄檔是本機目錄或靜態 HTTP 伺服器，內含模組清單的相關資訊，包括首頁、維護人員、各版本的 MODULE.bazel 檔案，以及如何擷取各版本的來源。值得注意的是，它「不需要」自行提供來源封存檔。

索引登錄檔必須採用以下格式：

  • /bazel_registry.json：包含登錄檔中繼資料的 JSON 檔案，例如：
    • mirrors：指定要用於來源封存檔的鏡像清單。 鏡像網址是鏡像本身與模組來源網址的串連，由 source.json 檔案指定，但不含通訊協定。舉例來說，如果模組的來源網址是 https://foo.com/bar/baz，且 mirrors 包含 ["https://mirror1.com/", "https://example.com/mirror2/"]，則 Bazel 會依序嘗試的網址為 https://mirror1.com/foo.com/bar/baz、https://example.com/mirror2/foo.com/bar/baz，最後是原始來源網址 https://foo.com/bar/baz。
    • module_base_path：在 source.json 檔案中，為具有 local_repository 類型的模組指定基本路徑
  • /modules：這個目錄包含登錄檔中每個模組的子目錄
  • /modules/$MODULE：這個目錄包含每個模組版本的子目錄，以及：
    • metadata.json：包含模組相關資訊的 JSON 檔案， 具有下列欄位：
      • homepage：專案首頁的網址
      • maintainers：JSON 物件清單，每個物件都對應至登錄檔中模組維護者的資訊。請注意，這不一定與專案的作者相同
      • versions：這個登錄檔中所有模組版本的清單
      • yanked_versions：這個模組的已撤銷版本地圖。鍵應為要撤銷的版本，值應為撤銷版本的原因說明，最好包含更多資訊的連結
  • /modules/$MODULE/$VERSION：包含下列檔案的目錄：
    • MODULE.bazel：這個模組版本的 MODULE.bazel 檔案
    • source.json：JSON 檔案，內含如何擷取這個模組版本來源的資訊
      • 預設類型為「archive」，代表 http_archive 存放區，包含下列欄位：
        • url：來源封存檔的網址
        • integrity：封存檔的子資源完整性 總和檢查碼
        • strip_prefix：解壓縮來源封存檔時要移除的目錄前置字串
        • patches：包含要套用至已擷取封存檔的修補程式檔案的地圖。修補程式檔案位於 /modules/$MODULE/$VERSION/patches 目錄下。索引鍵是修補程式檔案名稱，值則是修補程式檔案的完整性總和檢查碼
        • patch_strip：與 Unix patch 的 --strip 引數相同。
        • archive_type：下載檔案的封存類型 (與 http_archive 上的 type 相同)。 根據預設，系統會根據網址的副檔名判斷封存檔案類型。如果檔案沒有副檔名，您可以明確指定下列其中一種："zip"、"jar"、"war"、"aar"、"tar"、"tar.gz"、"tgz"、"tar.xz"、"txz"、"tar.zst"、"tzst"、tar.bz2、"ar" 或 "deb"。
      • 類型可以變更為使用 Git 存放區，並包含下列欄位：
        • type：git_repository
        • 下列欄位如 https://bazel.build/rules/lib/repo/git 所述：
          • remote
          • commit
          • shallow_since
          • tag
          • init_submodules
          • verbose
          • strip_prefix
      • 您可以變更類型，使用代表 local_repository 存放區的本機路徑，並搭配下列欄位：
        • type：local_path
        • path：存放區的本機路徑，計算方式如下：
          • 如果 path 是絕對路徑，則會維持原樣
          • 如果 path 是相對路徑，而 module_base_path 是絕對路徑，則會解析為 <module_base_path>/<path>
          • 如果 path 和 module_base_path 都是相對路徑，則會解析為 <registry_path>/<module_base_path>/<path>。登錄檔必須在本機託管，並由 --registry=file://<registry_path> 使用。否則 Bazel 會擲回錯誤
    • patches/：包含修補程式檔案的選用目錄，僅在 source.json 具有「封存」類型時使用

metadata.json

metadata.json 是選用的 JSON 檔案，內含模組相關資訊，並具有下列欄位：

  • versions：字串陣列，每個字串都代表這個登錄檔中可用的模組版本。這個陣列應與模組目錄的子項相符。
  • yanked_versions：JSON 物件，指定這個模組的 yanked 版本。鍵應為要撤銷的版本，值應為撤銷版本的原因說明，最好包含更多資訊的連結。

請注意，BCR 需要 metadata.json 檔案中的更多資訊。

source.json

source.json 是必要 JSON 檔案，內含如何擷取特定模組版本的資訊。這個檔案的結構取決於 type 欄位，預設為 archive。

  • 如果 type 為 archive (預設值)，這個模組版本會由 http_archive 存放區規則支援，方法是從指定網址下載封存檔並擷取內容。支援的欄位如下：
    • url：字串，來源封存檔的網址
    • mirror_urls：字串清單，來源封存檔的鏡像網址。系統會依序嘗試這些網址，做為備份網址。url
    • integrity：字串，封存檔的 [子資源完整性][subresource-integrity] 總和檢查碼
    • strip_prefix：字串，解壓縮來源封存檔時要移除的目錄前置字串
    • overlay：JSON 物件，內含要疊加在已擷取封存檔上的重疊檔案。修補程式檔案位於 /modules/$MODULE/$VERSION/overlay 目錄下。索引鍵是疊加檔案名稱，值則是疊加檔案的完整性總和檢查碼。系統會先套用疊加層，再套用修補程式檔案。
    • patches：JSON 物件，內含要套用至已解壓縮封存檔的修補程式檔案。修補程式檔案位於 /modules/$MODULE/$VERSION/patches 目錄下。索引鍵是修補程式檔案名稱，值則是修補程式檔案的完整性總和檢查碼。修補程式會在疊加檔案之後套用。
    • patch_strip：數字，與 Unix patch 的 --strip 引數相同。
    • archive_type：字串，下載檔案的封存類型 (與 http_archive 上的 type 相同)。
  • 如果 type 為 git_repository，這個模組版本會由 git_repository 存放區規則支援，並透過複製 Git 存放區擷取。
    • 系統支援下列欄位，並直接轉送至基礎 git_repository 存放區規則：remote、commit、shallow_since、tag、init_submodules、verbose 和 strip_prefix。
  • 如果 type 為 local_path，這個模組版本會由 local_repository 存放區規則支援，並符號連結至本機磁碟上的目錄。並可支援下列欄位：
    • path：存放區的本機路徑，計算方式如下：
      • 如果 path 是絕對路徑，則會維持原樣
      • 如果 path 是相對路徑，而 module_base_path 是絕對路徑，則會解析為 <module_base_path>/<path>
      • 如果 path 和 module_base_path 都是相對路徑，則會解析為 <registry_path>/<module_base_path>/<path>。登錄檔必須在本機託管，並由 --registry=file://<registry_path> 使用。否則 Bazel 會擲回錯誤

Bazel Central Registry

位於 https://bcr.bazel.build/ 的 Bazel Central Registry (BCR) 是索引登錄檔，內容由 GitHub 存放區 bazelbuild/bazel-central-registry 提供。您可以使用 https://registry.bazel.build/ 的網頁前端瀏覽內容。

Bazel 社群會維護 BCR，歡迎貢獻者提交提取要求。請參閱 BCR 貢獻內容指南。

除了遵循一般索引登錄檔的格式，BCR 也需要每個模組版本 (/modules/$MODULE/$VERSION/presubmit.yml) 的 presubmit.yml 檔案。這個檔案會指定幾個重要的建構和測試目標，可用於檢查這個模組版本的有效性。BCR 的 CI 管道也會使用這項功能，確保模組之間的互通性。

選取登錄檔

可重複的 Bazel 標記 --registry 可用於指定要從中要求模組的登錄檔清單，因此您可以設定專案，從第三方或內部登錄檔擷取依附元件。較早的登錄記錄優先。為方便起見，您可以將 --registry 旗標清單放在專案的 .bazelrc 檔案中。

如果您的登錄檔是代管在 GitHub 上 (例如 bazelbuild/bazel-central-registry 的分支)，則 --registry 值需要 raw.githubusercontent.com 下的原始 GitHub 位址。舉例來說，在 my-org 分支的 main 分支上，您會設定 --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/。

使用 --registry 標記會停止預設使用 Bazel Central Registry，但您可以新增 --registry=https://bcr.bazel.build 重新啟用。