Bazel Lockfile

回報問題 查看原始碼 Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

產生鎖定檔案

系統會在工作區根目錄下產生名為 MODULE.bazel.lock 的鎖定檔案。這項資訊會在建構程序期間建立或更新,特別是在模組解析和擴充功能評估之後。鎖定檔案會擷取專案的目前狀態,包括模組檔案、標記、覆寫和其他相關資訊。重要的是,它只會納入目前建構作業呼叫中包含的依附元件。

當專案發生變更,且影響其依附元件時,系統會自動更新鎖定檔案,以反映新的狀態。這麼做可確保鎖定檔案持續專注於目前版本所需的特定依附元件組合,並準確呈現專案已解析的依附元件。

鎖定檔案用途

鎖定檔案可透過標記 --lockfile_mode 進行控制,在專案狀態與鎖定檔案不同時,可自訂 Bazel 的行為。可用的模式如下:

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

鎖定檔案的優點

鎖定檔案有許多優點,且可用於各種用途:

  • 可重現的建構作業:鎖定檔會擷取軟體程式庫的特定版本或依附元件,確保建構作業可在不同環境中重現,並且隨時間推移。開發人員在建構專案時,可以依賴一致且可預測的結果。

  • 有效跳過解析度。如果自上次建構以來,專案依附元件並未發生變更,鎖定檔案可讓 Bazel 略過解析程序。這可大幅提升建構效率,特別是在解析可能耗時的情況下。

  • 穩定性和風險降低。鎖定檔案可防止外部程式庫發生意外更新或破壞性變更,進而維持穩定性。將依附元件鎖定至特定版本,可降低因不相容或未經測試的更新而引入錯誤的風險。

鎖定檔案內容

鎖定檔案包含判斷專案狀態是否已變更所需的所有必要資訊。並包含在目前狀態下建構專案的結果。鎖定檔案包含兩個主要部分:

  1. 模組解析度的輸入內容,例如 moduleFileHashflagslocalOverrideHashes,以及解析度的輸出內容 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 的鎖定檔案功能,打造更有效率、可靠且可協作的軟體開發工作流程。