Bazel Lockfile

回報問題 查看來源 Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bazel 的鎖定檔功能可記錄專案所需的軟體程式庫或套件的特定版本或依附元件。方法是儲存模組解析和擴充功能評估的結果。鎖定檔可確保建構作業可重現，並確保開發環境一致。此外，如果專案依附元件沒有任何變更，Bazel 就能略過解析程序，進而提升建構效率。此外，鎖定檔可防止外部程式庫發生非預期的更新或破壞性變更，進而降低導入錯誤的風險，有助於提升穩定性。

產生鎖定檔

鎖定檔會在工作區根目錄下產生，名稱為 MODULE.bazel.lock。這個檔案會在建構程序中建立或更新，具體來說，是在模組解析和擴充功能評估之後。鎖定檔會擷取專案的目前狀態，包括 MODULE 檔案、旗標、覆寫和其他相關資訊。重要事項：這份清單只會列出目前建構作業中包含的依附元件。

如果專案發生變更，導致依附元件受到影響，鎖定檔會自動更新，以反映新狀態。這麼做可確保鎖定檔只會記錄目前建構作業所需的特定依附元件集，準確呈現專案已解決的依附元件。

Lockfile 用量

您可以透過 --lockfile_mode 旗標控制鎖定檔，在專案狀態與鎖定檔不同時，自訂 Bazel 的行為。可用的模式如下：

  • update (預設)：如果專案狀態與鎖定檔相符，系統會立即從鎖定檔傳回解析結果。否則，系統會執行解析作業，並更新鎖定檔案以反映目前狀態。
  • error：如果專案狀態與鎖定檔相符，系統會從鎖定檔傳回解析結果。否則，Bazel 會擲回錯誤，指出專案與鎖定檔之間的差異。如果您想確保專案的依附元件維持不變，並將任何差異視為錯誤，這個模式就特別實用。
  • off：完全未檢查鎖定檔。

鎖定檔優點

鎖定檔有許多優點，而且用途廣泛：

  • 可重現的建構作業。鎖定檔會擷取軟體程式庫的特定版本或依附元件，確保建構作業在不同環境和時間點都能重現。開發人員建構專案時，可依據一致且可預測的結果。

  • 有效略過解決方案。如果自上次建構以來，專案依附元件沒有任何變更，Bazel 就能透過鎖定檔略過解析程序。這能大幅提升建構效率，尤其是在解析度可能耗時的情況下。

  • 穩定性與風險降低。鎖定檔可防止外部程式庫發生意外更新或重大變更，有助於維持穩定性。將依附元件鎖定為特定版本，可降低因不相容或未經測試的更新而導入錯誤的風險。

鎖定檔內容

鎖定檔包含所有必要資訊，可判斷專案狀態是否已變更。此外，也包含目前狀態下建構專案的結果。鎖定檔主要由兩部分組成：

  1. 模組解析度的輸入內容，例如 moduleFileHash、flags 和 localOverrideHashes，以及解析度的輸出內容 (即 moduleDepGraph)。
  2. 對於每個模組擴充功能，鎖定檔會包含影響該擴充功能的輸入內容 (以 transitiveDigest 表示)，以及執行該擴充功能的輸出內容 (稱為 generatedRepoSpecs)

以下範例說明鎖定檔的結構，並提供各部分的說明：

{
  "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",
          ...
        }
      }
    }
  }
}

模組檔案雜湊

moduleFileHash 代表 MODULE.bazel 檔案內容的雜湊值。如果這個檔案有任何變更，雜湊值就會不同。

旗幟

Flags 物件會儲存所有可能影響解析結果的旗標。

本機覆寫雜湊

如果根模組包含 local_path_overrides，這個區段會儲存本機存放區中 MODULE.bazel 檔案的雜湊值。可追蹤這項依附元件的變更。

模組依附元件圖表

moduleDepGraph 代表使用上述輸入內容的解析程序結果。並形成執行專案所需的所有模組依附元件圖。

模組擴充功能

「moduleExtensions」部分是地圖，只包含目前或先前叫用時使用的擴充功能，不包含不再使用的擴充功能。換句話說，如果擴充功能不再用於依附元件圖表，就會從 moduleExtensions 地圖中移除。

這個對應中的每個項目都對應至使用的擴充功能，並由其包含的檔案和名稱識別。每個項目的對應值都包含與該擴充功能相關的資訊：

  1. transitiveDigest：擴充功能實作的摘要，以及其遞移 .bzl 檔案。
  2. generatedRepoSpecs：使用目前輸入內容執行該擴充功能的結果。

使用情況也是影響擴充功能結果的因素之一。 雖然使用情形不會儲存在鎖定檔案中，但比較擴充功能目前狀態與鎖定檔案中的狀態時，系統會將使用情形納入考量。

最佳做法

如要充分發揮鎖定檔功能的優勢，建議您採取下列最佳做法：

  • 定期更新鎖定檔，以反映專案依附元件或設定的變更。確保後續建構作業採用最新且準確的依附元件集。

  • 在版本控管中加入鎖定檔，方便協作並確保所有團隊成員都能存取相同的鎖定檔，在專案中建立一致的開發環境。

只要遵循這些最佳做法，就能有效運用 Bazel 中的鎖定檔功能，進而提升軟體開發工作流程的效率、可靠性及協作性。