Bazel 註冊資料庫

回報問題 查看來源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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：來源封存檔的網址
        • mirror_urls：字串清單，來源封存檔的鏡像網址。 系統會依序嘗試這些網址，做為備份網址。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 具有「封存」類型時使用

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 重新啟用。