Bazel 註冊資料庫

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bazel 會向 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 檔案，不是來源封存檔中的檔案 (除非有非登錄檔的覆寫)。另請注意，最好使用這個檔案設定發布版本，並避免在來源封存 MODULE.bazel 檔案中進行這項操作。如要進一步瞭解模組版本控管，請參閱常見問題。
    • source.json：JSON 檔案，內含如何擷取這個模組版本來源的資訊
    • patches/：包含修補程式檔案的選用目錄，僅在 source.json 具有「封存」類型時使用
    • overlay/：包含重疊檔案的選用目錄，僅在 source.json 具有「封存」類型時使用

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 物件，指定這個模組的 yanked 版本。鍵應為要撤銷的版本，值應為撤銷版本的原因說明，最好包含更多資訊的連結。

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

source.json

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

  • 如果 type 為 archive (預設值)，這個模組版本會由 http_archive 存放區規則支援，方法是從指定網址下載封存檔並擷取內容。支援的欄位如下：
    • url：字串，來源封存檔的網址
    • mirror_urls：字串清單，來源封存檔的鏡像網址。系統會依序嘗試這些網址，做為備份網址。url
    • integrity：字串，封存檔的子資源完整性總和檢查碼
    • strip_prefix：字串，解壓縮來源封存檔時要移除的目錄前置字串
    • overlay：JSON 物件，內含要疊加在已擷取封存檔上的重疊檔案。修補程式檔案位於 /modules/$MODULE/$VERSION/overlay 目錄下。索引鍵是疊加檔案名稱，值則是疊加檔案的完整性總和檢查碼。系統會先套用疊加層，再套用修補程式檔案。
    • patches：JSON 物件，內含要套用至已解壓縮封存檔的修補程式檔案。修補程式檔案位於 /modules/$MODULE/$VERSION/patches 目錄下。索引鍵是修補程式檔案名稱，值則是修補程式檔案的完整性總和檢查碼。修補程式會在疊加檔案之後套用，並按照 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 重新啟用。