BazelCon 2022 akan hadir pada 16-17 November ke New York dan online.
Daftar sekarang.

Mengelola dependensi eksternal dengan Bzlmod

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Bzlmod adalah nama kode dari sistem dependensi eksternal baru yang diperkenalkan di Bazel 5.0. Fitur ini diperkenalkan untuk mengatasi beberapa masalah sistem lama yang tidak dapat diperbaiki secara bertahap; lihat bagian Pernyataan Masalah dalam dokumen desain asli untuk mengetahui detail selengkapnya.

Di Bazel 5.0, Bzlmod tidak diaktifkan secara default; flag --experimental_enable_bzlmod harus ditentukan agar hal berikut dapat diterapkan. Seperti saran nama flag, fitur ini saat ini bersifat eksperimental; API dan perilaku dapat berubah hingga fitur ini diluncurkan secara resmi.

Untuk memigrasikan project Anda ke Bzlmod, ikuti Panduan Migrasi Bzlmod. Anda juga dapat menemukan contoh penggunaan Bzlmod di repositori contoh.

Modul Bazel

Sistem dependensi eksternal berbasis WORKSPACE yang lama berpusat pada repositori (atau repositori), yang dibuat melalui aturan repositori (atau aturan repositori). Meskipun repo masih merupakan konsep penting dalam sistem baru, modul adalah unit inti dependensi.

Modul pada dasarnya adalah project Bazel yang dapat memiliki beberapa versi, yang masing-masing memublikasikan metadata tentang modul lain yang menjadi dependensinya. Ini sama dengan konsep yang sudah dikenal dalam sistem pengelolaan dependensi lainnya: artefak Maven, paket npm, peti Kargo, modul Go, dll.

Modul hanya menentukan dependensinya menggunakan pasangan name dan version, bukan URL tertentu di WORKSPACE. Dependensi tersebut kemudian dicari di registry Bazel; secara default, Bazel Central Registry. Di ruang kerja Anda, setiap modul kemudian diubah menjadi repo.

MODUL.bazel

Setiap versi dari setiap modul memiliki file MODULE.bazel yang mendeklarasikan dependensi dan metadata lainnya. Berikut adalah 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")

File MODULE.bazel harus berada di root direktori ruang kerja (di samping file WORKSPACE). Tidak seperti file WORKSPACE, Anda tidak perlu menentukan dependensi transitif; sebagai gantinya, Anda hanya boleh menentukan dependensi langsung, dan file MODULE.bazel dependensi Anda akan diproses untuk menemukan dependensi transitif secara otomatis.

File MODULE.bazel mirip dengan file BUILD karena tidak mendukung bentuk bentuk kontrol apa pun; serta melarang pernyataan load. Perintah yang didukung file MODULE.bazel adalah:

Format versi

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

Karena alasan ini, Bzlmod mengadopsi versi spesifikasi SemVer yang lebih santai. Perbedaannya meliputi:

  • SemVer menetapkan bahwa "rilis" bagian dari versi tersebut harus terdiri dari 3 segmen: MAJOR.MINOR.PATCH. Di Bazel, persyaratan ini dilonggarkan sehingga sejumlah segmen diizinkan.
  • Di SemVer, setiap segmen dalam "rilis" bagian harus berupa angka saja. Di Bazel, kode ini dilonggarkan untuk memungkinkan penulisan huruf, dan semantik perbandingan cocok dengan bagian "identifier" di "prerelease".
  • Selain itu, semantik terhadap peningkatan versi utama, minor, dan patch tidak diberlakukan. (Namun, lihat tingkat kompatibilitas untuk mengetahui detail tentang cara kami menunjukkan kompatibilitas mundur.)

Setiap versi SemVer yang valid adalah versi modul Bazel yang valid. Selain itu, dua versi SeemVer a dan b membandingkan a < b jika pembekuan yang sama dibandingkan dengan versi modul Bazel.

Resolusi versi

Masalah dependensi diamond merupakan hal penting di ruang pengelolaan dependensi berversi. Misalnya Anda memiliki grafik dependensi berikut:

       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 algoritme Minimal Version Selection (MVS) yang diperkenalkan dalam sistem modul Go. MVS mengasumsikan bahwa semua versi baru modul memiliki kompatibilitas mundur, sehingga hanya memilih versi tertinggi yang ditentukan oleh dependensi mana pun (D 1.1 dalam contoh kita). Disebut "minimal" karena D 1.1 di sini adalah versi minimal yang dapat memenuhi persyaratan kami; meskipun D 1.2 atau yang lebih baru ada, kami tidak memilihnya. Hal ini memiliki manfaat tambahan, yaitu pemilihan versi kesetiaan tinggi dan dapat direproduksi.

Resolusi versi dijalankan secara lokal di mesin Anda, bukan oleh registry.

Tingkat kompatibilitas

Perlu diperhatikan bahwa asumsi MVS&#39 tentang kompatibilitas mundur dapat dilakukan karena cukup memperlakukan versi modul yang tidak kompatibel dengan versi sebelumnya sebagai modul terpisah. Dalam hal SemVer, itu berarti A 1,x dan A 2,x dianggap sebagai modul yang berbeda, dan dapat berdampingan dalam grafik dependensi yang diselesaikan. Hal ini sebaliknya, dimungkinkan oleh fakta bahwa versi utama dienkode dalam jalur paket di Go, sehingga tidak ada konflik waktu kompilasi atau waktu penautan.

Di Bazel, kami tidak memiliki jaminan seperti itu. Jadi, kita memerlukan cara untuk menunjukkan angka "nomor utama" untuk mendeteksi versi yang tidak kompatibel dengan versi sebelumnya. Nomor ini disebut tingkat kompatibilitas, dan ditentukan oleh setiap versi modul dalam perintah module(). Dengan memiliki informasi ini, kita dapat menampilkan error saat mendeteksi bahwa versi modul yang sama dengan tingkat kompatibilitas yang berbeda ada dalam grafik dependensi yang diselesaikan.

Nama repositori

Di Bazel, setiap dependensi eksternal memiliki nama repositori. Terkadang, dependensi yang sama dapat digunakan melalui nama repositori yang berbeda (misalnya, @io_bazel_skylib dan @bazel_skylib berarti Bazel skylib), atau nama repositori yang sama dapat digunakan untuk dependensi yang berbeda dalam project yang berbeda.

Di Bzlmod, repositori dapat dihasilkan oleh modul Bazel dan ekstensi modul. Untuk mengatasi konflik nama repositori, kami menggunakan mekanisme pemetaan repositori di sistem baru. Berikut adalah dua konsep penting:

  • Nama repositori kanonis: Nama repositori unik global untuk setiap repositori. Ini akan menjadi nama direktori tempat repositori berada.
    Dibuat sebagai berikut (Peringatan: format nama kanonis bukanlah API yang harus Anda andalkan, tetapi dapat berubah kapan saja):

    • Untuk repositori modul Bazel: module_name~version
      (Contoh. @bazel_skylib~1.0.3)
    • Untuk repositori ekstensi modul: module_name~version~extension_name~repo_name
      (Contoh. @rules_cc~0.0.1~cc_configure~local_config_cc)
  • Local repositori name: Nama repositori yang akan digunakan dalam file BUILD dan .bzl dalam repo. Dependensi yang sama dapat memiliki nama lokal yang berbeda untuk repo yang berbeda.
    Ditentukan sebagai berikut:

    • Untuk repositori modul Bazel: module_name secara default, atau nama yang ditentukan oleh atribut repo_name dalam bazel_dep.
    • Untuk repositori ekstensi modul: nama repositori yang diperkenalkan melalui use_repo.

Setiap repositori memiliki kamus pemetaan repositori dari dependensi langsungnya, yang merupakan peta dari nama repositori lokal ke nama repositori kanonis. Kami menggunakan pemetaan repositori untuk menentukan nama repositori saat membuat label. Perlu diperhatikan bahwa tidak ada konflik pada nama repositori kanonis dan penggunaan nama repositori lokal dapat ditemukan dengan menguraikan file MODULE.bazel, sehingga konflik dapat dengan mudah ditemukan dan diselesaikan tanpa memengaruhi dependensi lain.

dependensi Strict

Format spesifikasi dependensi baru memungkinkan kami melakukan pemeriksaan yang lebih ketat. Secara khusus, sekarang kami menegakkan bahwa modul hanya dapat menggunakan repo yang dibuat dari dependensi langsungnya. Hal ini membantu mencegah kerusakan yang tidak disengaja dan sulit di-debug saat sesuatu dalam grafik dependensi transitif berubah.

dependensi yang ketat diimplementasikan berdasarkan pemetaan repositori. Pada dasarnya, pemetaan pemetaan untuk setiap repo berisi semua dependensi langsungnya, dan repositori lainnya tidak akan terlihat. Dependensi yang terlihat untuk setiap repositori ditentukan sebagai berikut:

  • Repositori modul Bazel dapat melihat semua repo yang diperkenalkan dalam file MODULE.bazel melalui bazel_dep dan use_repo.
  • Repositori ekstensi modul dapat melihat semua dependensi modul yang terlihat yang menyediakan ekstensi, serta semua repo lainnya yang dihasilkan oleh ekstensi modul yang sama.

Registry

Bzlmod menemukan dependensi dengan meminta informasinya dari registries Bazel. Registry Bazel hanyalah database modul Bazel. Satu-satunya bentuk registry yang didukung adalah registry indeks, yang merupakan direktori lokal atau server HTTP statis yang mengikuti format tertentu. Di masa mendatang, kami berencana menambahkan dukungan untuk registry modul tunggal, yang merupakan repositori git yang berisi sumber dan histori project.

Registry indeks

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

Registry indeks harus mengikuti format di bawah ini:

  • /bazel_registry.json: File JSON yang berisi metadata untuk registry. Saat ini, kunci hanya memiliki satu kunci, mirrors, yang menentukan daftar cermin untuk digunakan bagi arsip sumber.
  • /modules: Direktori yang berisi subdirektori untuk setiap modul dalam registry ini.
  • /modules/$MODULE: Direktori yang berisi subdirektori untuk setiap versi modul ini, serta file berikut:
    • 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 di registry. Perhatikan bahwa ini tidak selalu sama dengan penulis project.
      • versions: Daftar semua versi modul ini yang dapat ditemukan dalam registry ini.
      • yanked_versions: Daftar versi yanked dari modul ini. Saat ini, versi ini tidak memiliki operasi, tetapi di masa mendatang, versi yang ditarik akan dilewati atau menghasilkan error.
  • /modules/$MODULE/$VERSION: Direktori yang berisi file berikut:
    • MODULE.bazel: File MODULE.bazel dari versi modul ini.
    • source.json: File JSON yang berisi informasi tentang cara mengambil sumber versi modul ini, dengan kolom berikut:
      • url: URL arsip sumber.
      • integrity: Checksum Integritas Subresource dari arsip.
      • strip_prefix: Awalan direktori untuk dihilangkan saat mengekstrak arsip sumber.
      • patches: Daftar string, yang masing-masing menamai file patch untuk diterapkan ke arsip yang diekstrak. File patch berada di direktori /modules/$MODULE/$VERSION/patches.
      • patch_strip: Sama seperti argumen --strip dari patch Unix.
    • patches/: Direktori opsional yang berisi file patch.

Registry Pusat Bazel

Bazel Central Registry (BCR) adalah registry indeks yang berada di bcr.bazel.build. Isinya didukung oleh repo GitHub bazelbuild/bazel-central-registry.

BCR dikelola oleh komunitas Bazel; kontributor dapat mengirimkan permintaan penarikan. Lihat Kebijakan dan Prosedur Registry Central Bazel.

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 digunakan untuk memeriksa validitas versi modul ini, dan digunakan oleh pipeline CI BCR' untuk memastikan interoperabilitas antar-modul di BCR.

Memilih registry

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

Ekstensi Modul

Ekstensi modul memungkinkan Anda memperluas sistem modul dengan membaca data input dari modul di seluruh grafik dependensi, menjalankan logika yang diperlukan untuk menyelesaikan dependensi, dan terakhir membuat repo dengan memanggil aturan repo. Fungsinya mirip dengan makro WORKSPACE saat ini, tetapi lebih cocok dalam dunia modul dan dependensi transitif.

Ekstensi modul ditentukan dalam file .bzl, seperti aturan repo atau makro WORKSPACE. Mereka tidak dipanggil secara langsung; melainkan, setiap modul dapat menentukan bagian data yang disebut tag agar dapat dibaca oleh ekstensi. Kemudian, setelah resolusi versi modul selesai, ekstensi modul akan dijalankan. Setiap ekstensi dijalankan satu kali setelah resolusi modul (masih sebelum build benar-benar dilakukan), dan membaca semua tag yang dimilikinya di seluruh grafik dependensi.

          [ A 1.1                ]
          [   * maven.dep(X 2.1) ]
          [   * maven.pom(...)   ]
              /              \
   bazel_dep /                \ bazel_dep
            /                  \
[ B 1.2                ]     [ C 1.0                ]
[   * maven.dep(X 1.2) ]     [   * maven.dep(X 2.1) ]
[   * maven.dep(Y 1.3) ]     [   * cargo.dep(P 1.1) ]
            \                  /
   bazel_dep \                / bazel_dep
              \              /
          [ D 1.4                ]
          [   * maven.dep(Z 1.4) ]
          [   * cargo.dep(Q 1.1) ]

Dalam contoh grafik dependensi di atas, A 1.1 dan B 1.2 adalah modul Bazel; Anda dapat menganggap masing-masing modul sebagai file MODULE.bazel. Setiap modul dapat menentukan beberapa tag untuk ekstensi modul; di sini beberapa di antaranya ditentukan untuk ekstensi "maven", dan beberapa modul ditentukan untuk "cargo". Saat grafik dependensi ini diselesaikan (misalnya, mungkin B 1.2 sebenarnya memiliki bazel_dep pada D 1.3 tetapi diupgrade ke D 1.4 karena C), ekstensi "maven" dijalankan, dan dapat membaca semua tag maven.*, menggunakan informasi di dalamnya untuk menentukan repo mana yang akan dibuat. Demikian juga untuk ekstensi "kargo".

Penggunaan ekstensi

Ekstensi dihosting di modul Bazel itu sendiri, sehingga untuk menggunakan ekstensi di modul, Anda harus menambahkan bazel_dep pada modul tersebut terlebih dahulu, lalu memanggil fungsi bawaan use_extension untuk menyertakannya dalam cakupan. Perhatikan contoh berikut, cuplikan dari file MODULE.bazel untuk menggunakan ekstensi "maven" hipotetis yang ditentukan dalam modul rules_jvm_external:

bazel_dep(name = "rules_jvm_external", version = "1.0")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")

Setelah memasukkan ekstensi ke dalam cakupan, Anda dapat menggunakan sintaksis titik guna menentukan tag untuk ekstensi tersebut. Perhatikan bahwa tag harus mengikuti skema yang ditentukan oleh class tag yang sesuai (lihat definisi ekstensi di bawah). Berikut adalah contoh yang menentukan beberapa tag maven.dep dan maven.pom.

maven.dep(coord="org.junit:junit:3.0")
maven.dep(coord="com.google.guava:guava:1.2")
maven.pom(pom_xml="//:pom.xml")

Jika ekstensi menghasilkan repo yang ingin Anda gunakan dalam modul, gunakan perintah use_repo untuk mendeklarasikannya. Hal ini untuk memenuhi kondisi dependensi yang ketat dan menghindari konflik nama repo lokal.

use_repo(
    maven,
    "org_junit_junit",
    guava="com_google_guava_guava",
)

Repositori yang dihasilkan oleh ekstensi adalah bagian dari API-nya, jadi dari tag yang Anda tentukan, Anda harus mengetahui bahwa ekstensi "maven" akan menghasilkan repo yang disebut "org_junit_junit", dan yang disebut "com_google_guava_guava". Dengan use_repo, Anda dapat secara opsional mengganti namanya dalam cakupan modul Anda, seperti untuk "guava" di sini.

Definisi ekstensi

Ekstensi modul ditentukan mirip dengan aturan repo, menggunakan fungsi module_extension. Keduanya memiliki fungsi implementasi; tetapi meskipun aturan repo memiliki sejumlah atribut, ekstensi modul memiliki sejumlah tag_class, yang masing-masing memiliki sejumlah atribut. Class tag menentukan skema untuk tag yang digunakan oleh ekstensi ini. Melanjutkan contoh ekstensi hipotetis "maven" di atas:

# @rules_jvm_external//:extensions.bzl
maven_dep = tag_class(attrs = {"coord": attr.string()})
maven_pom = tag_class(attrs = {"pom_xml": attr.label()})
maven = module_extension(
    implementation=_maven_impl,
    tag_classes={"dep": maven_dep, "pom": maven_pom},
)

Deklarasi ini memperjelas bahwa tag maven.dep dan maven.pom dapat ditentukan, menggunakan skema atribut yang ditentukan di atas.

Fungsi implementasi ini mirip dengan makro WORKSPACE, tetapi memiliki objek module_ctx, yang memberikan akses ke grafik dependensi dan semua tag terkait. Selanjutnya, fungsi implementasi harus memanggil aturan repo untuk menghasilkan repo:

# @rules_jvm_external//:extensions.bzl
load("//:repo_rules.bzl", "maven_single_jar")
def _maven_impl(ctx):
  coords = []
  for mod in ctx.modules:
    coords += [dep.coord for dep in mod.tags.dep]
  output = ctx.execute(["coursier", "resolve", coords])  # hypothetical call
  repo_attrs = process_coursier(output)
  [maven_single_jar(**attrs) for attrs in repo_attrs]

Dalam contoh di atas, kita membahas semua modul dalam grafik dependensi (ctx.modules), yang masing-masing merupakan objek bazel_module yang kolom tags-nya menampilkan semua tag maven.* pada modul. Kemudian, kami memanggil utilitas Coursier untuk menghubungi Maven dan melakukan penyelesaian. Terakhir, kita menggunakan hasil resolusi untuk membuat sejumlah repo, dengan menggunakan aturan hipotesis maven_single_jarrepo.