Karena kekurangan WORKSPACE, Bzlmod akan ganti sistem WORKSPACE lama. File WORKSPACE akan dinonaktifkan oleh 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 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 Fungsimodule
sebagai repositori nama. Jika nama modul berbeda dengan nama repositori yang diperlukan, Anda dapat menggunakan atributrepo_name
fungsimodule
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
ataugit_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
maupunrules_java
bergantung padaplatform
, versi yang tepat dariplatform
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
{i>registry<i}, Anda dapat memperkenalkannya menggunakan
use_repo_rule
atau modul
ekstensi.
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 dapat menggunakan perintah
use_repo_rule
di MODULE.bazel untuk langsung membuat instance repo:## 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", )
Pada dasarnya, hal ini diimplementasikan menggunakan ekstensi modul. Jika Anda ingin melakukan logika yang lebih kompleks daripada hanya memanggil aturan repo, Anda juga dapat menerapkan ekstensi modul sendiri. Anda harus memindahkan definisi menjadi file
.bzl
, yang juga memungkinkan Anda berbagi definisi di 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 dependensibar
memerlukan3.0
. Ekstensi modul difoo
dapat dengan benar menyelesaikan konflik ini dan otomatis memilih versi3.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:
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.
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()
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
danregister_execution_platforms
API hanya tersedia dalam file MODULE.bazel. Anda tidak dapat memanggilnative.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):
- toolchain dan platform eksekusi yang terdaftar di modul root
File
MODULE.bazel
. - toolchain dan platform eksekusi yang terdaftar di
WORKSPACE
atau FileWORKSPACE.bzlmod
. - toolchain dan platform eksekusi yang didaftarkan oleh modul yang dependensi (transitif) modul root.
- jika tidak menggunakan
WORKSPACE.bzlmod
: toolchain yang terdaftar diWORKSPACE
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
dannew_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", )
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 memanggillocal_repository
starlark yang sesuai dalam modul . Selain itu, menjalankan versi kustom darilocal_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
.
Pengambilan versus Sinkronisasi
Perintah pengambilan dan sinkronisasi digunakan untuk mendownload repositori eksternal secara lokal dan menyimpan
mereka diperbarui. Terkadang juga untuk mengizinkan build secara offline menggunakan --nofetch
setelah mengambil semua repositori yang diperlukan untuk build.
Ruang Kerja
Sinkronisasi melakukan pengambilan paksa untuk semua repositori, atau untuk kumpulan repositori yang dikonfigurasi, sedangkan pengambilan hanya digunakan untuk mengambil target.
Bzlmod
Perintah sinkronisasi tidak lagi berlaku, tetapi ambil penawaran berbagai opsi. Anda dapat mengambil target, repositori, sekumpulan repositori yang dikonfigurasi, atau repositori yang terlibat dalam resolusi dependensi dan ekstensi modul Anda. Hasil pengambilan di-cache dan untuk memaksa pengambilan, Anda harus menyertakan
--force
selama proses pengambilan.
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 mengetahui 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:
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
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
penggunaanregister_toolchains
®ister_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 kontenWORKSPACE
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.
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 |
Proses migrasi
Proses migrasi Bzlmod umumnya dapat terlihat seperti ini:
- Pahami dependensi apa yang Anda miliki di WORKSPACE.
- Tambahkan file MODULE.bazel kosong di root project Anda.
- Tambahkan file WORKSPACE.bzlmod kosong untuk mengganti konten file WORKSPACE.
- Bangun target Anda dengan Bzlmod diaktifkan dan periksa repositori mana yang tidak ada.
- Memeriksa definisi repositori yang tidak ada dalam dependensi yang di-resolve .
- Memperkenalkan dependensi yang hilang sebagai modul Bazel, melalui modul ekstensi, atau tinggalkan di WORKSPACE.bzlmod untuk migrasi nanti.
- 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>
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 sedangkanhttps://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
dangit_override
.Sertakan modul pengujian dalam subdirektori yang menguji modul pengujian 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 tidak spesifik Bzlmod, tapi mengikuti praktik ini memudahkan Anda untuk 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
tetap membangun tanpa dependensi
dan penggantian {i>dev<i}.
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!