Registry Bazel

Per malam · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

Bzlmod menemukan dependensi dengan meminta informasinya dari registri Bazel: database modul Bazel. Saat ini, Bzlmod hanya mendukung registri indeks — direktori lokal atau server HTTP statis yang mengikuti format tertentu.

Registry indeks

Registry indeks adalah direktori lokal atau server HTTP statis yang berisi informasi tentang daftar modul — termasuk halaman beranda, pengelola, file MODULE.bazel setiap versi, dan cara mengambil sumber setiap versi. Khususnya, tidak perlu menayangkan arsip sumber itu sendiri.

Pendaftaran indeks harus mengikuti format di bawah:

  • /bazel_registry.json: File JSON yang berisi metadata untuk registry seperti:
    • mirrors: menentukan daftar mirror yang akan digunakan untuk arsip sumber. URL yang dicerminkan adalah gabungan dari cermin itu sendiri, dan URL sumber modul yang ditentukan oleh file source.json-nya tanpa protokol. Misalnya, jika URL sumber modul adalah https://foo.com/bar/baz, dan mirrors berisi ["https://mirror1.com/", "https://example.com/mirror2/"], maka URL yang akan dicoba Bazel secara berurutan adalah https://mirror1.com/foo.com/bar/baz, https://example.com/mirror2/foo.com/bar/baz, dan terakhir URL sumber aslinya sendiri https://foo.com/bar/baz.
    • module_base_path: menentukan jalur dasar untuk modul dengan jenis local_repository dalam file source.json
  • /modules: Direktori yang berisi subdirektori untuk setiap modul dalam registri ini
  • /modules/$MODULE: Direktori yang berisi subdirektori untuk setiap versi modul ini, serta:
    • metadata.json: File JSON yang berisi informasi tentang modul, dengan kolom berikut:
      • homepage: URL halaman beranda project
      • maintainers: Daftar objek JSON, yang masing-masing sesuai dengan informasi pengelola modul dalam registry. Perhatikan bahwa hal ini tidak harus sama dengan penulis project
      • versions: Daftar semua versi modul ini yang akan ditemukan di registri ini
      • yanked_versions: Peta versi modul ini yang dibatalkan. Kuncinya harus berupa versi yang akan dibatalkan dan nilainya harus berupa deskripsi mengapa versi tersebut dibatalkan, idealnya berisi link ke informasi lainnya
  • /modules/$MODULE/$VERSION: Direktori yang berisi file berikut:
    • MODULE.bazel: File MODULE.bazel versi modul ini
    • source.json: File JSON yang berisi informasi tentang cara mengambil sumber versi modul ini
      • Jenis defaultnya adalah "archive", yang merepresentasikan repo http_archive, dengan kolom berikut:
        • url: URL arsip sumber
        • integrity: Checksum Subresource Integrity arsip
        • strip_prefix: Awalan direktori yang akan dihapus saat mengekstrak arsip sumber
        • patches: Peta yang berisi file patch untuk diterapkan ke arsip yang diekstrak. File patch terletak di direktori /modules/$MODULE/$VERSION/patches. Kuncinya adalah nama file patch, dan nilainya adalah checksum integritas file patch
        • patch_strip: Sama dengan argumen --strip dari patch Unix.
        • archive_type: Jenis arsip file yang didownload (Sama seperti type di http_archive). Secara default, jenis arsip ditentukan dari ekstensi file URL. Jika file tidak memiliki ekstensi, Anda dapat menentukan salah satu ekstensi berikut secara eksplisit: "zip", "jar", "war", "aar", "tar", "tar.gz", "tgz", "tar.xz", "txz", "tar.zst", "tzst", tar.bz2, "ar", atau "deb".
      • Jenis dapat diubah untuk menggunakan repositori git, dengan kolom berikut:
        • type: git_repository
        • Kolom berikut seperti yang dijelaskan di https://bazel.build/rules/lib/repo/git:
          • remote
          • commit
          • shallow_since
          • tag
          • init_submodules
          • verbose
          • strip_prefix
      • Jenis dapat diubah untuk menggunakan jalur lokal, yang merepresentasikan repo local_repository, dengan kolom berikut:
        • type: local_path
        • path: Jalur lokal ke repo, dihitung sebagai berikut:
          • Jika path adalah jalur absolut, jalur tersebut akan tetap seperti apa adanya
          • Jika path adalah jalur relatif dan module_base_path adalah jalur absolut, maka akan diselesaikan ke <module_base_path>/<path>
          • Jika path dan module_base_path adalah jalur relatif, maka akan diselesaikan ke <registry_path>/<module_base_path>/<path>. Registry harus dihosting secara lokal dan digunakan oleh --registry=file://<registry_path>. Jika tidak, Bazel akan menampilkan error
    • patches/: Direktori opsional yang berisi file patch, hanya digunakan saat source.json memiliki jenis "archive"

metadata.json

metadata.json adalah file JSON opsional yang berisi informasi tentang modul, dengan kolom berikut:

  • versions: Array string, yang masing-masing menunjukkan versi modul yang tersedia di registry ini. Array ini harus cocok dengan turunan dari direktori modul.
  • yanked_versions: Objek JSON yang menentukan versi dibatalkan dari modul ini. Kuncinya harus berupa versi yang akan dibatalkan, dan nilainya harus berupa deskripsi mengapa versi tersebut dibatalkan, idealnya berisi link ke informasi selengkapnya.

Perhatikan bahwa BCR memerlukan informasi lebih lanjut dalam file metadata.json.

source.json

source.json adalah file JSON wajib diisi yang berisi informasi tentang cara mengambil versi tertentu dari sebuah modul. Skema file ini bergantung pada kolom type, yang secara default adalah archive.

  • Jika type adalah archive (default), versi modul ini didukung oleh aturan repo http_archive; versi ini diambil dengan mendownload arsip dari URL tertentu dan mengekstrak isinya. API ini mendukung kolom berikut:
    • url: String, URL arsip sumber
    • mirror_urls: Daftar string, URL duplikat arsip sumber. URL dicoba secara berurutan setelah url sebagai cadangan.
    • integrity: String, checksum [Subresource Integrity][subresource-integrity] arsip
    • strip_prefix: String, awalan direktori yang akan dihapus saat mengekstrak arsip sumber
    • overlay: Objek JSON yang berisi file overlay untuk ditumpuk di atas arsip yang diekstrak. File patch terletak di direktori /modules/$MODULE/$VERSION/overlay. Kuncinya adalah nama file overlay, dan nilainya adalah checksum integritas file overlay. Overlay diterapkan sebelum file patch.
    • patches: Objek JSON yang berisi file patch untuk diterapkan ke arsip yang diekstrak. File patch terletak di direktori /modules/$MODULE/$VERSION/patches. Kuncinya adalah nama file patch, dan nilainya adalah checksum integritas file patch. Patch diterapkan setelah file overlay.
    • patch_strip: Angka; sama dengan argumen --strip dari Unix patch.
    • archive_type: String, jenis arsip file yang didownload (Sama dengan type di http_archive).
  • Jika type adalah git_repository, versi modul ini didukung oleh aturan repo git_repository; versi ini diambil dengan meng-clone repositori Git.
    • Kolom berikut didukung, dan diteruskan langsung ke aturan repositori git_repository yang mendasarinya: remote, commit, shallow_since, tag, init_submodules, verbose, dan strip_prefix.
  • Jika type adalah local_path, versi modul ini didukung oleh aturan repo local_repository; modul ini ditautkan secara simbolis ke direktori di disk lokal. Kolom ini mendukung berikut:
    • path: Jalur lokal ke repo, dihitung sebagai berikut:
      • Jika path adalah jalur absolut, jalur tersebut akan tetap seperti apa adanya
      • Jika path adalah jalur relatif dan module_base_path adalah jalur absolut, maka akan diselesaikan ke <module_base_path>/<path>
      • Jika path dan module_base_path adalah jalur relatif, maka akan diselesaikan ke <registry_path>/<module_base_path>/<path>. Registry harus dihosting secara lokal dan digunakan oleh --registry=file://<registry_path>. Jika tidak, Bazel akan menampilkan error

Bazel Central Registry

Bazel Central Registry (BCR) di https://bcr.bazel.build/ adalah indeks registry dengan konten yang didukung oleh repo GitHub bazelbuild/bazel-central-registry. Anda dapat menjelajahi isinya menggunakan frontend web di https://registry.bazel.build/.

Komunitas Bazel mengelola BCR, dan kontributor dipersilakan untuk mengirimkan permintaan pull. Lihat panduan kontribusi BCR.

Selain mengikuti format registry indeks normal, BCR memerlukan file presubmit.yml untuk setiap versi modul (/modules/$MODULE/$VERSION/presubmit.yml). File ini menentukan beberapa target build dan pengujian penting yang dapat Anda gunakan untuk memeriksa validitas versi modul ini. Pipeline CI BCR juga menggunakan ini untuk memastikan interoperabilitas antar-modul.

Memilih registry

Flag Bazel yang dapat diulang --registry dapat digunakan untuk menentukan daftar registry untuk meminta modul, sehingga Anda dapat menyiapkan project untuk mengambil dependensi dari registry pihak ketiga atau internal. Pendaftaran sebelumnya lebih diutamakan. Untuk mempermudah, Anda dapat menempatkan daftar tanda --registry di file .bazelrc project Anda.

Jika registri Anda dihosting di GitHub (misalnya, sebagai fork dari bazelbuild/bazel-central-registry), maka nilai --registry Anda memerlukan alamat GitHub mentah di raw.githubusercontent.com. Misalnya, di cabang main fork my-org, Anda akan menetapkan --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/.

Menggunakan tanda --registry akan menghentikan penggunaan Bazel Central Registry secara default, tetapi Anda dapat menambahkannya kembali dengan menambahkan --registry=https://bcr.bazel.build.