Panduan Migrasi Bzlmod

Laporkan masalah Lihat sumber Nightly · 8.0 . 7,4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Karena kelemahan WORKSPACE, Bzlmod akan mengganti sistem WORKSPACE lama. File WORKSPACE akan dinonaktifkan secara default di Bazel 8 (akhir 2024) dan akan dihapus di Bazel 9 (akhir 2025). Panduan ini membantu Anda memigrasikan project ke Bzlmod dan menghapus WORKSPACE untuk mengambil dependensi eksternal.

WORKSPACE vs Bzlmod

WORKSPACE dan Bzlmod Bazel menawarkan fitur serupa dengan sintaksis yang berbeda. Bagian ini menjelaskan cara melakukan migrasi dari fungsi WORKSPACE tertentu ke Bzlmod.

Menentukan root ruang kerja Bazel

File WORKSPACE menandai root sumber project Bazel, tanggung jawab ini diganti dengan MODULE.bazel di Bazel versi 6.3 dan yang lebih baru. Dengan versi Bazel sebelum 6.3, masih akan ada file WORKSPACE atau WORKSPACE.bazel di root ruang kerja Anda, mungkin dengan komentar seperti:

• WORKSPACE

  # This file marks the root of the Bazel workspace.
  # See MODULE.bazel for external dependencies setup.
  

Mengaktifkan Bzlmod di bazelrc

.bazelrc memungkinkan Anda menetapkan flag yang berlaku setiap kali menjalankan Bazel. Untuk mengaktifkan Bzlmod, gunakan flag --enable_bzlmod, dan terapkan ke perintah common sehingga berlaku untuk setiap perintah:

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

Menentukan nama repositori untuk ruang kerja Anda

• WORKSPACE

  Fungsi workspace digunakan untuk menentukan nama repositori untuk ruang kerja Anda. Hal ini memungkinkan //foo:bar target di ruang kerja direferensikan sebagai @<workspace name>//foo:bar. Jika tidak ditentukan, nama repositori default untuk ruang kerja Anda adalah __main__.

  ## WORKSPACE
  workspace(name = "com_foo_bar")
  

• Bzlmod

  Sebaiknya referensikan target di ruang kerja yang sama dengan sintaksis //foo:bar tanpa @<repo name>. Namun, jika Anda memerlukan sintaksis lama, Anda dapat menggunakan nama modul yang ditentukan oleh fungsi module sebagai nama repositori. Jika nama modul berbeda dengan nama repositori yang diperlukan, Anda dapat menggunakan atribut repo_name dari fungsi module untuk mengganti nama repositori.

  ## MODULE.bazel
  module(
      name = "bar",
      repo_name = "com_foo_bar",
  )
  

Mengambil dependensi eksternal sebagai modul Bazel

Jika dependensi Anda adalah project Bazel, Anda seharusnya dapat bergantung padanya sebagai modul Bazel jika juga mengadopsi Bzlmod.

• WORKSPACE

  Dengan WORKSPACE, biasanya Anda menggunakan aturan repositori http_archive atau git_repository untuk mendownload sumber project Bazel.

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
  
  http_archive(
      name = "bazel_skylib",
      urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.4.2/bazel-skylib-1.4.2.tar.gz"],
      sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa",
  )
  load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
  bazel_skylib_workspace()
  
  http_archive(
      name = "rules_java",
      urls = ["https://github.com/bazelbuild/rules_java/releases/download/6.1.1/rules_java-6.1.1.tar.gz"],
      sha256 = "76402a50ae6859d50bd7aed8c1b8ef09dae5c1035bb3ca7d276f7f3ce659818a",
  )
  load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains")
  rules_java_dependencies()
  rules_java_toolchains()
  

  Seperti yang dapat Anda lihat, ini adalah pola umum yang mengharuskan pengguna memuat dependensi transitif dari makro dependensi. Anggap bazel_skylib dan rules_java bergantung pada platform, versi persis dependensi platform ditentukan oleh urutan makro.

• Bzlmod

  Dengan Bzlmod, selama dependensi Anda tersedia di Bazel Central Registry atau registry Bazel kustom, Anda cukup bergantung padanya dengan perintah bazel_dep.

  ## MODULE.bazel
  bazel_dep(name = "bazel_skylib", version = "1.4.2")
  bazel_dep(name = "rules_java", version = "6.1.1")
  

  Bzlmod me-resolve dependensi modul Bazel secara transitif menggunakan algoritma MVS. Oleh karena itu, versi platform yang diperlukan secara maksimal akan dipilih secara otomatis.

Mengganti dependensi sebagai modul Bazel

Sebagai modul root, Anda dapat mengganti dependensi modul Bazel dengan cara yang berbeda.

Baca bagian penggantian untuk mengetahui informasi selengkapnya.

Anda dapat menemukan beberapa contoh penggunaan di repositori examples.

Mengambil dependensi eksternal dengan ekstensi modul

Jika dependensi Anda bukan project Bazel atau belum tersedia di registry Bazel, Anda dapat memperkenalkannya menggunakan use_repo_rule atau ekstensi modul.

• WORKSPACE

  Download file menggunakan aturan repositori http_file.

  ## WORKSPACE
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

• Bzlmod

  Dengan Bzlmod, Anda dapat menggunakan perintah use_repo_rule dalam file MODULE.bazel untuk membuat instance repo secara langsung:

  ## MODULE.bazel
  http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  http_file(
      name = "data_file",
      url = "http://example.com/file",
      sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  )
  

  Di balik layar, hal ini diimplementasikan menggunakan ekstensi modul. Jika perlu melakukan logika yang lebih kompleks daripada hanya memanggil aturan repo, Anda juga dapat menerapkan ekstensi modul sendiri. Anda harus memindahkan definisi ke file .bzl, yang juga memungkinkan Anda membagikan definisi antara WORKSPACE dan Bzlmod selama periode migrasi.

  ## repositories.bzl
  load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
  def my_data_dependency():
      http_file(
          name = "data_file",
          url = "http://example.com/file",
          sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      )
  

  Terapkan ekstensi modul untuk memuat makro dependensi. Anda dapat menentukannya dalam file .bzl makro yang sama, tetapi untuk mempertahankan kompatibilitas dengan versi Bazel yang lebih lama, sebaiknya tentukan dalam file .bzl terpisah.

  ## extensions.bzl
  load("//:repositories.bzl", "my_data_dependency")
  def _non_module_dependencies_impl(_ctx):
      my_data_dependency()
  
  non_module_dependencies = module_extension(
      implementation = _non_module_dependencies_impl,
  )
  

  Agar repositori terlihat oleh project root, Anda harus mendeklarasikan penggunaan ekstensi modul dan repositori dalam file MODULE.bazel.

  ## MODULE.bazel
  non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies")
  use_repo(non_module_dependencies, "data_file")
  

Menyelesaikan konflik dependensi eksternal dengan ekstensi modul

Project dapat menyediakan makro yang memperkenalkan repositori eksternal berdasarkan input dari pemanggilnya. Namun, bagaimana jika ada beberapa pemanggil dalam grafik dependensi dan menyebabkan konflik?

Anggap project foo menyediakan makro berikut yang menggunakan version sebagai argumen.

## repositories.bzl in foo {:#repositories.bzl-foo}
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
    http_file(
        name = "data_file",
        url = "http://example.com/file-%s" % version,
        # Omitting the "sha256" attribute for simplicity
    )

• WORKSPACE

  Dengan WORKSPACE, Anda dapat memuat makro dari @foo dan menentukan versi dependensi data yang Anda perlukan. Anggap Anda memiliki dependensi lain @bar, yang juga bergantung pada @foo, tetapi memerlukan versi dependensi data yang berbeda.

  ## WORKSPACE
  
  # Introduce @foo and @bar.
  ...
  
  load("@foo//:repositories.bzl", "data_deps")
  data_deps(version = "2.0")
  
  load("@bar//:repositories.bzl", "bar_deps")
  bar_deps() # -> which calls data_deps(version = "3.0")
  

  Dalam hal ini, pengguna akhir harus menyesuaikan urutan makro di WORKSPACE dengan cermat untuk mendapatkan versi yang mereka butuhkan. Ini adalah salah satu titik masalah terbesar dengan WORKSPACE karena tidak benar-benar memberikan cara yang masuk akal untuk menyelesaikan dependensi.

• Bzlmod

  Dengan Bzlmod, penulis project foo dapat menggunakan ekstensi modul untuk menyelesaikan konflik. Misalnya, asumsikan bahwa selalu memilih versi dependensi data maksimum yang diperlukan di antara semua modul Bazel adalah hal yang wajar.

  ## extensions.bzl in foo
  load("//:repositories.bzl", "data_deps")
  
  data = tag_class(attrs={"version": attr.string()})
  
  def _data_deps_extension_impl(module_ctx):
      # Select the maximal required version in the dependency graph.
      version = "1.0"
      for mod in module_ctx.modules:
          for data in mod.tags.data:
              version = max(version, data.version)
      data_deps(version)
  
  data_deps_extension = module_extension(
      implementation = _data_deps_extension_impl,
      tag_classes = {"data": data},
  )
  

  ## MODULE.bazel in bar
  bazel_dep(name = "foo", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "3.0")
  use_repo(foo_data_deps, "data_file")
  

  ## MODULE.bazel in root module
  bazel_dep(name = "foo", version = "1.0")
  bazel_dep(name = "bar", version = "1.0")
  
  foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
  foo_data_deps.data(version = "2.0")
  use_repo(foo_data_deps, "data_file")
  

  Dalam hal ini, modul root memerlukan versi data 2.0, sedangkan dependensinya bar memerlukan 3.0. Ekstensi modul di foo dapat menyelesaikan konflik ini dengan benar dan secara otomatis memilih versi 3.0 untuk dependensi data.

Mengintegrasikan pengelola paket pihak ketiga

Setelah bagian terakhir, karena ekstensi modul menyediakan cara untuk mengumpulkan informasi dari grafik dependensi, menjalankan logika kustom untuk me-resolve dependensi dan memanggil aturan repositori untuk memperkenalkan repositori eksternal, hal ini memberikan cara yang bagus bagi penulis aturan untuk meningkatkan kumpulan aturan yang mengintegrasikan pengelola paket untuk bahasa tertentu.

Baca halaman ekstensi modul untuk mempelajari lebih lanjut cara menggunakan ekstensi modul.

Berikut adalah daftar kumpulan aturan yang telah mengadopsi Bzlmod untuk mengambil dependensi dari berbagai pengelola paket:

• rules_jvm_external
• rules_go
• rules_python

Contoh minimal yang mengintegrasikan pengelola paket pseudo tersedia di repositori examples.

Mendeteksi toolchain di mesin host

Saat aturan build Bazel perlu mendeteksi toolchain yang tersedia di mesin host, aturan tersebut menggunakan aturan repositori untuk memeriksa mesin host dan membuat info toolchain sebagai repositori eksternal.

• WORKSPACE

  Dengan aturan repositori berikut untuk mendeteksi toolchain shell.

  ## local_config_sh.bzl
  def _sh_config_rule_impl(repository_ctx):
      sh_path = get_sh_path_from_env("SH_BIN_PATH")
  
      if not sh_path:
          sh_path = detect_sh_from_path()
  
      if not sh_path:
          sh_path = "/shell/binary/not/found"
  
      repository_ctx.file("BUILD", """
  load("@bazel_tools//tools/sh:sh_toolchain.bzl", "sh_toolchain")
  sh_toolchain(
      name = "local_sh",
      path = "{sh_path}",
      visibility = ["//visibility:public"],
  )
  toolchain(
      name = "local_sh_toolchain",
      toolchain = ":local_sh",
      toolchain_type = "@bazel_tools//tools/sh:toolchain_type",
  )
  """.format(sh_path = sh_path))
  
  sh_config_rule = repository_rule(
      environ = ["SH_BIN_PATH"],
      local = True,
      implementation = _sh_config_rule_impl,
  )
  

  Anda dapat memuat aturan repositori di WORKSPACE.

  ## WORKSPACE
  load("//:local_config_sh.bzl", "sh_config_rule")
  sh_config_rule(name = "local_config_sh")
  

• Bzlmod

  Dengan Bzlmod, Anda dapat memperkenalkan repositori yang sama menggunakan ekstensi modul, yang mirip dengan memperkenalkan repositori @data_file di bagian terakhir.

  ## local_config_sh_extension.bzl
  load("//:local_config_sh.bzl", "sh_config_rule")
  
  sh_config_extension = module_extension(
      implementation = lambda ctx: sh_config_rule(name = "local_config_sh"),
  )
  

  Kemudian, gunakan ekstensi dalam file MODULE.bazel.

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  

Mendaftarkan toolchain & platform eksekusi

Setelah bagian terakhir, setelah memperkenalkan informasi toolchain hosting repositori (misalnya local_config_sh), Anda mungkin ingin mendaftarkan toolchain.

• WORKSPACE

  Dengan WORKSPACE, Anda dapat mendaftarkan toolchain dengan cara berikut.

  1. Anda dapat mendaftarkan toolchain file .bzl dan memuat makro dalam file WORKSPACE.

     ## local_config_sh.bzl
     def sh_configure():
         sh_config_rule(name = "local_config_sh")
         native.register_toolchains("@local_config_sh//:local_sh_toolchain")
     

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_configure")
     sh_configure()
     

  2. Atau daftarkan toolchain di file WORKSPACE secara langsung.

     ## WORKSPACE
     load("//:local_config_sh.bzl", "sh_config_rule")
     sh_config_rule(name = "local_config_sh")
     register_toolchains("@local_config_sh//:local_sh_toolchain")
     

• Bzlmod

  Dengan Bzlmod, API register_toolchains dan register_execution_platforms hanya tersedia dalam file MODULE.bazel. Anda tidak dapat memanggil native.register_toolchains dalam ekstensi modul.

  ## MODULE.bazel
  sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
  use_repo(sh_config_ext, "local_config_sh")
  register_toolchains("@local_config_sh//:local_sh_toolchain")
  

Toolchain dan platform eksekusi yang terdaftar di WORKSPACE, WORKSPACE.bzlmod, dan setiap file MODULE.bazel modul Bazel mengikuti urutan prioritas ini selama pemilihan toolchain (dari tertinggi ke terendah):

1. toolchain dan platform eksekusi yang terdaftar dalam file MODULE.bazel modul root.
2. toolchain dan platform eksekusi yang terdaftar dalam file WORKSPACE atau WORKSPACE.bzlmod.
3. toolchain dan platform eksekusi yang didaftarkan oleh modul yang merupakan dependensi (transitif) dari modul root.
4. jika tidak menggunakan WORKSPACE.bzlmod: toolchain yang terdaftar di akhiran WORKSPACE.

Memperkenalkan repositori lokal

Anda mungkin perlu memasukkan dependensi sebagai repositori lokal saat memerlukan versi lokal dependensi untuk proses debug atau ingin menggabungkan direktori di ruang kerja sebagai repositori eksternal.

• WORKSPACE

  Dengan WORKSPACE, hal ini dicapai oleh dua aturan repositori native, local_repository dan new_local_repository.

  ## WORKSPACE
  local_repository(
      name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

• Bzlmod

  Dengan Bzlmod, Anda dapat menggunakan local_path_override untuk mengganti modul dengan jalur lokal.

  ## MODULE.bazel
  bazel_dep(name = "rules_java")
  local_path_override(
      module_name = "rules_java",
      path = "/Users/bazel_user/workspace/rules_java",
  )
  

  Catatan: Dengan local_path_override, Anda hanya dapat memperkenalkan direktori lokal sebagai modul Bazel, yang berarti direktori tersebut harus memiliki file MODULE.bazel dan dependensi transitifnya akan dipertimbangkan selama resolusi dependensi. Selain itu, semua perintah penggantian modul hanya dapat digunakan oleh modul root.

  Anda juga dapat memperkenalkan repositori lokal dengan ekstensi modul. Namun, Anda tidak dapat memanggil native.local_repository dalam ekstensi modul, ada upaya berkelanjutan untuk membuat starlark semua aturan repositori native (lihat #18285 untuk mengetahui progresnya). Kemudian, Anda dapat memanggil local_repository starlark yang sesuai dalam ekstensi modul. Anda juga dapat menerapkan versi kustom aturan repositori local_repository dengan mudah jika ini adalah masalah pemblokiran bagi Anda.

Mengikat target

Aturan bind di WORKSPACE tidak digunakan lagi dan tidak didukung di Bzlmod. Ini diperkenalkan untuk memberi target alias dalam paket //external khusus. Semua pengguna yang bergantung pada ini harus bermigrasi.

Misalnya, Anda memiliki

## WORKSPACE
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

Hal ini memungkinkan target lain bergantung pada //external:openssl. Anda dapat bermigrasi dari hal ini dengan:

• Ganti semua penggunaan //external:openssl dengan @my-ssl//src:openssl-lib.

• Atau gunakan aturan build alias

  • Tentukan target berikut dalam paket (misalnya, //third_party)

    ## third_party/BUILD
    alias(
        name = "openssl",
        actual = "@my-ssl//src:openssl-lib",
    )
    

  • Ganti semua penggunaan //external:openssl dengan //third_party:openssl.

Pengambilan versus Sinkronisasi

Perintah pengambilan dan sinkronisasi digunakan untuk mendownload repo eksternal secara lokal dan terus memperbaruinya. Terkadang juga untuk mengizinkan build offline menggunakan flag --nofetch setelah mengambil semua repo yang diperlukan untuk build.

• WORKSPACE

  Sinkronisasi melakukan pengambilan paksa untuk semua repositori, atau untuk kumpulan repositori yang dikonfigurasi tertentu, sedangkan pengambilan hanya digunakan untuk mengambil target tertentu.

• Bzlmod

  Perintah sinkronisasi tidak lagi berlaku, tetapi pengambilan menawarkan berbagai opsi. Anda dapat mengambil target, repositori, kumpulan repo yang dikonfigurasi, atau semua repositori yang terlibat dalam resolusi dependensi dan ekstensi modul. Hasil pengambilan di-cache dan untuk memaksa pengambilan, Anda harus menyertakan opsi --force selama proses pengambilan.

Migrasi

Bagian ini memberikan informasi dan panduan yang berguna untuk proses migrasi Bzlmod Anda.

Mengetahui dependensi Anda di WORKSPACE

Langkah pertama migrasi adalah memahami dependensi yang Anda miliki. Mungkin sulit untuk mengetahui dependensi yang tepat yang diperkenalkan dalam file WORKSPACE karena dependensi transitif sering dimuat dengan makro *_deps.

Memeriksa dependensi eksternal dengan file yang di-resolve ruang kerja

Untungnya, tanda --experimental_repository_resolved_file dapat membantu. Flag ini pada dasarnya menghasilkan "file kunci" dari semua dependensi eksternal yang diambil dalam perintah Bazel terakhir Anda. Anda dapat menemukan detail selengkapnya di postingan blog ini.

Kolom ini dapat digunakan dengan dua cara:

1. Untuk mengambil info dependensi eksternal yang diperlukan untuk mem-build target tertentu.

   bazel clean --expunge
   bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
   

2. Untuk mengambil info semua dependensi eksternal yang ditentukan dalam file WORKSPACE.

   bazel clean --expunge
   bazel sync --experimental_repository_resolved_file=resolved.bzl
   

   Dengan perintah bazel sync, Anda dapat mengambil semua dependensi yang ditentukan dalam file WORKSPACE, yang mencakup:

   • Penggunaan bind
   • Penggunaan register_toolchains & register_execution_platforms

   Namun, jika project Anda bersifat lintas platform, sinkronisasi bazel dapat rusak di platform tertentu karena beberapa aturan repositori mungkin hanya berjalan dengan benar di platform yang didukung.

Setelah menjalankan perintah, Anda akan memiliki informasi dependensi eksternal dalam file resolved.bzl.

Memeriksa dependensi eksternal dengan bazel query

Anda mungkin juga tahu bahwa bazel query dapat digunakan untuk memeriksa aturan repositori dengan

bazel query --output=build //external:<repo name>

Meskipun lebih praktis dan jauh lebih cepat, kueri bazel dapat berbohong tentang versi dependensi eksternal, jadi berhati-hatilah saat menggunakannya. Membuat kueri dan memeriksa dependensi eksternal dengan Bzlmod akan dilakukan oleh subperintah baru.

Dependensi default bawaan

Jika memeriksa file yang dihasilkan oleh --experimental_repository_resolved_file, Anda akan menemukan banyak dependensi yang tidak ditentukan di WORKSPACE. Hal ini karena Bazel sebenarnya menambahkan awalan dan akhiran ke konten file WORKSPACE pengguna untuk memasukkan beberapa dependensi default, yang biasanya diperlukan oleh aturan native (misalnya @bazel_tools, @platforms, dan @remote_java_tools). Dengan Bzlmod, dependensi tersebut diperkenalkan dengan modul bawaan bazel_tools, yang merupakan dependensi default untuk setiap modul Bazel lainnya.

Mode hybrid untuk migrasi bertahap

Bzlmod dan WORKSPACE dapat bekerja secara berdampingan, yang memungkinkan migrasi dependensi dari file WORKSPACE ke Bzlmod menjadi proses bertahap.

Catatan: Dalam praktiknya, memuat makro "*_deps" di WORKSPACE sering kali menyebabkan kebingungan dengan dependensi Bzlmod. Oleh karena itu, sebaiknya mulai dengan file WORKSPACE.bzlmod dan hindari memuat dependensi transitif dengan makro.

WORKSPACE.bzlmod

Selama migrasi, pengguna Bazel mungkin perlu beralih antara build dengan dan tanpa Bzlmod yang diaktifkan. Dukungan WORKSPACE.bzlmod diterapkan untuk membuat proses lebih lancar.

WORKSPACE.bzlmod memiliki sintaksis yang sama persis dengan WORKSPACE. Jika Bzlmod diaktifkan, jika file WORKSPACE.bzlmod juga ada di root ruang kerja:

• WORKSPACE.bzlmod akan diterapkan dan konten WORKSPACE akan diabaikan.
• Tidak ada awalan atau akhiran yang ditambahkan ke file WORKSPACE.bzlmod.

Menggunakan file WORKSPACE.bzlmod dapat mempermudah migrasi karena:

• Jika Bzlmod dinonaktifkan, Anda akan kembali mengambil dependensi dari file WORKSPACE asli.
• Jika Bzlmod diaktifkan, Anda dapat melacak dependensi yang tersisa untuk dimigrasikan dengan WORKSPACE.bzlmod dengan lebih baik.

Visibilitas repositori

Bzlmod dapat mengontrol repositori lain yang terlihat dari repositori tertentu, lihat nama repositori dan dependensi ketat untuk mengetahui detail selengkapnya.

Berikut adalah ringkasan visibilitas repositori dari berbagai jenis repositori saat juga mempertimbangkan WORKSPACE.

	Dari repo utama	Dari repositori modul Bazel	Dari repositori ekstensi modul	Dari repositori WORKSPACE
Repositori utama	Terlihat	Jika modul root adalah dependensi langsung	Jika modul root adalah dependensi langsung dari modul yang menghosting ekstensi modul	Terlihat
Repositori modul Bazel	Dependensi langsung	Dependensi langsung	Dependensi langsung modul yang menghosting ekstensi modul	Dependensi langsung modul root
Repositori ekstensi modul	Dependensi langsung	Dependensi langsung	Dependensi langsung modul yang menghosting ekstensi modul + semua repo yang dihasilkan oleh ekstensi modul yang sama	Dependensi langsung modul root
Repos WORKSPACE	Semua terlihat	Tidak terlihat	Tidak terlihat	Semua terlihat

Catatan: Untuk modul root, jika repositori @foo ditentukan di WORKSPACE dan @foo juga digunakan sebagai nama repositori yang terlihat di MODULE.bazel, maka @foo akan merujuk ke repositori yang diperkenalkan di MODULE.bazel.

Catatan: Untuk repositori @bar yang dihasilkan oleh ekstensi modul, jika @foo digunakan sebagai nama repositori yang terlihat dari repositori lain yang dihasilkan oleh ekstensi modul yang sama dan dependensi langsung modul yang menghosting ekstensi modul, maka untuk repositori @bar, @foo akan merujuk ke repositori yang terakhir.

Proses migrasi

Proses migrasi Bzlmod standar dapat terlihat seperti ini:

1. Memahami dependensi yang Anda miliki di WORKSPACE.
2. Tambahkan file MODULE.bazel kosong di root project Anda.
3. Tambahkan file WORKSPACE.bzlmod kosong untuk mengganti konten file WORKSPACE.
4. Build target Anda dengan Bzlmod yang diaktifkan dan periksa repositori mana yang tidak ada.
5. Periksa definisi repositori yang hilang dalam file dependensi yang di-resolve.
6. Masukkan dependensi yang hilang sebagai modul Bazel, melalui ekstensi modul, atau biarkan di WORKSPACE.bzlmod untuk migrasi nanti.
7. Kembali ke langkah 4 dan ulangi hingga semua dependensi tersedia.

Alat migrasi

Ada skrip bantuan migrasi Bzlmod interaktif yang dapat membantu Anda memulai.

Skrip ini melakukan hal berikut:

• Buat dan uraikan file yang di-resolve WORKSPACE.
• Cetak info repositori dari file yang di-resolve dengan cara yang dapat dibaca manusia.
• Jalankan perintah build bazel, deteksi pesan error yang dikenali, dan rekomendasikan cara untuk bermigrasi.
• Periksa apakah dependensi sudah tersedia di BCR.
• Tambahkan dependensi ke file MODULE.bazel.
• Menambahkan dependensi melalui ekstensi modul.
• Tambahkan dependensi ke file WORKSPACE.bzlmod.

Untuk menggunakannya, pastikan Anda telah menginstal rilis Bazel terbaru, dan jalankan perintah berikut:

git clone https://github.com/bazelbuild/bazel-central-registry.git
cd <your workspace root>
<BCR repo root>/tools/migrate_to_bzlmod.py -t <your build targets>

Catatan: Skrip migrasi tidak sempurna dan mungkin tidak terbaru karena Bzlmod terus berkembang, selalu periksa kembali apakah solusi yang direkomendasikan sudah benar.

Memublikasikan modul Bazel

Jika project Bazel Anda adalah dependensi untuk project lain, Anda dapat memublikasikan project di Bazel Central Registry.

Agar dapat memeriksa project di BCR, Anda memerlukan URL arsip sumber project. Perhatikan beberapa hal saat membuat arsip sumber:

• Pastikan arsip mengarah ke versi tertentu.

  BCR hanya dapat menerima arsip sumber berversi karena Bzlmod perlu melakukan perbandingan versi selama resolusi dependensi.

• Pastikan URL arsip stabil.

  Bazel memverifikasi konten arsip berdasarkan nilai hash, jadi Anda harus memastikan checksum file yang didownload tidak pernah berubah. Jika URL berasal dari GitHub, buat dan upload arsip rilis di halaman rilis. GitHub tidak akan menjamin checksum arsip sumber yang dihasilkan berdasarkan permintaan. Singkatnya, URL dalam bentuk https://github.com/<org>/<repo>/releases/download/... dianggap stabil sedangkan https://github.com/<org>/<repo>/archive/... tidak. Lihat Pemadaman Layanan Checksum Arsip GitHub untuk mengetahui konteks selengkapnya.

• Pastikan hierarki sumber mengikuti tata letak repositori asli.

  Jika repositori Anda sangat besar dan Anda ingin membuat arsip distribusi dengan ukuran yang lebih kecil dengan menghapus sumber yang tidak diperlukan, pastikan hierarki sumber yang dihapus adalah subset dari hierarki sumber asli. Hal ini memudahkan pengguna akhir mengganti modul ke versi non-rilis dengan archive_override dan git_override.

• Sertakan modul pengujian di subdirektori yang menguji API yang paling umum.

  Modul pengujian adalah project Bazel dengan file WORKSPACE dan MODULE.bazel sendiri yang terletak di subdirektori arsip sumber yang bergantung pada modul sebenarnya yang akan dipublikasikan. File ini harus berisi contoh atau beberapa pengujian integrasi yang mencakup API Anda yang paling umum. Lihat modul pengujian untuk mempelajari cara menyiapkannya.

Setelah URL arsip sumber Anda siap, ikuti panduan kontribusi BCR untuk mengirimkan modul Anda ke BCR dengan GitHub Pull Request.

Sebaiknya siapkan Aplikasi GitHub Publish to BCR untuk repositori Anda guna mengotomatiskan proses pengiriman modul ke BCR.

Praktik terbaik

Bagian ini mendokumentasikan beberapa praktik terbaik yang harus Anda ikuti untuk mengelola dependensi eksternal dengan lebih baik.

Pisahkan target ke dalam paket yang berbeda untuk menghindari pengambilan dependensi yang tidak perlu.

Periksa #12835, tempat dependensi dev untuk pengujian dipaksa diambil tanpa perlu untuk mem-build target yang tidak memerlukannya. Hal ini sebenarnya tidak khusus untuk Bzlmod, tetapi mengikuti praktik ini akan mempermudah untuk menentukan dependensi developer dengan benar.

Menentukan dependensi developer

Anda dapat menetapkan atribut dev_dependency ke true untuk direktif bazel_dep dan use_extension sehingga direktif tersebut tidak diterapkan ke project dependen. Sebagai modul root, Anda dapat menggunakan flag --ignore_dev_dependency untuk memverifikasi apakah target masih di-build tanpa dependensi dan penggantian developer.

Progres migrasi komunitas

Anda dapat memeriksa Bazel Central Registry untuk mengetahui apakah dependensi Anda sudah tersedia. Jika tidak, jangan ragu untuk bergabung dengan diskusi GitHub ini untuk memberikan suara positif atau memposting dependensi yang memblokir migrasi Anda.

Laporkan masalah

Periksa daftar masalah GitHub Bazel untuk mengetahui masalah Bzlmod yang diketahui. Jangan ragu untuk mengajukan masalah baru atau permintaan fitur yang dapat membantu mengatasi masalah migrasi Anda.