Bazel 註冊資料庫

回報問題查看原始碼 Nightly · 8.1 · 8.0 · 7.5 · 7.4

Bzlmod 會從 Bazel 註冊表 (Bazel 模組的資料庫) 要求依附元件資訊，藉此發現依附元件。Bazel 僅支援一種註冊表類型，即索引註冊表，也就是依循特定格式的本機目錄或靜態 HTTP 伺服器。

索引登錄

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

索引註冊表必須採用下列格式：

/bazel_registry.json：選用的 JSON 檔案，其中包含註冊表的中繼資料。
/modules：目錄，其中包含此登錄檔中每個模組的子目錄
/modules/$MODULE：這個目錄包含每個模組版本的子目錄，這些子目錄的名稱為 $MODULE，以及包含此模組中繼資料的 metadata.json 檔案。
/modules/$MODULE/$VERSION：包含下列檔案的目錄：
- MODULE.bazel：這個模組版本的 MODULE.bazel 檔案。請注意，這是在 Bazel 外部依附元件解析期間讀取的 MODULE.bazel 檔案，不是來源封存區的檔案 (除非有非登錄機制覆寫)。
- source.json：JSON 檔案，其中包含如何擷取此模組版本來源的資訊
- patches/：可選的目錄，其中包含修補檔案，僅用於 source.json 為「archive」類型時
- overlay/：可選的目錄，其中包含疊加檔案，僅在 source.json 為「archive」類型時才會使用

`bazel_registry.json`

bazel_registry.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_path 類型模組的基本路徑

`metadata.json`

metadata.json 是可選的 JSON 檔案，其中包含模組相關資訊，包括下列欄位：

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

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

`source.json`

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

如果 type 為 archive (預設值)，這個模組版本會由 http_archive 存放區規則支援；擷取方式是從指定網址下載封存檔，然後擷取其內容。支援下列欄位：
- 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 中央登錄表

位於 https://bcr.bazel.build/ 的 Bazel 中央註冊中心 (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 可用來指定要從中要求模組的註冊表清單，因此您可以設定專案，從第三方或內部註冊表擷取依附元件。較早的註冊項目優先。為方便起見，您可以在專案的 .bazelrc 檔案中放入 --registry 旗標清單。

如果您的登錄表由 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 中央註冊服務，但您可以新增 --registry=https://bcr.bazel.build 來重新加入。