Lockfile Bazel

Fitur lockfile di Bazel memungkinkan perekaman versi atau dependensi tertentu dari library atau paket software yang diperlukan oleh project. Hal ini dicapai dengan menyimpan hasil resolusi modul dan evaluasi ekstensi. File kunci mempromosikan 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, modul 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 lockfile tetap fokus pada kumpulan dependensi tertentu yang diperlukan untuk build saat ini, sehingga memberikan representasi akurat dari dependensi project yang telah diselesaikan.

Penggunaan File Kunci

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 tidak ada, informasi tersebut akan ditambahkan ke file kunci. Dalam mode ini, Bazel juga menghindari pembaruan informasi yang dapat diubah, seperti versi yang ditarik, untuk dependensi yang belum berubah.
• refresh: Seperti update, tetapi informasi yang dapat diubah selalu diperbarui saat beralih ke mode ini dan kira-kira setiap jam saat dalam mode ini.
• error: Seperti update, tetapi jika ada informasi yang tidak ada atau sudah tidak berlaku, Bazel akan gagal dengan error. Mode ini tidak pernah mengubah lockfile atau melakukan permintaan jaringan selama resolusi. Ekstensi modul yang menandai dirinya sebagai reproducible mungkin masih melakukan permintaan jaringan, tetapi diharapkan selalu menghasilkan hasil yang sama.
• off: File kunci tidak diperiksa atau diperbarui.

Manfaat File Kunci

Lockfile ini menawarkan beberapa manfaat dan dapat digunakan dengan berbagai cara:

• Build yang dapat direproduksi. Dengan mengambil versi atau dependensi library software tertentu, file kunci 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. File kunci memungkinkan Bazel menghindari download file registry yang sudah digunakan dalam build sebelumnya. Hal ini meningkatkan efisiensi build secara signifikan, terutama dalam skenario yang memerlukan waktu lama.

• Stabilitas dan pengurangan risiko. File kunci membantu mempertahankan stabilitas dengan mencegah update yang tidak terduga atau perubahan yang menyebabkan gangguan di library eksternal. Dengan mengunci dependensi ke versi tertentu, risiko munculnya bug akibat update yang tidak kompatibel atau belum diuji akan berkurang.

Konten File Kunci

File kunci berisi semua informasi yang diperlukan untuk menentukan apakah status project telah berubah. Studi kasus juga mencakup hasil pembuatan project dalam status saat ini. Lockfile terdiri dari dua bagian utama:

1. Hash dari semua file jarak jauh yang merupakan input untuk resolusi modul.
2. Untuk setiap ekstensi modul, lockfile menyertakan input yang memengaruhinya, yang diwakili oleh bzlTransitiveDigest, usagesDigest, dan kolom lainnya, serta output dari menjalankan ekstensi tersebut, yang disebut sebagai generatedRepoSpecs

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. Perhatikan bahwa hal ini juga memerlukan perekaman saat registry tertentu tidak berisi modul tertentu, tetapi registry dengan prioritas yang lebih rendah melakukannya (lihat entri "not found" dalam contoh). Informasi yang dapat diubah secara inheren ini dapat diperbarui melalui bazel mod deps --lockfile_mode=refresh.

Bazel menggunakan hash dari lockfile untuk mencari file registry di cache repositori sebelum mendownloadnya, sehingga mempercepat resolusi berikutnya.

Versi yang Ditarik 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:

1. bzlTransitiveDigest adalah ringkasan implementasi ekstensi dan file .bzl yang dimuat secara transitif olehnya.
2. usagesDigest adalah ringkasan penggunaan ekstensi dalam grafik dependensi, yang mencakup semua tag.
3. Kolom yang tidak ditentukan lebih lanjut yang melacak input lain ke ekstensi, seperti konten file atau direktori yang dibaca atau variabel lingkungan yang digunakan.
4. generatedRepoSpecs mengenkode repositori yang dibuat oleh ekstensi dengan input saat ini.
5. Kolom moduleExtensionMetadata opsional berisi metadata yang disediakan oleh ekstensi, seperti apakah repositori tertentu yang dibuatnya harus diimpor melalui use_repo oleh modul root. Informasi ini mendukung perintah bazel 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 file kunci dalam kontrol versi untuk memfasilitasi kolaborasi dan memastikan bahwa semua anggota tim memiliki akses ke file kunci yang sama, sehingga mempromosikan 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 file kunci. Karena Bazel itu sendiri adalah dependensi build Anda, file kunci bersifat khusus untuk versi Bazel, dan akan berubah bahkan di antara rilis Bazel yang kompatibel dengan versi sebelumnya. Penggunaan bazelisk akan memastikan bahwa semua developer menggunakan versi Bazel yang cocok dengan file kunci.

Dengan mengikuti praktik terbaik ini, Anda dapat menggunakan fitur lockfile secara efektif di Bazel, sehingga menghasilkan alur kerja pengembangan software yang lebih efisien, andal, dan kolaboratif.