Registry Bazel

Bazel menemukan dependensi dengan meminta informasinya dari registry Bazel: database modul Bazel. Bazel hanya mendukung satu jenis registry — registry 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. Perlu diperhatikan bahwa registry indeks tidak perlu menayangkan arsip sumber itu sendiri.

Registry indeks harus memiliki format berikut:

• /bazel_registry.json: File JSON opsional yang berisi metadata untuk registry.
• /modules: Direktori yang berisi subdirektori untuk setiap modul dalam registry ini
• /modules/$MODULE: Direktori yang berisi subdirektori untuk setiap versi modul bernama $MODULE, serta file metadata.json yang berisi metadata untuk modul ini.
• /modules/$MODULE/$VERSION: Direktori yang berisi file berikut:
  • MODULE.bazel: File MODULE.bazel dari versi modul ini. Perhatikan bahwa ini adalah file MODULE.bazel yang dibaca selama resolusi dependensi eksternal Bazel, bukan file dari arsip sumber (kecuali jika ada penggantian non-registry). Perhatikan juga bahwa sebaiknya gunakan file ini untuk menetapkan versi rilis dan hindari melakukannya di file MODULE.bazel arsip sumber. Untuk mempelajari versi modul lebih lanjut, lihat FAQ.
  • source.json: File JSON yang berisi informasi tentang cara mengambil sumber versi modul ini
  • patches/: Direktori opsional yang berisi file patch, hanya digunakan jika source.json memiliki jenis "archive"
  • overlay/: Direktori opsional yang berisi file overlay, hanya digunakan jika source.json memiliki jenis "archive"

bazel_registry.json

bazel_registry.json adalah file opsional yang menentukan metadata yang berlaku untuk seluruh registry. File ini dapat berisi kolom berikut:

• mirrors: array string, yang menentukan daftar mirror yang akan digunakan untuk arsip sumber.
  • URL mirror adalah gabungan dari mirror itu sendiri, dan URL sumber modul yang ditentukan oleh file source.json 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 asli itu sendiri https://foo.com/bar/baz.
• module_base_path: string, yang menentukan jalur dasar untuk modul dengan jenis local_path dalam file source.json

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 direktori modul.
• yanked_versions: Objek JSON yang menentukan versi yanked dari modul ini. Kunci harus berupa versi yang akan di-yank, dan nilainya harus berupa deskripsi alasan versi tersebut di-yank, sebaiknya berisi link ke informasi selengkapnya.

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

source.json

source.json adalah file JSON yang diperlukan dan berisi informasi tentang cara mengambil versi modul tertentu. 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 kontennya. Kolom berikut didukung:
  • url: String, URL arsip sumber
  • mirror_urls: Daftar string, URL mirror arsip sumber. URL dicoba secara berurutan setelah url sebagai cadangan.
  • integrity: String, checksum Subresource Integrity dari arsip
  • strip_prefix: String, awalan direktori yang akan dihapus saat mengekstrak arsip sumber
  • overlay: Objek JSON yang berisi file overlay untuk ditambahkan ke arsip yang diekstrak. File patch terletak di direktori /modules/$MODULE/$VERSION/overlay. Kunci 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. Kunci adalah nama file patch, dan nilainya adalah checksum integritas file patch. Patch diterapkan setelah file overlay dan dalam urutan yang muncul di patches.
  • 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 repo 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; versi ini di-symlink ke direktori di disk lokal. Kolom berikut didukung:
  • path: Jalur lokal ke repo, dihitung sebagai berikut:
    • Jika path adalah jalur absolut, jalur tersebut akan tetap seperti itu
    • Jika path adalah jalur relatif dan module_base_path adalah jalur absolut, jalur tersebut akan di-resolve ke <module_base_path>/<path>
    • Jika path dan module_base_path adalah jalur relatif, jalur tersebut akan di-resolve 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 registry indeks dengan konten yang didukung oleh repo GitHub bazelbuild/bazel-central-registry. Anda dapat menjelajahi kontennya menggunakan frontend web di https://registry.bazel.build/.

Komunitas Bazel mengelola BCR, dan kontributor dapat 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 file ini untuk memastikan interoperabilitas antar-modul.

Memilih registry

Flag Bazel yang dapat diulang --registry dapat digunakan untuk menentukan daftar registry tempat meminta modul, sehingga Anda dapat menyiapkan project untuk mengambil dependensi dari registry pihak ketiga atau internal. Registry sebelumnya akan diprioritaskan. Untuk memudahkan, Anda dapat menempatkan daftar flag --registry di file .bazelrc project.

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

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