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

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

外部依存関係の概要

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

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

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

コンセプト

リポジトリ

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

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

メインリポジトリ

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

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

ワークスペース

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

これまで、「リポジトリ」と「ワークスペース」のコンセプトは混同されてきました。「ワークスペース」という用語はメインリポジトリを指すために使用され、場合によっては「リポジトリ」の同義語として使用されることさえあります。

正規リポジトリ名

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

メインリポジトリでは、正規名として常に空の文字列が使用されます。

リポジトリ名

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

逆に、これはリポジトリマッピングとして理解できます。各リポジトリは、「見かけ上のリポジトリ名」から「正規のリポジトリ名」へのマッピングを維持します。

リポジトリルール

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

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

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

リポジトリを取得する

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

通常、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() という単一の関数のみを使用できます。repo() は、BUILD ファイルの package() 関数と同じ引数を取ります。package() はパッケージ内のすべてのビルドターゲットに共通の属性を指定しますが、repo() はリポジトリ内のすべてのビルドターゲットに対して同様に指定します。

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

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

Bzlmod による外部依存関係の管理

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

Bazel モジュールは、複数のバージョンを持つことができる 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 レジストリ（デフォルトでは Bazel Central Registry）で検索する直接的な依存関係のみを記載する必要があります。このレジストリは依存関係の MODULE.bazel ファイルを提供します。これにより、Bazel はバージョン解決を実行する前に推移的依存関係グラフ全体を検出できます。

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

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

Bzlmod の外部リンク

bazelbuild/examples の Bzlmod の使用例
Bazel External Dependencies Overhaul（元の Bzlmod 設計ドキュメント）
BazelCon 2021 での Bzlmod に関する講演
Bzlmod に関する 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 の欠点により、Bzlmod は今後の Bazel リリースで以前の WORKSPACE システムを置き換えようとしています。Bzlmod への移行方法については、Bzlmod 移行ガイドをご覧ください。