Lockfile Bazel

Laporkan masalah Lihat sumber Nightly · 7.4 .

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 proses resolusi saat tidak ada perubahan pada dependensi project. Selain itu, lockfile meningkatkan stabilitas dengan mencegah update yang tidak terduga atau perubahan yang dapat menyebabkan gangguan di library eksternal, sehingga mengurangi risiko timbulnya bug.

Pembuatan File Kunci

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. Lockfile mengambil status project saat ini, termasuk file MODULE, flag, penggantian, dan informasi relevan lainnya. Yang penting, file ini hanya menyertakan dependensi yang disertakan dalam pemanggilan build saat ini.

Saat perubahan terjadi dalam project yang memengaruhi dependensinya, file kunci akan otomatis diperbarui 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 Lockfile

Lockfile dapat dikontrol oleh flag --lockfile_mode untuk menyesuaikan perilaku Bazel saat status project berbeda dengan lockfile. Mode yang tersedia adalah:

  • update (Default): Jika status project cocok dengan lockfile, hasil resolusi akan segera ditampilkan dari lockfile. Jika tidak, resolusi akan dijalankan, dan file kunci akan diperbarui untuk mencerminkan status saat ini.
  • error: Jika status project cocok dengan file kunci, hasil resolusi akan ditampilkan dari file kunci. Jika tidak, Bazel akan menampilkan error yang menunjukkan variasi antara project dan lockfile. Mode ini sangat berguna jika Anda ingin memastikan bahwa dependensi project Anda tetap tidak berubah, dan setiap perbedaan akan diperlakukan sebagai error.
  • off: File kunci tidak diperiksa sama sekali.

Manfaat File Kunci

File kunci 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.

  • Pelewatan resolusi yang efisien. Dengan lockfile, Bazel dapat melewati proses resolusi jika tidak ada perubahan pada dependensi project sejak build terakhir. Hal ini meningkatkan efisiensi build secara signifikan, terutama dalam skenario yang memerlukan waktu lama untuk resolusi.

  • 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. Hal ini juga mencakup hasil build project dalam status saat ini. File kunci terdiri dari dua bagian utama:

  1. Input resolusi modul, seperti moduleFileHash, flags, dan localOverrideHashes, serta output resolusi, yaitu moduleDepGraph.
  2. Untuk setiap ekstensi modul, file kunci menyertakan input yang memengaruhinya, diwakili oleh transitiveDigest, dan output dari ekstensi yang dijalankan disebut sebagai generatedRepoSpecs

Berikut adalah contoh yang menunjukkan struktur file kunci, beserta penjelasan untuk setiap bagian:

{
  "lockFileVersion": 1,
  "moduleFileHash": "b0f47b98a67ee15f9.......8dff8721c66b721e370",
  "flags": {
    "cmdRegistries": [
      "https://bcr.bazel.build/"
    ],
    "cmdModuleOverrides": {},
    "allowedYankedVersions": [],
    "envVarAllowedYankedVersions": "",
    "ignoreDevDependency": false,
    "directDependenciesMode": "WARNING",
    "compatibilityMode": "ERROR"
  },
  "localOverrideHashes": {
    "bazel_tools": "b5ae1fa37632140aff8.......15c6fe84a1231d6af9"
  },
  "moduleDepGraph": {
    "<root>": {
      "name": "",
      "version": "",
      "executionPlatformsToRegister": [],
      "toolchainsToRegister": [],
      "extensionUsages": [
        {
          "extensionBzlFile": "extension.bzl",
          "extensionName": "lockfile_ext"
        }
      ],
      ...
    }
  },
  "moduleExtensions": {
    "//:extension.bzl%lockfile_ext": {
      "transitiveDigest": "oWDzxG/aLnyY6Ubrfy....+Jp6maQvEPxn0pBM=",
      "generatedRepoSpecs": {
        "hello": {
          "bzlFile": "@@//:extension.bzl",
          ...
        }
      }
    }
  }
}

Hash File Modul

moduleFileHash mewakili hash konten file MODULE.bazel. Jika terjadi perubahan dalam file ini, nilai hash-nya akan berbeda.

Flag

Objek Flags menyimpan semua flag yang dapat memengaruhi hasil resolusi.

Hash Penggantian Lokal

Jika modul root menyertakan local_path_overrides, bagian ini akan menyimpan hash file MODULE.bazel di repositori lokal. Class ini memungkinkan pelacakan perubahan pada dependensi ini.

Grafik Dependensi Modul

moduleDepGraph merepresentasikan hasil proses resolusi menggunakan input yang disebutkan di atas. Library ini membentuk grafik dependensi dari semua modul yang diperlukan untuk menjalankan project.

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.

Setiap entri dalam peta ini sesuai dengan ekstensi yang digunakan dan diidentifikasi berdasarkan file dan nama yang ada di dalamnya. Nilai yang sesuai untuk setiap entri berisi informasi relevan yang terkait dengan ekstensi tersebut:

  1. transitiveDigest adalah ringkasan implementasi ekstensi dan file .bzl transitifnya.
  2. generatedRepoSpecs adalah hasil dari menjalankan ekstensi tersebut dengan input saat ini.

Faktor tambahan yang dapat memengaruhi hasil ekstensi adalah penggunaannya. Meskipun tidak disimpan dalam file kunci, penggunaan akan dipertimbangkan saat membandingkan status ekstensi saat ini dengan status dalam file kunci.

Praktik Terbaik

Untuk memaksimalkan manfaat fitur lockfile, 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 paling baru dan akurat.

  • 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.

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.