BazelCon 2024 登録の受け付けを開始しました。

このページは Cloud Translation API によって翻訳されました。

Bazel ロックファイル

問題を報告ソースを表示 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel のロックファイル機能を使用すると、プロジェクトに必要なソフトウェアライブラリまたはパッケージの特定のバージョンまたは依存関係を記録できます。これは、モジュール解決と拡張機能評価の結果を保存することで実現されます。ロックファイルは再現可能なビルドを促進し、一貫性のある開発環境を確保します。また、プロジェクトの依存関係の変更の影響を受けない解決プロセスの部分を Bazel がスキップできるようにすることで、ビルド効率を高めることができます。さらに、ロックファイルは、外部ライブラリの予期しない更新や破壊的な変更を防ぐことで安定性を向上させ、バグの発生リスクを軽減します。

ロックファイルの生成

ロックファイルは、ワークスペースのルート下に MODULE.bazel.lock という名前で生成されます。これは、ビルドプロセス（特にモジュールの解決と拡張機能の評価後）で作成または更新されます。重要なのは、ビルドの現在の呼び出しに含まれる依存関係のみが含まれることです。

プロジェクトで依存関係に影響する変更が行われると、ロックファイルが自動的に更新され、新しい状態が反映されます。これにより、ロックファイルは現在のビルドに必要な特定の依存関係セットに焦点を当て続け、プロジェクトの解決済み依存関係を正確に表すことができます。

ロックファイルの使用

ロックファイルはフラグ --lockfile_mode で制御でき、プロジェクトの状態がロックファイルと異なる場合に Bazel の動作をカスタマイズできます。使用可能なモードは次のとおりです。

update（デフォルト）: ロックファイルに存在する情報を使用して、既知のレジストリファイルのダウンロードをスキップし、結果が最新である拡張機能を再評価しないようにします。情報が不足している場合は、ロックファイルに追加されます。このモードでは、Bazel は変更されていない依存関係について、変更可能な情報（削除されたバージョンなど）を更新することも回避します。
refresh: update と同様ですが、変更可能な情報は、このモードに切り替えるときと、このモードにいる間、約 1 時間ごとに常に更新されます。
error: update と同様ですが、情報が不足している場合や古い場合は、Bazel がエラーで失敗します。このモードでは、解決中にロックファイルの変更やネットワークリクエストが実行されることはありません。reproducible としてマークされたモジュール拡張機能は、ネットワークリクエストを実行する可能性がありますが、常に同じ結果が生成されることが期待されます。
off: ロックファイルはチェックも更新もされません。

ロックファイルのメリット

ロックファイルにはいくつかの利点があります。また、さまざまな方法で利用できます。

再現可能なビルド。ロックファイルは、ソフトウェアライブラリの特定のバージョンまたは依存関係をキャプチャすることで、さまざまな環境で、また時間の経過とともにビルドを再現できるようにします。デベロッパーは、プロジェクトの構築時に一貫した予測可能な結果を期待できます。
迅速な段階的な解決:ロックファイルを使用すると、Bazel は以前のビルドですでに使用されたレジストリファイルをダウンロードしなくて済みます。これにより、特に解決に時間がかかる場合のビルド効率が大幅に向上します。
安定性とリスクの軽減。ロックファイルは、外部ライブラリの予期しない更新や破壊的な変更を防ぐことで、安定性を維持するのに役立ちます。依存関係を特定のバージョンにロックすることで、互換性のないアップデートやテストされていないアップデートによるバグの発生リスクを軽減できます。

ロックファイルの内容

ロックファイルには、プロジェクトの状態が変化したかどうかを判断するために必要なすべての情報が含まれています。また、現在の状態でプロジェクトをビルドした結果も含まれます。ロックファイルは主に 2 つの部分で構成されています。

モジュール解決への入力であるすべてのリモートファイルのハッシュ。
ロックファイルには、モジュール拡張機能ごとに、それに影響する入力（bzlTransitiveDigest、usagesDigest などのフィールドで表されます）と、その拡張機能の実行の出力（generatedRepoSpecs と呼ばれます）が含まれます。

ロックファイルの構造と各セクションの説明を示す例を次に示します。

{
  "lockFileVersion": 10,
  "registryFileHashes": {
    "https://bcr.bazel.build/bazel_registry.json": "8a28e4af...5d5b3497",
    "https://bcr.bazel.build/modules/foo/1.0/MODULE.bazel": "7cd0312e...5c96ace2",
    "https://bcr.bazel.build/modules/foo/2.0/MODULE.bazel": "70390338... 9fc57589",
    "https://bcr.bazel.build/modules/foo/2.0/source.json": "7e3a9adf...170d94ad",
    "https://registry.mycorp.com/modules/foo/1.0/MODULE.bazel": "not found",
    ...
  },
  "selectedYankedVersions": {
    "foo@2.0": "Yanked for demo purposes"
  },
  "moduleExtensions": {
    "//:extension.bzl%lockfile_ext": {
      "general": {
        "bzlTransitiveDigest": "oWDzxG/aLnyY6Ubrfy....+Jp6maQvEPxn0pBM=",
        "usagesDigest": "aLmqbvowmHkkBPve05yyDNGN7oh7QE9kBADr3QIZTZs=",
        ...,
        "generatedRepoSpecs": {
          "hello": {
            "bzlFile": "@@//:extension.bzl",
            ...
          }
        }
      }
    },
    "//:extension.bzl%lockfile_ext2": {
      "os:macos": {
        "bzlTransitiveDigest": "oWDzxG/aLnyY6Ubrfy....+Jp6maQvEPxn0pBM=",
        "usagesDigest": "aLmqbvowmHkkBPve05y....yDNGN7oh7r3QIZTZs=",
        ...,
        "generatedRepoSpecs": {
          "hello": {
            "bzlFile": "@@//:extension.bzl",
            ...
          }
        }
      },
      "os:linux": {
        "bzlTransitiveDigest": "eWDzxG/aLsyY3Ubrto....+Jp4maQvEPxn0pLK=",
        "usagesDigest": "aLmqbvowmHkkBPve05y....yDNGN7oh7r3QIZTZs=",
        ...,
        "generatedRepoSpecs": {
          "hello": {
            "bzlFile": "@@//:extension.bzl",
            ...
          }
        }
      }
    }
  }
}

レジストリファイルハッシュ

registryFileHashes セクションには、モジュール解決中にアクセスされたリモートレジストリのすべてのファイルのハッシュが含まれています。解決アルゴリズムは同じ入力が与えられた場合に完全に確定的であり、すべてのリモート入力がハッシュ化されるため、ロックファイル内のリモート情報の過度の重複を回避しながら、完全に再現可能な解決結果が得られます。また、特定のレジストリに特定のモジュールが含まれていないが、優先度の低いレジストリに含まれている場合も記録する必要があります（例の「not found」エントリを参照）。本質的に変更可能なこの情報は、bazel mod deps --lockfile_mode=refresh を介して更新できます。

Bazel は、ロックファイルのハッシュを使用して、リポジトリキャッシュ内のレジストリファイルを検索してからダウンロードします。これにより、後続の解決が高速化されます。

選択した yanked バージョン

selectedYankedVersions セクションには、モジュール解決によって選択されたモジュールの yanked バージョンが含まれています。通常、ビルドしようとするとエラーが発生するため、このセクションが空でなくなるのは、yanked バージョンが --allow_yanked_versions または BZLMOD_ALLOW_YANKED_VERSIONS で明示的に許可されている場合のみです。

このフィールドは、モジュールファイルと比較して、削除されたバージョン情報は本質的に変更可能であるため、ハッシュで参照できないため必要です。この情報は bazel mod deps --lockfile_mode=refresh で更新できます。

モジュール拡張機能

moduleExtensions セクションは、現在の呼び出しで使用されている拡張機能、または以前に呼び出された拡張機能のみを含むマップで、使用されなくなった拡張機能は除外されます。つまり、依存関係グラフ全体で拡張機能が使用されていない場合は、moduleExtensions マップから削除されます。

拡張機能がオペレーティングシステムやアーキテクチャのタイプに依存しない場合は、このセクションに「一般」のエントリが 1 つだけ表示されます。それ以外の場合は、OS、アーキテクチャ、またはその両方に基づいて名前が付けられた複数のエントリが含まれ、それぞれがそれぞれの仕様で拡張機能を評価した結果に対応します。

拡張機能マップの各エントリは、使用される拡張機能に対応しており、そのファイルと名前で識別されます。各エントリの対応する値には、その拡張機能に関連付けられている関連情報が含まれています。

bzlTransitiveDigest は、拡張機能の実装と、それによって間接的に読み込まれる .bzl ファイルのダイジェストです。
usagesDigest は、依存関係グラフ内の拡張機能の使用状況のダイジェストです。これにはすべてのタグが含まれます。
拡張機能への他の入力（読み取るファイルやディレクトリの内容、使用する環境変数など）を追跡する、未指定のフィールド。
generatedRepoSpecs は、拡張機能によって作成されたリポジトリを現在の入力でエンコードします。
オプションの moduleExtensionMetadata フィールドには、拡張機能によって提供されるメタデータが含まれます。たとえば、拡張機能によって作成された特定のリポジトリをルートモジュールが use_repo 経由でインポートするかどうかなどです。この情報は bazel mod tidy コマンドに使用されます。

モジュール拡張機能は、reproducible = True を使用して返されるメタデータを設定することで、ロックファイルへの追加をオプトアウトできます。こうすることで、同じ入力が与えられたときに常に同じリポジトリが作成されることが保証されます。

ベストプラクティス

ロックファイル機能のメリットを最大限に活用するには、次のベストプラクティスを検討してください。

プロジェクトの依存関係や構成の変更を反映するように、ロックファイルを定期的に更新します。これにより、後続のビルドが最新かつ正確な依存関係セットに基づくようになります。すべての拡張機能を一度にロックするには、bazel mod deps --lockfile_mode=update を実行します。
ロックファイルをバージョン管理に含めてコラボレーションを促進し、すべてのチームメンバーが同じロックファイルにアクセスできるようにすることで、プロジェクト全体で一貫した開発環境を促進します。
bazelisk を使用して Bazel を実行し、ロックファイルに対応する Bazel バージョンを指定する .bazelversion ファイルをバージョン管理に含めます。Bazel 自体がビルドの依存関係であるため、ロックファイルは Bazel バージョンに固有であり、下位互換性のある Bazel リリース間でさえ変更されます。bazelisk を使用すると、すべてのデベロッパーがロックファイルに一致する Bazel バージョンを使用できます。

これらのベストプラクティスに従うことで、Bazel のロックファイル機能を効果的に活用し、より効率的で信頼性の高いコラボレーションソフトウェア開発ワークフローを実現できます。

結合の競合

ロックファイル形式は、マージの競合を最小限に抑えるように設計されていますが、競合が発生することもあります。

自動解決

Bazel には、これらの競合を自動的に解決するカスタム git merge ドライバが用意されています。

次の行を Git リポジトリのルートの .gitattributes ファイルに追加して、ドライバを設定します。

# A custom merge driver for the Bazel lockfile.
# https://bazel.build/external/lockfile#automatic-resolution
MODULE.bazel.lock merge=bazel-lockfile-merge

その後、ドライバを使用する各デベロッパーは、次の手順に沿ってドライバを 1 回登録する必要があります。

jq（1.5 以降）をインストールします。
次のコマンドを実行します。

jq_script=$(curl https://raw.githubusercontent.com/bazelbuild/bazel/master/scripts/bazel-lockfile-merge.jq)
printf '%s\n' "${jq_script}" | less # to optionally inspect the jq script
git config --global merge.bazel-lockfile-merge.name   "Merge driver for the Bazel lockfile (MODULE.bazel.lock)"
git config --global merge.bazel-lockfile-merge.driver "jq -s '${jq_script}' -- %O %A %B > %A.jq_tmp && mv %A.jq_tmp %A"

手動解像度

registryFileHashes フィールドと selectedYankedVersions フィールドの単純なマージ競合は、競合の両側のすべてのエントリを保持することで安全に解決できます。

他のタイプのマージ競合は手動で解決しないでください。代替方法は次のとおりです。

git reset MODULE.bazel.lock && git checkout MODULE.bazel.lock を使用して、ロックファイルの以前の状態を復元します。
MODULE.bazel ファイルの競合を解決します。
bazel mod deps を実行してロックファイルを更新します。