Lockfile Bazel

Laporkan masalah Lihat sumber Nightly · 8.0 . 7,4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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, hal ini meningkatkan efisiensi build dengan mengizinkan Bazel melewati proses resolusi jika tidak ada perubahan pada dependensi project. Selain itu, file kunci meningkatkan stabilitas dengan mencegah update yang tidak terduga atau perubahan yang dapat menyebabkan gangguan di library eksternal, sehingga mengurangi risiko munculnya bug.

Pembuatan File Kunci

File kunci dibuat di root ruang kerja dengan nama MODULE.bazel.lock. File ini dibuat atau diperbarui selama proses build, terutama setelah resolusi modul dan evaluasi ekstensi. File kunci menangkap 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 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 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): Jika status project cocok dengan file kunci, hasil resolusi akan segera ditampilkan dari file kunci. Jika tidak, resolusi akan dieksekusi, 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 file kunci. 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 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.
Lewati resolusi yang efisien. File kunci memungkinkan Bazel melewati proses resolusi jika tidak ada perubahan pada dependensi project sejak build terakhir. Hal ini secara signifikan meningkatkan efisiensi build, terutama dalam skenario saat resolusi dapat memakan waktu.
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. Ini juga mencakup hasil pembuatan project dalam status saat ini. File kunci terdiri dari dua bagian utama:

Input resolusi modul, seperti moduleFileHash, flags, dan localOverrideHashes, serta output resolusi, yaitu moduleDepGraph.
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 pada 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. Hal ini memungkinkan pelacakan perubahan pada dependensi ini.

Grafik Dependensi Modul

moduleDepGraph mewakili hasil proses resolusi menggunakan input yang disebutkan di atas. File 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 oleh file dan namanya. Nilai yang sesuai untuk setiap entri berisi informasi yang relevan yang terkait dengan ekstensi tersebut:

transitiveDigest adalah ringkasan implementasi ekstensi dan file .bzl transitifnya.
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 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 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.