Modul Bazel

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

Modul Bazel adalah project Bazel yang dapat memiliki beberapa versi, yang masing-masing memublikasikan metadata tentang modul lain yang bergantung padanya. Hal ini analog dengan konsep yang dikenal dalam sistem pengelolaan dependensi lainnya, seperti _artefak_ Maven, _paket_ npm, _modul_ Go, atau _crate_ Cargo.

Modul harus memiliki file MODULE.bazel di root repo-nya. File ini adalah manifes modul, yang mendeklarasikan nama, versi, daftar dependensi langsung, dan informasi lainnya. Untuk contoh dasar:

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

Lihat daftar lengkap petunjuk yang tersedia dalam MODULE.bazel file.

Untuk melakukan resolusi modul, Bazel dimulai dengan membaca file MODULE.bazel modul root, lalu berulang kali meminta file MODULE.bazel dependensi dari registry Bazel hingga menemukan seluruh grafik dependensi.

Secara default, Bazel kemudian memilih satu versi setiap modul untuk digunakan. Bazel merepresentasikan setiap modul dengan repo, dan berkonsultasi lagi dengan registry untuk mempelajari cara menentukan setiap repo.

Format versi

Bazel memiliki ekosistem yang beragam dan project menggunakan berbagai skema pembuatan versi. Yang paling populer adalah SemVer, tetapi ada juga project terkemuka yang menggunakan skema berbeda seperti Abseil, yang versinya berbasis tanggal, misalnya 20210324.2).

Oleh karena itu, Bzlmod mengadopsi versi spesifikasi SemVer yang lebih fleksibel. Perbedaannya meliputi:

  • SemVer menetapkan bahwa bagian "rilis" versi harus terdiri dari 3 segmen: MAJOR.MINOR.PATCH. Di Bazel, persyaratan ini dilonggarkan se hingga memungkinkan jumlah segmen berapa pun.
  • Di SemVer, setiap segmen di bagian "rilis" hanya boleh berupa digit. Di Bazel, hal ini dilonggarkan untuk memungkinkan huruf juga, dan semantik perbandingan cocok dengan "pengenal" di bagian "prerilis".
  • Selain itu, semantik peningkatan versi utama, versi minor, dan versi patch tidak diterapkan.

Versi SemVer yang valid adalah versi modul Bazel yang valid. Selain itu, dua versi SemVer a dan b membandingkan a < b jika dan hanya jika hal yang sama berlaku saat dibandingkan sebagai versi modul Bazel.

Pemilihan versi

Pertimbangkan masalah dependensi berlian, yang merupakan bagian penting dalam ruang pengelolaan dependensi versi. Misalkan Anda memiliki grafik dependensi:

       A 1.0
      /     \
   B 1.0    C 1.1
     |        |
   D 1.0    D 1.1

Versi D mana yang harus digunakan? Untuk menjawab pertanyaan ini, Bzlmod menggunakan algoritma Pemilihan Versi Minimal (MVS) yang diperkenalkan dalam sistem modul Go. MVS mengasumsikan bahwa semua versi baru modul kompatibel dengan versi sebelumnya, sehingga memilih versi tertinggi yang ditentukan oleh dependensi (D 1.1 dalam contoh kita). Versi ini disebut "minimal" karena D 1.1 adalah versi paling awal yang dapat memenuhi persyaratan kita— meskipun D 1.2 atau yang lebih baru ada, kita tidak memilihnya. Penggunaan MVS membuat proses pemilihan versi yang berakurasi tinggi dan dapat direproduksi.

Versi yang ditarik

Registry dapat mendeklarasikan versi tertentu sebagai ditarik jika harus dihindari (seperti untuk kerentanan keamanan). Bazel menampilkan error saat memilih versi modul yang ditarik. Untuk memperbaiki error ini, upgrade ke versi yang lebih baru, tidak ditarik, atau gunakan --allow_yanked_versions flag untuk secara eksplisit mengizinkan versi yang ditarik.

Ganti

Tentukan penggantian dalam file MODULE.bazel untuk mengubah perilaku resolusi modul Bazel. Hanya penggantian modul root yang berlaku—jika modul digunakan sebagai dependensi, penggantiannya akan diabaikan.

Setiap penggantian ditentukan untuk nama modul tertentu, yang memengaruhi semua versinya dalam grafik dependensi. Meskipun hanya penggantian modul root yang berlaku, penggantian tersebut dapat digunakan untuk dependensi transitif yang tidak bergantung langsung pada modul root.

Penggantian versi tunggal

The single_version_override memiliki beberapa tujuan:

  • Dengan atribut version, Anda dapat menyematkan dependensi ke versi tertentu, terlepas dari versi dependensi mana yang diminta dalam grafik dependensi.
  • Dengan atribut registry, Anda dapat memaksa dependensi ini berasal dari registry tertentu, bukan mengikuti proses pemilihan registry normal.
  • Dengan atribut patch*, Anda dapat menentukan kumpulan patch yang akan diterapkan ke modul yang didownload.

Semua atribut ini bersifat opsional dan dapat digabungkan satu sama lain.

Penggantian beberapa versi

A multiple_version_override dapat ditentukan untuk memungkinkan beberapa versi modul yang sama ada bersamaan dalam grafik dependensi yang di-resolve.

Jika ada beberapa versi modul yang sama yang tersisa dalam grafik dependensi, Bazel akan memilih versi yang lebih tinggi dan terdekat yang diizinkan untuk setiap dependensi.

Misalnya, jika versi 1.1, 1.3, 1.5, 1.7, dan 2.0 ada dalam grafik dependensi sebelum resolusi:

  • Penggantian beberapa versi yang mengizinkan 1.3, 1.7, dan 2.0 akan mengupgrade 1.1 ke 1.3, 1.5 ke 1.7, dan versi lainnya tetap sama.
  • Penggantian beberapa versi yang mengizinkan 1.9 dan 2.0 akan menghasilkan error, karena 1.9 tidak ada dalam grafik dependensi sebelum resolusi.

Selain itu, pengguna juga dapat mengganti registry menggunakan registry atribut, mirip dengan penggantian versi tunggal.

Penggantian non-registry

Penggantian non-registry akan menghapus modul sepenuhnya dari resolusi versi. Bazel tidak meminta file MODULE.bazel ini dari registry, tetapi dari repo itu sendiri.

Bazel mendukung penggantian non-registry berikut:

Menentukan repo yang tidak mewakili modul Bazel

Dengan bazel_dep, Anda dapat menentukan repo yang mewakili modul Bazel lainnya. Terkadang ada kebutuhan untuk menentukan repo yang tidak mewakili modul Bazel ; misalnya, repo yang berisi file JSON biasa yang akan dibaca sebagai data.

Dalam hal ini, Anda dapat menggunakan use_repo_rule petunjuk untuk menentukan repo secara langsung dengan memanggil aturan repo. Repo ini hanya akan terlihat oleh modul tempat repo ditentukan.

Di balik layar, hal ini diimplementasikan menggunakan mekanisme yang sama dengan ekstensi modul, yang memungkinkan Anda menentukan repo dengan lebih fleksibel.

Nama repositori dan dependensi ketat

Nama tampak dari repo yang mendukung modul ke dependensi langsungnya secara default adalah nama modulnya, kecuali jika atribut repo_name dari petunjuk bazel_dep menyatakan sebaliknya. Perhatikan bahwa hal ini berarti modul hanya dapat menemukan dependensi langsungnya. Hal ini membantu mencegah gangguan yang tidak disengaja karena perubahan pada dependensi transitif.

Nama kanonis repo yang mendukung modul adalah module_name+version (misalnya, bazel_skylib+1.0.3) atau module_name+ (misalnya, bazel_features+), bergantung pada apakah ada beberapa versi modul dalam seluruh grafik dependensi (lihat multiple_version_override). Perhatikan bahwa format nama kanonis bukanlah API yang harus Anda andalkan dan dapat berubah kapan saja. Daripada melakukan hard code nama kanonis, gunakan cara yang didukung untuk langsung mendapatkannya dari Bazel:

  • Dalam file BUILD dan .bzl files, gunakan Label.repo_name pada instance Label yang dibuat dari string label yang diberikan oleh nama repo yang terlihat, misalnya, Label("@bazel_skylib").repo_name.
  • Saat mencari runfile, gunakan $(rlocationpath ...) atau salah satu library runfile di @bazel_tools//tools/{bash,cpp,java}/runfiles atau, untuk ruleset rules_foo, di @rules_foo//foo/runfiles.
  • Saat berinteraksi dengan Bazel dari alat eksternal seperti IDE atau server bahasa, gunakan perintah bazel mod dump_repo_mapping untuk mendapatkan pemetaan dari nama yang terlihat ke nama kanonis untuk kumpulan repositori tertentu.

Ekstensi modul juga dapat memperkenalkan repo tambahan ke dalam cakupan modul yang terlihat.