Bazel ロックファイル

問題を報告 ソースを表示

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

ロックファイルの生成

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

プロジェクト内で依存関係に影響する変更が発生すると、ロックファイルは新しい状態を反映するように自動的に更新されます。これにより、ロックファイルは現在のビルドに必要な特定の依存関係のセットにフォーカスされたままとなり、プロジェクトの解決済みの依存関係を正確に表現できます。

ロックファイルの使用

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

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

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

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

  • 再現可能なビルド。ロックファイルでは、ソフトウェア ライブラリの特定のバージョンや依存関係をキャプチャすることで、さまざまな環境や時間の経過に伴ってビルドを再現できます。デベロッパーは、プロジェクトをビルドする際に、一貫性があり予測可能な結果を利用できます。

  • 迅速な解決。ロックファイルにより、Bazel は、以前のビルドですでに使用されていたレジストリ ファイルをダウンロードせずに済みます。これにより、特に解決に時間がかかるシナリオで、ビルドの効率が大幅に向上します。

  • 安定性とリスクの軽減。ロックファイルは、外部ライブラリの予期しない更新や互換性を破る変更を防止することで、安定性を維持します。依存関係を特定のバージョンにロックすることで、互換性のない更新やテストされていない更新が原因でバグが発生するリスクが軽減されます。

ロックファイルの内容

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

  1. モジュール解決への入力であるすべてのリモート ファイルのハッシュ。
  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 セクションには、モジュールの解決中にアクセスされるリモート レジストリのすべてのファイルのハッシュが含まれます。解決アルゴリズムは、同じ入力を与えられ、すべてのリモート入力がハッシュされると完全に確定的であるため、ロックファイル内のリモート情報の過剰な重複を回避しながら、完全に再現可能な解決結果が保証されます。なお、特定のレジストリに特定のモジュールがないものの、優先順位の低いレジストリには含まれていた場合、記録が必要になります（例の「見つかりません」エントリを参照）。本質的に変更可能な情報は、bazel mod deps --lockfile_mode=refresh で更新できます。

Bazel は、ロックファイルのハッシュを使用して、ダウンロードする前にリポジトリ キャッシュ内でレジストリ ファイルを検索します。これにより、以降の解決時間を短縮できます。

選択したヤンク付きバージョン

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

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

モジュール拡張機能

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

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

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

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

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

ベスト プラクティス

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

  • 定期的にロックファイルを更新して、プロジェクトの依存関係や構成の変更を反映します。これにより、以降のビルドが最新かつ正確な依存関係のセットに基づくようになります。すべての拡張機能を一度にロックするには、bazel mod deps --lockfile_mode=update を実行します。

  • ロックファイルをバージョン管理に含めてコラボレーションを促進し、すべてのチームメンバーが同じロックファイルにアクセスできるようにします。これにより、プロジェクト全体で一貫性のある開発環境が促進されます。

  • bazelisk を使用して Bazel を実行し、ロックファイルに対応する Bazel バージョンを指定する .bazelversion ファイルをバージョン管理に含めます。Bazel 自体はビルドの依存関係であるため、ロックファイルは Bazel バージョンに固有であり、下位互換性のある Bazel リリース間でも変わります。bazelisk を使用すると、すべてのデベロッパーがロックファイルと一致する Bazel バージョンを使用するようになります。

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