Panduan Migrasi Bzlmod

Laporkan masalah Lihat sumber Per Malam · 7,2 · 7,1 · 7,0 · 6,5 · 6,4

Karena kekurangan WORKSPACE, Bzlmod akan menggantikan sistem WORKSPACE yang lama dalam rilis Bazel mendatang. Panduan ini membantu Anda memigrasikan project Anda ke Bzlmod dan melepaskan WORKSPACE untuk mengambil data eksternal dependensi.

WORKSPACE vs Bzlmod

WORKSPACE dan Bzlmod Bazel menawarkan fitur serupa dengan sintaks yang berbeda. Ini menjelaskan cara bermigrasi dari fungsi WORKSPACE tertentu ke Bzlmod.

Menentukan root ruang kerja Bazel

File WORKSPACE menandai {i>root<i} sumber dari proyek Bazel, tanggung jawab ini MODULE.bazel dalam versi 6.3 dan yang lebih baru. Dengan versi Bazel sebelum 6.3, masih harus ada file WORKSPACE atau WORKSPACE.bazel di root ruang kerja Anda, mungkin dengan komentar seperti:

• Ruang Kerja

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

Mengaktifkan Bzlmod di bazelrc

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

• .bazelrc

  # Enable Bzlmod for every Bazel command
  common --enable_bzlmod
  

Tentukan nama repositori untuk ruang kerja Anda

• Ruang Kerja

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

  ## WORKSPACE
  workspace(name = "com_foo_bar")
  

• Bzlmod

  Sebaiknya rujuk target di ruang kerja yang sama dengan Sintaksis //foo:bar tanpa @<repo name>. Tetapi jika Anda memang membutuhkan {i>syntax<i} lama , Anda dapat menggunakan nama modul yang ditentukan oleh Fungsi module sebagai repositori nama. Jika nama modul berbeda dengan nama repositori yang diperlukan, Anda dapat menggunakan atribut repo_name 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 proyek Bazel, Anda seharusnya dapat bergantung padanya sebagai modul Bazel saat juga mengadopsi Bzlmod.

• Ruang Kerja

  Dengan WORKSPACE, adalah hal yang umum untuk menggunakan http_archive atau git_repository aturan repositori untuk unduh sumber proyek 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 Anda lihat, ini adalah pola umum yang diperlukan pengguna untuk memuat dependensi dari makro dependensi. Asumsikan baik bazel_skylib maupun rules_java bergantung pada platform, versi yang tepat dari platform dependensi ditentukan oleh urutan makro.

• Bzlmod

  Dengan Bzlmod, selama dependensi Anda tersedia di Bazel Central Registry atau Bazel kustom Anda registry, Anda cukup mengandalkannya 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 MVS. Oleh karena itu, nilai maksimum versi yang diperlukan dari platform dipilih secara otomatis.

Mengganti dependensi sebagai modul Bazel

Sebagai modul {i>root<i}, Anda bisa mengganti dependensi modul Bazel dengan cara cara.

Baca bagian mengganti untuk informasi selengkapnya tidak akurat atau tidak sesuai.

Anda dapat menemukan beberapa contoh penggunaan di contoh repositori resource.

Mengambil dependensi eksternal dengan ekstensi modul

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

• Ruang Kerja

  Mendownload file menggunakan http_file aturan repositori.

  ## 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 harus memindahkan definisi ke dalam file .bzl, yang juga memungkinkan Anda berbagi 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",
      )
  

  Implementasikan ekstensi modul untuk memuat makro dependensi. Anda dapat menentukan dalam file makro .bzl yang sama, tetapi untuk menjaga kompatibilitas dengan versi Bazel 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 bisa menyediakan makro yang memperkenalkan repositori eksternal berdasarkan input dari pemanggilnya. Tetapi bagaimana jika ada beberapa pemanggil di grafik dependensi dan mereka menyebabkan konflik?

Asumsikan 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
    )

• Ruang Kerja

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

  ## 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 dengan hati-hati WORKSPACE untuk mendapatkan versi yang mereka butuhkan. Ini adalah salah satu masalah terbesar WORKSPACE karena tidak memberikan cara yang masuk akal untuk menyelesaikan dependensi.

• Bzlmod

  Dengan Bzlmod, penulis project foo dapat menggunakan ekstensi modul untuk me-resolve konflik. Misalnya, mari kita asumsikan masuk akal untuk selalu memilih versi dependensi data maksimal yang diperlukan di antara semua modul Bazel.

  ## 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 dependensi bar memerlukan 3.0. Ekstensi modul di foo dapat dengan benar menyelesaikan konflik ini dan otomatis memilih versi 3.0 untuk data dependensi.

Mengintegrasikan pengelola paket pihak ketiga

Setelah bagian terakhir, karena ekstensi modul memberikan cara untuk mengumpulkan informasi dari grafik dependensi, jalankan logika kustom untuk dependensi dan aturan repositori panggilan untuk memperkenalkan repositori eksternal, menyediakan 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 sudah mengadopsi Bzlmod untuk mengambil dependensi dari berbagai pengelola paket:

• rules_jvm_external
• rules_go
• rules_python

Contoh minimal yang mengintegrasikan pengelola paket semu tersedia di contoh repositori resource.

Mendeteksi toolchain di mesin host

Ketika aturan build Bazel perlu mendeteksi toolchain yang tersedia di host Anda mereka menggunakan aturan repositori untuk memeriksa komputer {i>host<i} dan menghasilkan info toolchain sebagai repositori eksternal.

• Ruang Kerja

  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 dalam bagian.

  ## 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"),
  )
  

  Lalu gunakan ekstensi di 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")
  

Daftarkan toolchain & platform eksekusi

Setelah bagian terakhir, memperkenalkan repositori yang menghosting toolchain informasi tambahan (mis. local_config_sh), Anda mungkin ingin mendaftarkan Rantai Alat (Toolchain).

• Ruang Kerja

  Dengan WORKSPACE, Anda dapat mendaftarkan toolchain dengan cara berikut.

  1. Anda dapat mendaftarkan toolchain file .bzl dan memuat makro di 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, register_toolchains dan register_execution_platforms API 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 file MODULE.bazel setiap modul Bazel akan mengikuti urutan prioritas selama pemilihan toolchain (dari tertinggi ke terendah):

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

Memperkenalkan repositori lokal

Anda mungkin perlu memperkenalkan dependensi sebagai repositori lokal dari dependensi untuk proses debug atau Anda ingin menyertakan di ruang kerja Anda sebagai repositori eksternal.

• Ruang Kerja

  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 ke 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 perangkat itu harus memiliki file MODULE.bazel dan dependensi transitif dipertimbangkan selama dependensi resolusi. Selain itu, semua direktif 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 membenarkan semua aturan repositori native (periksa #18285 untuk progres). Kemudian, Anda dapat memanggil local_repository starlark yang sesuai dalam modul . Juga mudah untuk menerapkan versi khusus dari local_repository aturan repositori jika ini merupakan masalah pemblokiran untuk Anda.

Mengikat target

Aturan bind di WORKSPACE tidak digunakan lagi dan tidak didukung di Bzlmod. Diperkenalkan untuk memberikan alias pada target di paket khusus //external. Semua pengguna, bergantung pada setelan 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 memigrasikan dari data ini dengan:

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

• Atau gunakan aturan build alias

  • Tentukan target berikut dalam sebuah 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-lib.

Migrasi

Bagian ini memberikan informasi dan panduan yang berguna untuk migrasi Bzlmod {i>checkout<i}.

Mengetahui dependensi Anda di WORKSPACE

Langkah pertama migrasi adalah memahami dependensi apa yang Anda miliki. Ini mungkin sulit untuk mencari tahu dependensi apa yang sebenarnya diperkenalkan dalam WORKSPACE karena dependensi transitif sering dimuat dengan *_deps makro.

Memeriksa dependensi eksternal dengan file Workspace yang diselesaikan

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

Cara ini dapat digunakan dengan dua cara:

1. Untuk mengambil info dependensi eksternal yang diperlukan guna membangun 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 WORKSPACE, yang meliputi:

   • bind penggunaan
   • register_toolchains & register_execution_platforms penggunaan

   Namun, jika proyek Anda lintas platform, sinkronisasi bazel bisa rusak pada platform karena beberapa aturan repositori hanya dapat berjalan dengan benar pada di seluruh platform Google.

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

Memeriksa dependensi eksternal dengan bazel query

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

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

Meskipun lebih nyaman dan jauh lebih cepat, kueri bazel dapat berbohong tentang versi dependensi eksternal, Jadi, berhati-hatilah saat menggunakannya! Membuat kueri dan memeriksa item eksternal dependensi dengan Bzlmod akan dicapai dengan subperintah.

Dependensi default bawaan

Jika Anda memeriksa file yang dibuat oleh --experimental_repository_resolved_file, Anda akan menemukan banyak dependensi yang tidak didefinisikan di WORKSPACE Anda. Hal ini karena Bazel sebenarnya menambahkan awalan dan akhiran ke WORKSPACE pengguna untuk menginjeksikan beberapa dependensi {i>default<i}, yang biasanya diperlukan oleh aturan native (misalnya @bazel_tools, @platforms, dan @remote_java_tools). Dengan {i>Bzlmod<i}, dependensi tersebut diperkenalkan dengan modul bawaan bazel_tools , yang merupakan dependensi default untuk setiap Modul Bazel.

Mode campuran untuk migrasi bertahap

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

WORKSPACE.bzlmod

Selama migrasi, pengguna Bazel mungkin perlu beralih antara build dengan dan tanpa mengaktifkan Bzlmod. Dukungan WORKSPACE.bzlmod diimplementasikan untuk membuat dan proses berjalan lebih lancar.

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

• WORKSPACE.bzlmod berlaku dan konten WORKSPACE diabaikan.
• Tidak ada awalan atau akhiran yang ditambahkan ke file {i>WORKSPACE.bzlmod<i}.

Menggunakan file WORKSPACE.bzlmod dapat membuat migrasi lebih mudah karena:

• Ketika Bzlmod dinonaktifkan, Anda akan kembali mengambil dependensi dari file WORKSPACE asli.
• Ketika {i>Bzlmod<i} diaktifkan, Anda dapat melacak dependensi apa yang tersisa untuk bermigrasi dengan WORKSPACE.bzlmod.

Catatan: WORKSPACE.bzlmod TIDAK menggantikan fungsi WORKSPACE untuk mengidentifikasi root ruang kerja, oleh karena itu Anda masih memerlukan file WORKSPACE di root ruang kerja Anda.

Visibilitas repositori

{i>Bzlmod<i} dapat mengontrol repositori lain mana yang terlihat dari sebuah repositori, periksa nama repositori dan dependensi untuk mengetahui detail selengkapnya.

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

	Dari repo utama	Dari repositori modul Bazel	Dari repositori ekstensi modul	Dari repositori WORKSPACE
Repositori utama	Dapat dilihat	Jika modul root merupakan dependensi langsung	Jika modul root adalah dependensi langsung dari modul yang menghosting ekstensi modul	Dapat dilihat
Repositori modul Bazel	Dependensi langsung	Dependensi langsung	Dependensi langsung dari modul yang menghosting ekstensi modul	Dependensi langsung dari modul root
Repositori ekstensi modul	Dependensi langsung	Dependensi langsung	Dependensi langsung dari modul yang menghosting ekstensi modul + semua repositori yang dibuat oleh ekstensi modul yang sama	Dependensi langsung dari modul root
Repositori WORKSPACE	Semua terlihat	Tidak terlihat	Tidak terlihat	Semua terlihat

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

Catatan: Untuk repositori yang dihasilkan ekstensi modul @bar, jika @foo digunakan sebagai nama repositori yang jelas dari repositori lain yang dihasilkan oleh ekstensi modul yang sama dependensi modul yang menghosting ekstensi modul, lalu untuk repositori @bar, @foo merujuk pada kebijakan yang disebut terakhir.

Proses migrasi

Proses migrasi Bzlmod umumnya dapat terlihat seperti ini:

1. Pahami dependensi apa 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. Bangun target Anda dengan Bzlmod diaktifkan dan periksa repositori mana yang tidak ada.
5. Memeriksa definisi repositori yang tidak ada dalam dependensi yang di-resolve .
6. Memperkenalkan dependensi yang hilang sebagai modul Bazel, melalui modul ekstensi, atau tinggalkan di WORKSPACE.bzlmod untuk migrasi nanti.
7. Kembali ke 4 dan ulangi hingga semua dependensi tersedia.

Alat migrasi

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

Skrip melakukan hal-hal berikut:

• Buat dan urai file yang diselesaikan WORKSPACE.
• Mencetak info repositori dari file yang di-resolve dengan cara yang dapat dibaca manusia.
• Jalankan perintah {i>bazel build<i}, deteksi pesan {i>error<i} yang dikenali, dan rekomendasikan bermigrasi.
• Periksa apakah dependensi sudah tersedia di BCR.
• Tambahkan dependensi ke file MODULE.bazel.
• Tambahkan 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 diperbarui karena Bzlmod berkembang, selalu periksa kembali apakah solusi yang direkomendasikan sudah benar.

Memublikasikan modul Bazel

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

Agar dapat memeriksa proyek Anda di BCR, Anda memerlukan URL arsip sumber menyelesaikan proyek tersebut. 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 dengan nilai {i>hash<i}, jadi Anda harus pastikan {i>checksum<i} dari file yang diunduh tidak pernah berubah. Jika URL-nya adalah dari GitHub, silakan buat dan unggah arsip rilis di halaman rilis. GitHub tidak akan menjamin {i>checksum<i} dari arsip sumber yang dihasilkan di permintaan tinggi. Singkatnya, URL dalam bentuk https://github.com/<org>/<repo>/releases/download/... dianggap stabil sedangkan https://github.com/<org>/<repo>/archive/... tidak. Periksa GitHub Checksum Arsip Pemadaman layanan untuk konteks selengkapnya.

• Pastikan hierarki sumber mengikuti tata letak repositori asli.

  Jika repositori Anda sangat besar dan Anda ingin membuat sebuah distribusi arsipkan dengan ukuran lebih kecil dengan menghapus sumber yang tidak diperlukan, buat memastikan bahwa pohon sumber yang dihilangkan adalah {i>subset<i} dari pohon sumber asli. Ini memudahkan pengguna akhir untuk mengganti modul ke non-rilis versi oleh archive_override dan git_override.

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

  Modul pengujian adalah project Bazel dengan WORKSPACE dan MODULE.bazel yang terletak di subdirektori arsip sumber yang bergantung pada modul aktual untuk dipublikasikan. Studi kasus harus berisi contoh atau beberapa pengujian integrasi yang mencakup API paling umum. Periksa modul pengujian untuk mempelajari cara menyiapkannya.

Jika Anda sudah menyiapkan URL arsip sumber, ikuti kontribusi BCR panduan untuk mengirimkan modul Anda ke BCR dengan GitHub Permintaan Pull.

Sangat disarankan untuk menyiapkan opsi Publikasikan ke Aplikasi GitHub BCR untuk repositori untuk mengotomatiskan proses pengiriman modul Anda ke BCR.

Praktik terbaik

Bagian ini mendokumentasikan beberapa praktik terbaik yang harus Anda ikuti untuk meningkatkan untuk mengelola dependensi eksternal Anda.

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

Centang #12835, tempat developer dependensi untuk pengujian harus diambil secara tidak perlu untuk membangun target yang tidak memerlukannya. Sebenarnya ini tidak spesifik Bzlmod, tapi mengikuti praktik ini akan memudahkan Anda dalam menentukan dependensi {i>dev<i} dengan benar.

Menentukan dependensi dev

Anda dapat menetapkan atribut dev_dependency ke benar (true) untuk bazel_dep dan use_extension agar tidak diterapkan ke project dependen. Sebagai modul root, Anda dapat menggunakan Flag --ignore_dev_dependency untuk memverifikasi apakah target Anda masih membangun tanpa dependensi dev.

Progres migrasi komunitas

Anda dapat memeriksa Bazel Central Registry untuk menemukan apakah dependensi Anda sudah tersedia. Jika tidak, silakan bergabung Diskusi GitHub untuk memberi suara positif atau memposting dependensi yang memblokir migrasi Anda.

Laporkan masalah

Lihat daftar masalah GitHub Bazel untuk mengetahui Bzlmod yang diketahui masalah performa. Jangan ragu untuk mengajukan masalah atau permintaan fitur baru yang dapat membantu membuka blokir migrasi Anda!