Lockfile Bazel

Laporkan masalah Lihat sumber

Fitur lockfile di Bazel memungkinkan perekaman versi atau dependensi tertentu library software atau paket yang diperlukan oleh project. Hal ini dilakukan dengan menyimpan hasil resolusi modul dan evaluasi ekstensi. Lockfile mendukung build yang dapat direproduksi, sehingga memastikan lingkungan pengembangan yang konsisten. Selain itu, API 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 Lockfile

Lockfile dibuat di bawah 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, 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 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 lockfile akan diupdate untuk mencerminkan status saat ini.
  • error: Jika status project cocok dengan lockfile, hasil resolusi akan ditampilkan dari lockfile. Jika tidak, Bazel akan menampilkan error yang menunjukkan variasi antara project dan lockfile. Mode ini sangat berguna saat Anda ingin memastikan bahwa dependensi project Anda tidak berubah, dan setiap perbedaan diperlakukan sebagai error.
  • off: Lockfile tidak diperiksa sama sekali.

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

  • Stabilitas dan pengurangan risiko. Lockfile membantu mempertahankan 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 Lockfile

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:

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

Berikut adalah contoh yang menunjukkan struktur lockfile, 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.

Tanda

Objek Flags menyimpan semua tanda 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 panggilan saat ini atau yang sebelumnya dipanggil, sekaligus mengecualikan ekstensi apa pun yang tidak lagi digunakan. Dengan kata lain, jika ekstensi tidak digunakan lagi 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 ringkasan penerapan ekstensi dan file .bzl transitifnya.
  2. generatedRepoSpecs yang merupakan hasil dari menjalankan ekstensi tersebut dengan input saat ini.

Faktor tambahan yang dapat memengaruhi hasil ekstensi adalah penggunaannya. Meskipun tidak disimpan di lockfile, penggunaannya akan dipertimbangkan saat membandingkan status ekstensi saat ini dengan yang ada di lockfile.

Tips

Untuk memaksimalkan manfaat fitur lockfile, pertimbangkan praktik terbaik berikut:

  • Mengupdate lockfile secara rutin untuk mencerminkan perubahan pada dependensi atau konfigurasi project. Hal ini memastikan bahwa build berikutnya didasarkan pada kumpulan dependensi yang terbaru dan akurat.

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

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.