外部依存関係の概要

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

Bazel は、ワークスペースにないビルドで使用されるソースファイル（テキストとバイナリの両方）である外部依存関係をサポートしています。 たとえば、GitHub リポジトリでホストされているルールセット、Maven アーティファクト、現在のワークスペース外のローカルマシンのディレクトリなどがあります。

Bazel 6.0 以降、Bazel で外部依存関係を管理する方法は 2 つあります。 従来のリポジトリ中心の WORKSPACE システムと、 新しいモジュール中心の MODULE.bazel システム（コードネーム Bzlmod、 --enable_bzlmod フラグで有効）です。2 つのシステムを 併用できますが、今後の Bazel リリースでは Bzlmod が WORKSPACE システムに置き換わります。移行方法については、Bzlmod 移行ガイドをご覧ください。

このドキュメントでは、Bazel での外部依存関係の管理に関するコンセプトについて説明し、2 つのシステムについて詳しく説明します。

コンセプト

リポジトリ

ルートに境界マーカー ファイルがあり、Bazel ビルドで使用できるソースファイルを含むディレクトリ ツリー。多くの場合、リポ と略されます。

リポの境界マーカー ファイルは、MODULE.bazel（このリポが Bazel モジュールを表すことを示す）、REPO.bazel（下記を参照）、またはレガシー コンテキストでは WORKSPACE または WORKSPACE.bazel になります。リポの境界マーカー ファイルは、リポの境界を示します。このようなファイルは、1 つのディレクトリに複数存在できます。

メイン リポジトリ

現在の Bazel コマンドが実行されているリポジトリ。

メイン リポジトリのルートは、 ワークスペース ルート とも呼ばれます。

ワークスペース

同じメイン リポジトリで実行されるすべての Bazel コマンドが共有する環境。これには、メイン リポと、定義されているすべての外部リポのセットが含まれます。

歴史的に、「リポジトリ」と「ワークスペース」のコンセプトは混同されてきました。「ワークスペース」という用語は、メイン リポジトリを指すために使用されることが多く、リポジトリの同義語として使用されることもあります。

正規リポジトリ名

リポジトリがアドレス指定可能な正規名。ワークスペースのコンテキストでは、各リポジトリに 1 つの正規名があります。正規名が canonical_name のリポ内のターゲットは、ラベル @@canonical_name//package:target でアドレス指定できます（二重の @ に注意してください）。

メイン リポジトリの正規名は常に空の文字列です。

表示リポジトリ名

特定のリポのコンテキストでリポジトリがアドレス指定可能な名前。 これは、リポの「ニックネーム」と考えることができます。正規名が michael のリポは、リポ alice のコンテキストでは表示名が mike になる可能性がありますが、リポ bob のコンテキストでは表示名が mickey になる可能性があります。この場合、michael 内のターゲットは、alice のコンテキストでラベル @mike//package:target でアドレス指定できます（単一の @ に注意してください）。

逆に、これはリポジトリ マッピングと考えることができます。各リポ は、「表示リポジトリ名」から「正規リポジトリ名」へのマッピングを維持します。

リポジトリ ルール

リポジトリ定義のスキーマ。Bazel にリポジトリを具体化する方法を指示します。たとえば、「特定の URL から ZIP アーカイブをダウンロードして展開する」、「特定の Maven アーティファクトを取得して java_import ターゲットとして使用できるようにする」、「ローカル ディレクトリをシンボリック リンクする」などがあります。すべてのリポは、適切な数の引数を使用してリポルールを呼び出すことで定義 されます。

独自のリポジトリ ルールを作成する方法について詳しくは、リポジトリ ルールをご覧ください。

最も一般的なリポルールは http_archiveで、URL からアーカイブをダウンロードして展開し、 local_repositoryで、すでに Bazel リポジトリである ローカル ディレクトリをシンボリック リンクします。

リポジトリを取得する

関連付けられたリポルールを実行して、リポをローカル ディスクで使用できるようにするアクション。ワークスペースで定義されたリポは、取得されるまでローカル ディスクで使用できません。

通常、Bazel はリポから何かが必要で、リポがまだ取得されていない場合にのみリポを取得します。リポがすでに取得されている場合、Bazel は定義が変更された場合にのみ再取得します。

fetch コマンドを使用すると、リポジトリ、ターゲット、またはビルドに必要なすべてのリポジトリのプリフェッチを開始できます。この機能により、--nofetch オプションを使用してオフライン ビルドが可能になります。

--fetch オプションは、ネットワーク アクセスを管理するために使用されます。デフォルト値は true です。 ただし、false（--nofetch）に設定すると、コマンドは依存関係のキャッシュ バージョンを使用します。存在しない場合、コマンドは失敗します。

取得の制御について詳しくは、取得オプションをご覧ください。

ディレクトリ レイアウト

取得後、リポは出力ベースの external サブディレクトリに正規名で保存されます。

次のコマンドを実行すると、正規名が canonical_name のリポの内容を確認できます。

ls $(bazel info output_base)/external/ canonical_name

REPO.bazel ファイル

REPO.bazel ファイルは、リポを構成するディレクトリ ツリーの最上位の境界をマークするために使用されます。リポジトリの境界ファイルとして機能するために何も含める必要はありませんが、リポジトリ内のすべてのビルドターゲットに共通の属性を指定するために使用することもできます。

REPO.bazel ファイルの構文は BUILD ファイルに似ていますが、load ステートメントはサポートされておらず、repo() という 1 つの関数のみを使用できます。repo() は、package() ファイルの BUILD 関数と同じ引数を取ります。package() はパッケージ内のすべてのビルドターゲットに共通の属性を指定しますが、repo() はリポ内のすべてのビルドターゲットに対して同様の処理を行います。

たとえば、次の REPO.bazel ファイルを使用して、リポ内のすべてのターゲットに共通のライセンスを指定できます。

repo(
    default_package_metadata = ["//:my_license"],
)

Bzlmod で外部依存関係を管理する

新しい外部依存関係サブシステムである Bzlmod は、リポ定義を直接処理しません。代わりに、モジュールから依存関係グラフを構築し、 拡張機能をグラフの上に実行して、それに応じてリポを定義します。

A Bazel module は、複数の バージョンを持つことができる Bazel プロジェクトです。各バージョンは、依存する他のモジュールに関するメタデータを公開 します。モジュールには、リポルートの WORKSPACE ファイルの横に MODULE.bazel ファイルが必要です。このファイルはモジュールのマニフェストで、名前、バージョン、依存関係のリストなどの情報が宣言されています。基本的な例を次に示します。

module(name = "my-module", version = "1.0")

bazel_dep(name = "rules_cc", version = "0.0.1")
bazel_dep(name = "protobuf", version = "3.19.0")

モジュールは、直接依存関係のみをリストする必要があります。Bzlmod は、デフォルトで Bazel Central Registry である Bazel registryで直接依存関係を検索します。レジストリは依存関係の MODULE.bazel ファイルを提供します。これにより、Bazel はバージョン解決を行う前に、推移的な依存関係グラフ全体を検出できます。

バージョン解決後（各モジュールに 1 つのバージョンが選択されます）、Bazel はレジストリに再度問い合わせて、各モジュールのリポジトリを定義する方法（ほとんどの場合、http_archive を使用）を確認します。

モジュールは、タグと呼ばれるカスタマイズされたデータの一部を指定することもできます。これは、モジュール解決後にモジュール拡張機能によって使用され、追加のリポジトリを定義します。これらの拡張機能はリポルールと同様の機能を備えており、ファイル I/O やネットワーク リクエストの送信などのアクションを実行できます。これにより、Bazel は他のパッケージ管理システムと連携しながら、Bazel モジュールから構築された依存関係グラフを尊重できます。

WORKSPACE でリポを定義する

従来、外部依存関係は WORKSPACE（または WORKSPACE.bazel）ファイルでリポを定義することで管理できます。このファイルは BUILD ファイルと同様の構文を持ち、ビルドルールの代わりにリポルールを使用します。

次のスニペットは、WORKSPACE ファイルで http_archive リポルールを使用する例です。

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "foo",
    urls = ["https://example.com/foo.zip"],
    sha256 = "c9526390a7cd420fdcec2988b4f3626fe9c5b51e2959f685e8f4d170d1a9bd96",
)

このスニペットは、正規名が foo のリポを定義します。WORKSPACE システムでは、デフォルトで、リポの正規名は他のすべてのリポに対する表示名でもあります。

ファイルで使用できる関数の完全なリストをご覧ください。 WORKSPACE

WORKSPACE システムの欠点

WORKSPACE システムの導入以来、ユーザーから多くの問題が報告されています。たとえば、次のようなものがあります。

  • Bazel は依存関係の WORKSPACE ファイルを評価しないため、直接依存関係に加えて、すべての推移的な依存関係をメイン リポの WORKSPACE ファイルで定義する必要があります。
  • この問題を回避するため、プロジェクトでは「deps.bzl」パターンが採用されています。このパターンでは、複数のリポジトリを定義するマクロを定義し、ユーザーに WORKSPACE ファイルでこのマクロを呼び出すように依頼します。
    • これには独自の問題があります。マクロは他の .bzl ファイルを load できないため、これらのプロジェクトでは、この「deps」マクロで推移的な依存関係を定義するか、ユーザーに複数の階層化された「deps」マクロを呼び出すことでこの問題を回避する必要があります。
    • Bazel は WORKSPACE ファイルを順番に評価します。また、依存関係はバージョン情報なしで URL を使用して http_archive で指定されます。つまり、ダイヤモンド依存関係（A が B と C に依存し、B と C が両方とも D の異なるバージョンに依存する）の場合、バージョン解決を確実に行う方法はありません。

WORKSPACE の欠点により、今後の Bazel リリースでは Bzlmod が従来の WORKSPACE システムに置き換わります。Bzlmod への移行方法については、Bzlmod 移行 ガイドをご覧ください。