Bazel Lockfile

报告问题 查看源代码

Bazel 中的 lockfile 功能可以记录项目所需的软件库或软件包的特定版本或依赖项。它通过存储模块解析和扩展评估的结果来实现这一点。锁定文件旨在促进可重现的构建，确保一致的开发环境。此外，它还允许 Bazel 在项目依赖项没有更改时跳过解析流程，从而提高了构建效率。此外，锁定文件可以防止外部库中的意外更新或破坏性更改来提高稳定性，从而降低引入 bug 的风险。

生成锁文件

锁定文件在工作区根目录下生成，名为 MODULE.bazel.lock。它在构建流程中创建或更新，尤其是在模块解析和扩展评估之后。锁定文件会捕获项目的当前状态，包括 MODULE 文件、标志、替换项和其他相关信息。重要的是，它仅包含当前构建调用中包含的依赖项。

当项目中发生影响其依赖项的更改时，锁定文件会自动更新以反映新状态。这样可确保锁定文件始终专注于当前 build 所需的特定依赖项集，从而准确表示项目的已解析依赖项。

Lockfile 使用情况

锁定文件可通过 --lockfile_mode 标志控制，以便在项目状态与锁定文件不同时自定义 Bazel 的行为。可用的模式包括：

  • update（默认）：如果项目状态与锁定文件匹配，则立即从锁定文件返回解决结果。否则，系统会执行解析并更新锁定文件以反映当前状态。
  • error：如果项目状态与锁定文件匹配，则从锁定文件返回解析结果。否则，Bazel 会抛出一个错误，指明项目和锁文件之间的变化。如果您想确保项目的依赖项保持不变，并将任何差异视为错误，此模式特别有用。
  • off：完全不检查锁定文件。

Lockfile 的优势

锁定文件具有多种优势，可通过多种方式使用：

  • 可重现的 build。通过捕获软件库的特定版本或依赖项，锁定文件可确保 build 在不同环境中和随时间推移都能重现。开发者在构建项目时可以依赖一致且可预测的结果。

  • 跳过高效解决方案。如果自上次构建以来项目依赖项未发生任何变化，则 lockfile 可让 Bazel 跳过解析过程。这可以显著提高构建效率，尤其是在解析可能非常耗时的场景中。

  • 稳定性和风险降低。锁定文件可防止发生意外更新或破坏外部库的更改，从而有助于保持稳定性。通过将依赖项锁定到特定版本，可以降低由于更新不兼容或未经测试的更新而引入 bug 的风险。

锁定文件内容

锁定文件包含确定项目状态是否已更改所需的所有信息。还包含在当前状态下构建项目的结果。锁定文件由两个主要部分组成：

  1. 模块分辨率的输入（例如 moduleFileHash、flags 和 localOverrideHashes）以及分辨率的输出（即 moduleDepGraph）。
  2. 对于每个模块扩展，lockfile 都包含对其有影响的输入（以 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 - 使用当前输入运行该扩展程序的结果。

可能影响扩展程序结果的另一个因素是它们的使用情况。虽然未存储在锁定文件中，但在将扩展程序的当前状态与锁定文件中的状态进行比较时，系统会考虑这些使用情况。

最佳实践

为了最大限度地发挥 Lockfile 功能的优势，请考虑以下最佳实践：

  • 定期更新锁定文件，以反映项目依赖项或配置的变化。这样可确保后续构建基于最新、最准确的依赖项集。

  • 在版本控制中包含锁定文件，以促进协作并确保所有团队成员都可以访问同一个锁定文件，从而在整个项目中促进一致的开发环境。

遵循这些最佳实践，您可以有效利用 Bazel 中的 lockfile 功能，从而提高软件开发工作流的效率、可靠性和协作性。