Fitur lockfile di Bazel memungkinkan perekaman versi atau dependensi tertentu library software atau paket yang diperlukan oleh project. Hal ini dicapai dengan menyimpan hasil resolusi modul dan evaluasi ekstensi. Lockfile mendukung build yang dapat direproduksi, sehingga memastikan lingkungan pengembangan yang konsisten. Selain itu, atribut ini meningkatkan efisiensi build dengan memungkinkan Bazel melewati bagian proses resolusi yang tidak terpengaruh oleh perubahan dalam dependensi project. Selain itu, file kunci meningkatkan stabilitas dengan mencegah update yang tidak terduga atau perubahan yang merusak di library eksternal, sehingga mengurangi risiko munculnya bug.
Pembuatan Lockfile
File kunci dibuat di root ruang kerja dengan nama
MODULE.bazel.lock
. Library ini dibuat atau diupdate selama proses build,
khususnya setelah resolusi modul dan evaluasi ekstensi. Yang penting, file ini
hanya menyertakan dependensi yang disertakan dalam pemanggilan build
saat ini.
Saat terjadi perubahan pada project yang memengaruhi dependensinya, lockfile akan otomatis diupdate untuk mencerminkan status baru. Hal ini memastikan bahwa file kunci tetap berfokus pada kumpulan dependensi tertentu yang diperlukan untuk build saat ini, sehingga memberikan representasi yang akurat tentang dependensi project yang di-resolve.
Penggunaan Lockfile
File kunci dapat dikontrol oleh tanda
--lockfile_mode
untuk
menyesuaikan perilaku Bazel saat status project berbeda dengan
file kunci. Mode yang tersedia adalah:
update
(Default): Gunakan informasi yang ada dalam file kunci untuk melewati download file registry yang diketahui dan untuk menghindari mengevaluasi ulang ekstensi yang hasilnya masih terbaru. Jika informasi yang hilang, informasi akan ditambahkan ke {i>lockfile<i}. Dalam mode ini, Bazel juga menghindari pembaruan informasi yang dapat diubah, seperti versi yang ditarik, untuk dependensi yang belum berubah.refresh
: Sepertiupdate
, tetapi informasi yang dapat diubah selalu diperbarui saat beralih ke mode ini dan kira-kira setiap jam saat dalam mode ini.error
: Sepertiupdate
, tetapi jika ada informasi yang hilang atau tidak berlaku lagi, Bazel akan gagal dengan error. Mode ini tidak pernah mengubah file kunci atau melakukan permintaan jaringan selama resolusi. Ekstensi modul yang menandainya sebagaireproducible
dapat tetap menjalankan permintaan jaringan, tetapi diperkirakan selalu memberikan hasil yang sama.off
: File kunci tidak diperiksa atau diperbarui.
Manfaat Lockfile
Lockfile ini menawarkan beberapa manfaat dan dapat digunakan dengan berbagai cara:
Build yang dapat direproduksi. Dengan merekam versi atau dependensi library software tertentu, lockfile memastikan bahwa build dapat direproduksi di berbagai lingkungan dan dari waktu ke waktu. Developer dapat mengandalkan hasil yang konsisten dan dapat diprediksi saat mem-build project mereka.
Resolusi inkremental yang cepat. Dengan lockfile ini, Bazel dapat menghindari download file registry yang sudah digunakan di build sebelumnya. Hal ini meningkatkan efisiensi build secara signifikan, terutama dalam skenario yang memerlukan waktu lama.
Stabilitas dan pengurangan risiko. Lockfile membantu menjaga stabilitas dengan mencegah update yang tidak terduga atau perubahan yang dapat menyebabkan gangguan di library eksternal. Dengan mengunci dependensi ke versi tertentu, risiko munculnya bug karena update yang tidak kompatibel atau belum diuji akan berkurang.
Konten File Kunci
Lockfile berisi semua informasi yang diperlukan untuk menentukan apakah status project telah berubah. Hal ini juga mencakup hasil build project dalam status saat ini. Lockfile terdiri dari dua bagian utama:
- Hash dari semua file jarak jauh yang merupakan input ke resolusi modul.
- Untuk setiap ekstensi modul, file kunci menyertakan input yang memengaruhinya,
yang diwakili oleh
bzlTransitiveDigest
,usagesDigest
, dan kolom lainnya, serta output dari ekstensi yang dijalankan, yang disebut sebagaigeneratedRepoSpecs
Berikut adalah contoh yang menunjukkan struktur file kunci, beserta penjelasan untuk setiap bagian:
{
"lockFileVersion": 10,
"registryFileHashes": {
"https://bcr.bazel.build/bazel_registry.json": "8a28e4af...5d5b3497",
"https://bcr.bazel.build/modules/foo/1.0/MODULE.bazel": "7cd0312e...5c96ace2",
"https://bcr.bazel.build/modules/foo/2.0/MODULE.bazel": "70390338... 9fc57589",
"https://bcr.bazel.build/modules/foo/2.0/source.json": "7e3a9adf...170d94ad",
"https://registry.mycorp.com/modules/foo/1.0/MODULE.bazel": "not found",
...
},
"selectedYankedVersions": {
"foo@2.0": "Yanked for demo purposes"
},
"moduleExtensions": {
"//:extension.bzl%lockfile_ext": {
"general": {
"bzlTransitiveDigest": "oWDzxG/aLnyY6Ubrfy....+Jp6maQvEPxn0pBM=",
"usagesDigest": "aLmqbvowmHkkBPve05yyDNGN7oh7QE9kBADr3QIZTZs=",
...,
"generatedRepoSpecs": {
"hello": {
"bzlFile": "@@//:extension.bzl",
...
}
}
}
},
"//:extension.bzl%lockfile_ext2": {
"os:macos": {
"bzlTransitiveDigest": "oWDzxG/aLnyY6Ubrfy....+Jp6maQvEPxn0pBM=",
"usagesDigest": "aLmqbvowmHkkBPve05y....yDNGN7oh7r3QIZTZs=",
...,
"generatedRepoSpecs": {
"hello": {
"bzlFile": "@@//:extension.bzl",
...
}
}
},
"os:linux": {
"bzlTransitiveDigest": "eWDzxG/aLsyY3Ubrto....+Jp4maQvEPxn0pLK=",
"usagesDigest": "aLmqbvowmHkkBPve05y....yDNGN7oh7r3QIZTZs=",
...,
"generatedRepoSpecs": {
"hello": {
"bzlFile": "@@//:extension.bzl",
...
}
}
}
}
}
}
Hash File Registry
Bagian registryFileHashes
berisi hash semua file dari
registry jarak jauh yang diakses selama resolusi modul. Karena algoritma resolusi
sepenuhnya determenistik saat diberi input yang sama dan semua input
jarak jauh di-hash, hal ini memastikan hasil resolusi yang dapat direproduksi sepenuhnya sekaligus
menghindari duplikasi informasi jarak jauh yang berlebihan dalam lockfile. Perlu diperhatikan bahwa
proses ini juga memerlukan pencatatan saat registry tertentu tidak berisi modul
tertentu, tetapi registry dengan prioritas lebih rendah memilikinya (lihat entri "tidak ditemukan" dalam
contoh). Informasi yang dapat diubah secara inheren ini dapat diperbarui melalui
bazel mod deps --lockfile_mode=refresh
.
Bazel menggunakan hash dari file kunci untuk mencari file registry di cache repositori sebelum mendownloadnya, yang mempercepat resolusi berikutnya.
Versi Yanked yang Dipilih
Bagian selectedYankedVersions
berisi versi modul yang ditarik
yang dipilih oleh resolusi modul. Karena hal ini biasanya mengakibatkan error saat mencoba membangun, bagian ini hanya tidak kosong ketika versi yang ditarik diizinkan secara eksplisit melalui --allow_yanked_versions
atau BZLMOD_ALLOW_YANKED_VERSIONS
.
Kolom ini diperlukan karena, dibandingkan dengan file modul, informasi versi yang ditarik
secara inheren dapat diubah sehingga tidak dapat direferensikan oleh hash. Informasi ini
dapat diperbarui melalui bazel mod deps --lockfile_mode=refresh
.
Ekstensi Modul
Bagian moduleExtensions
adalah peta yang hanya menyertakan ekstensi yang digunakan
dalam pemanggilan saat ini atau yang sebelumnya dipanggil, sekaligus mengecualikan ekstensi
yang tidak lagi digunakan. Dengan kata lain, jika ekstensi tidak lagi digunakan
di seluruh grafik dependensi, ekstensi tersebut akan dihapus dari peta
moduleExtensions
.
Jika ekstensi tidak bergantung pada sistem operasi atau jenis arsitektur, bagian ini hanya menampilkan satu entri "umum". Jika tidak, beberapa entri akan disertakan, yang diberi nama berdasarkan OS, arsitektur, atau keduanya, dan setiap entri akan sesuai dengan hasil evaluasi ekstensi berdasarkan spesifikasi tersebut.
Setiap entri dalam peta ekstensi sesuai dengan ekstensi yang digunakan dan diidentifikasi oleh file dan namanya. Nilai yang sesuai untuk setiap entri berisi informasi relevan yang terkait dengan ekstensi tersebut:
bzlTransitiveDigest
adalah ringkasan implementasi ekstensi dan file .bzl yang dimuat secara transitif olehnya.usagesDigest
adalah ringkasan penggunaan ekstensi dalam grafik dependensi yang mencakup semua tag.- Kolom yang tidak ditentukan lebih lanjut yang melacak input lain ke ekstensi, seperti konten file atau direktori yang dibaca atau variabel lingkungan yang digunakan.
generatedRepoSpecs
mengenkode repositori yang dibuat oleh ekstensi dengan input saat ini.- Kolom
moduleExtensionMetadata
opsional berisi metadata yang disediakan oleh ekstensi seperti apakah repositori tertentu yang dibuatnya harus diimpor melaluiuse_repo
oleh modul root. Informasi ini mendukung perintahbazel mod tidy
.
Ekstensi modul dapat memilih untuk tidak disertakan dalam file kunci dengan menetapkan
metadata yang ditampilkan dengan reproducible = True
. Dengan demikian, fungsi tersebut berjanji bahwa
mereka akan selalu membuat repositori yang sama jika diberi input yang sama.
Praktik Terbaik
Untuk memaksimalkan manfaat fitur file kunci, pertimbangkan praktik terbaik berikut:
Perbarui file kunci secara berkala untuk mencerminkan perubahan pada dependensi atau konfigurasi project. Hal ini memastikan bahwa build berikutnya didasarkan pada kumpulan dependensi yang terbaru dan akurat. Untuk mengunci semua ekstensi sekaligus, jalankan
bazel mod deps --lockfile_mode=update
.Sertakan lockfile dalam kontrol versi untuk memfasilitasi kolaborasi dan memastikan semua anggota tim memiliki akses ke lockfile yang sama, sehingga mendukung lingkungan pengembangan yang konsisten di seluruh project.
Gunakan
bazelisk
untuk menjalankan Bazel, dan sertakan file.bazelversion
dalam kontrol versi yang menentukan versi Bazel yang sesuai dengan lockfile. Karena Bazel sendiri merupakan dependensi build Anda, lockfile ini dikhususkan untuk versi Bazel, dan akan berubah bahkan antara rilis Bazel yang kompatibel dengan versi lama. Penggunaanbazelisk
memastikan bahwa semua developer menggunakan versi Bazel yang cocok dengan file kunci.
Dengan mengikuti praktik terbaik ini, Anda dapat memanfaatkan fitur lockfile di Bazel secara efektif, sehingga menghasilkan alur kerja pengembangan software yang lebih efisien, andal, dan kolaboratif.
Konflik Penggabungan
Format lockfile dirancang untuk meminimalkan konflik penggabungan, tetapi masih dapat terjadi.
Resolusi Otomatis
Bazel menyediakan driver penggabungan git kustom untuk membantu menyelesaikan konflik ini secara otomatis.
Siapkan driver dengan menambahkan baris ini ke file .gitattributes
di root
repositori git Anda:
# A custom merge driver for the Bazel lockfile.
# https://bazel.build/external/lockfile#automatic-resolution
MODULE.bazel.lock merge=bazel-lockfile-merge
Kemudian, setiap developer yang ingin menggunakan driver harus mendaftarkannya sekali dengan mengikuti langkah-langkah berikut:
- Instal jq (1.5 atau yang lebih tinggi).
- Jalankan perintah berikut:
jq_script=$(curl https://raw.githubusercontent.com/bazelbuild/bazel/master/scripts/bazel-lockfile-merge.jq)
printf '%s\n' "${jq_script}" | less # to optionally inspect the jq script
git config --global merge.bazel-lockfile-merge.name "Merge driver for the Bazel lockfile (MODULE.bazel.lock)"
git config --global merge.bazel-lockfile-merge.driver "jq -s '${jq_script}' -- %O %A %B > %A.jq_tmp && mv %A.jq_tmp %A"
Resolusi Manual
Konflik penggabungan sederhana di kolom registryFileHashes
dan selectedYankedVersions
dapat diselesaikan secara aman dengan menyimpan semua entri dari kedua sisi
konflik.
Jenis konflik penggabungan lainnya tidak boleh diselesaikan secara manual. Sebagai gantinya:
- Pulihkan status lockfile sebelumnya
melalui
git reset MODULE.bazel.lock && git checkout MODULE.bazel.lock
. - Selesaikan konflik apa pun di file
MODULE.bazel
. - Jalankan
bazel mod deps
untuk memperbarui file kunci.