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を実行してロックファイルを更新します。