BazelCon 2025 のスケジュールが公開されました。今すぐご登録ください。

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

外部依存関係の操作

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

Bazel は、他のプロジェクトのターゲットに依存できます。これらの他のプロジェクトからの依存関係は、外部依存関係と呼ばれます。

ワークスペースディレクトリの WORKSPACE ファイル（または WORKSPACE.bazel ファイル）は、他のプロジェクトのソースを取得する方法を Bazel に指示します。これらの他のプロジェクトには、独自のターゲットを持つ 1 つ以上の BUILD ファイルを含めることができます。メインプロジェクト内の BUILD ファイルは、WORKSPACE ファイルの名前を使用して、これらの外部ターゲットに依存できます。

たとえば、システムに 2 つのプロジェクトがあるとします。

/
  home/
    user/
      project1/
        WORKSPACE
        BUILD
        srcs/
          ...
      project2/
        WORKSPACE
        BUILD
        my-libs/

project1 が /home/user/project2/BUILD で定義されたターゲット :foo に依存する場合、project2 という名前のリポジトリが /home/user/project2 にあることを指定できます。次に、/home/user/project1/BUILD のターゲットは @project2//:foo に依存する可能性があります。

WORKSPACE ファイルを使用すると、ユーザーはファイルシステムの他の部分のターゲットやインターネットからダウンロードしたターゲットに依存できます。BUILD ファイルと同じ構文を使用しますが、リポジトリルール（ワークスペースルールとも呼ばれます）という別のルールセットを使用できます。Bazel には、いくつかの組み込みリポジトリルールと、一連の埋め込み Starlark リポジトリルールが付属しています。ユーザーは、より複雑な動作を実現するためにカスタムリポジトリルールを作成することもできます。

サポートされている外部依存関係のタイプ

次の基本的なタイプの外部依存関係を使用できます。

他の Bazel プロジェクトへの依存関係
Bazel 以外のプロジェクトへの依存関係
外部パッケージへの依存関係

他の Bazel プロジェクトに依存する

2 つ目の Bazel プロジェクトのターゲットを使用する場合は、local_repository、git_repository、または http_archive を使用して、ローカルファイルシステムからシンボリックリンクを作成するか、git リポジトリを参照するか、ダウンロードします（それぞれ）。

たとえば、プロジェクト my-project/ で作業していて、同僚のプロジェクト coworkers-project/ のターゲットに依存するとします。どちらのプロジェクトも Bazel を使用しているため、同僚のプロジェクトを外部依存関係として追加し、同僚が定義したターゲットを自分の BUILD ファイルから使用できます。my_project/WORKSPACE に次のコードを追加します。

local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
)

同僚がターゲット //foo:bar を持っている場合、プロジェクトはそれを @coworkers_project//foo:bar として参照できます。外部プロジェクト名は、有効なワークスペース名にする必要があります。

Bazel 以外のプロジェクトへの依存

new_ で始まるルール（new_local_repository など）を使用すると、Bazel を使用しないプロジェクトからターゲットを作成できます。

たとえば、プロジェクト my-project/ を作業していて、同僚のプロジェクト coworkers-project/ に依存するとします。同僚のプロジェクトは make を使用してビルドしますが、生成される .so ファイルの 1 つに依存したいと考えています。そのためには、次のコードを my_project/WORKSPACE に追加します。

new_local_repository(
    name = "coworkers_project",
    path = "/path/to/coworkers-project",
    build_file = "coworker.BUILD",
)

build_file は、既存のプロジェクトにオーバーレイする BUILD ファイルを指定します。次に例を示します。

cc_library(
    name = "some-lib",
    srcs = glob(["**"]),
    visibility = ["//visibility:public"],
)

これにより、プロジェクトの BUILD ファイルから @coworkers_project//:some-lib に依存できるようになります。

外部パッケージに依存する

Maven アーティファクトとリポジトリ

ルールセット rules_jvm_external を使用して、Maven リポジトリからアーティファクトをダウンロードし、Java 依存関係として使用できるようにします。

依存関係をフェッチする

デフォルトでは、外部依存関係は bazel build 中に必要に応じて取得されます。特定のターゲットセットに必要な依存関係をプリフェッチする場合は、bazel fetch を使用します。すべての外部依存関係を無条件で取得するには、bazel sync を使用します。取得したリポジトリは出力ベースに保存されるため、取得はワークスペースごとに行われます。

依存関係のシャドーイング

可能な限り、プロジェクトに単一のバージョンポリシーを設定することをおすすめします。これは、コンパイル対象の依存関係で、最終的なバイナリに組み込まれるものに必要です。ただし、この条件を満たさない場合は、依存関係をシャドーイングできます。次のシナリオを考えてみます。

myproject/WORKSPACE

workspace(name = "myproject")

local_repository(
    name = "A",
    path = "../A",
)
local_repository(
    name = "B",
    path = "../B",
)

A/WORKSPACE

workspace(name = "A")

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

B/WORKSPACE

workspace(name = "B")

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

依存関係 A と B はどちらも testrunner に依存しますが、依存する testrunner のバージョンが異なります。これらのテストランナーが myproject 内で共存できない理由はありませんが、名前が同じであるため、互いに競合します。両方の依存関係を宣言するには、myproject/WORKSPACE を更新します。

workspace(name = "myproject")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "testrunner-v1",
    urls = ["https://github.com/testrunner/v1.zip"],
    sha256 = "..."
)
http_archive(
    name = "testrunner-v2",
    urls = ["https://github.com/testrunner/v2.zip"],
    sha256 = "..."
)
local_repository(
    name = "A",
    path = "../A",
    repo_mapping = {"@testrunner" : "@testrunner-v1"}
)
local_repository(
    name = "B",
    path = "../B",
    repo_mapping = {"@testrunner" : "@testrunner-v2"}
)

このメカニズムは、ダイヤモンドを結合するためにも使用できます。たとえば、A と B の依存関係が同じで、名前が異なる場合、それらの依存関係は myproject/WORKSPACE で結合できます。

コマンドラインからリポジトリをオーバーライドする

コマンドラインから宣言されたリポジトリをローカルリポジトリでオーバーライドするには、--override_repository フラグを使用します。このフラグを使用すると、ソースコードを変更せずに外部リポジトリの内容を変更できます。

たとえば、@foo をローカルディレクトリ /path/to/local/foo にオーバーライドするには、--override_repository=foo=/path/to/local/foo フラグを渡します。

ユースケースの一部を示します。

問題のデバッグ。たとえば、http_archive リポジトリをローカルディレクトリにオーバーライドして、変更をより簡単に行うことができます。
ベンダーリング。ネットワーク呼び出しを行えない環境の場合は、ネットワークベースのリポジトリルールをオーバーライドして、代わりにローカルディレクトリを指すようにします。

プロキシの使用

Bazel は、HTTPS_PROXY 環境変数と HTTP_PROXY 環境変数からプロキシアドレスを取得し、これらを使用して HTTP/HTTPS ファイルをダウンロードします（指定されている場合）。

IPv6 のサポート

IPv6 専用のマシンでは、Bazel は変更なしで依存関係をダウンロードできます。ただし、デュアルスタック IPv4/IPv6 マシンでは、Bazel は Java と同じ規則に従います。IPv4 が有効になっている場合は、IPv4 が優先されます。たとえば、IPv4 ネットワークが外部アドレスを解決または到達できない場合、Network unreachable 例外が発生し、ビルドが失敗することがあります。このような場合は、java.net.preferIPv6Addresses=true システムプロパティを使用して、IPv6 を優先するように Bazel の動作をオーバーライドできます。詳細:

--host_jvm_args=-Djava.net.preferIPv6Addresses=true 起動オプションを使用します。たとえば、.bazelrc ファイルに次の行を追加します。

startup --host_jvm_args=-Djava.net.preferIPv6Addresses=true
インターネットへの接続も必要とする Java ビルドターゲット（統合テストで必要になることがあります）を実行している場合は、--jvmopt=-Djava.net.preferIPv6Addresses=true ツールフラグも使用します。たとえば、.bazelrc ファイルに次の行を追加します。

build --jvmopt=-Djava.net.preferIPv6Addresses
たとえば、依存関係のバージョン解決に rules_jvm_external を使用している場合は、COURSIER_OPTS 環境変数に -Djava.net.preferIPv6Addresses=true も追加して、Coursier の JVM オプションを指定します。

推移的依存関係

Bazel は、WORKSPACE ファイルにリストされている依存関係のみを読み取ります。プロジェクト（A）が別のプロジェクト（B）に依存しており、そのプロジェクトの WORKSPACE ファイルに第三のプロジェクト（C）への依存関係がリストされている場合は、B と C の両方をプロジェクトの WORKSPACE ファイルに追加する必要があります。この要件により WORKSPACE ファイルのサイズが大きくなる可能性がありますが、1 つのライブラリにバージョン 1.0 の C が含まれ、別のライブラリにバージョン 2.0 の C が含まれる可能性を抑えることができます。

外部依存関係のキャッシュ保存

デフォルトでは、Bazel は外部依存関係の定義が変更された場合にのみ、外部依存関係を再ダウンロードします。定義で参照されているファイル（パッチや BUILD ファイルなど）の変更も bazel によって考慮されます。

再ダウンロードを強制するには、bazel sync を使用します。

レイアウト

外部依存関係はすべて、出力ベースのサブディレクトリ external の下のディレクトリにダウンロードされます。ローカルリポジトリの場合、新しいディレクトリを作成する代わりに、シンボリックリンクが作成されます。external ディレクトリを表示するには、次のコマンドを実行します。

ls $(bazel info output_base)/external

bazel clean を実行しても、外部ディレクトリは実際には削除されません。すべての外部アーティファクトを削除するには、bazel clean --expunge を使用します。

オフラインビルド

オフラインでビルドを実行することが望ましい場合や、必要になる場合があります。飛行機での移動などのシンプルなユースケースでは、bazel fetch または bazel sync を使用して必要なリポジトリをprefetchingするだけで十分です。さらに、--nofetch オプションを使用すると、ビルド中にそれ以降のリポジトリのフェッチを無効にできます。

必要なファイルの提供を bazel 以外のエンティティが行う真のオフラインビルドの場合、bazel は --distdir オプションをサポートしています。リポジトリルールが ctx.download または ctx.download_and_extract を介してファイルをフェッチするように bazel に要求し、必要なファイルのハッシュサムを提供すると、bazel はまず、そのオプションで指定されたディレクトリで、提供された最初の URL のベース名と一致するファイルを探し、ハッシュが一致する場合はそのローカルコピーを使用します。

Bazel 自体も、この手法を使用して、配布アーティファクトからオフラインでブートストラップします。これは、内部の distdir_tar に必要な外部依存関係をすべて収集することで実現されます。

ただし、bazel では、ネットワークにアクセスするかどうかを把握せずに、リポジトリルールで任意のコマンドを実行できます。そのため、bazel にはビルドを完全にオフラインで実行するオプションはありません。そのため、ビルドがオフラインで正しく動作するかどうかをテストするには、bazel がブートストラップテストで行うように、ネットワークを外部からブロックする必要があります。

ベストプラクティス

リポジトリルール

通常、リポジトリルールは次のことを担当します。

システム設定を検出してファイルに書き込む。
システム内の他の場所でリソースを見つける。
URL からリソースをダウンロードしています。
BUILD ファイルを外部リポジトリディレクトリに生成またはシンボリックリンクすること。

可能な限り、repository_ctx.execute の使用は避けてください。たとえば、Make を使用してビルドする Bazel 以外の C++ ライブラリを使用する場合は、ctx.execute(["make"]) を実行するのではなく、repository_ctx.download() を使用してから、ビルドする BUILD ファイルを作成することをおすすめします。

git_repository と new_git_repository よりも http_archive を優先します。その理由は次のとおりです。

Git リポジトリルールはシステム git(1) に依存しますが、HTTP ダウンローダーは Bazel に組み込まれており、システム依存関係はありません。
http_archive はミラーとして urls のリストをサポートしますが、git_repository は単一の remote のみをサポートします。
http_archive はリポジトリキャッシュで動作しますが、git_repository では動作しません。詳しくは、#5116 をご覧ください。

bind() を使用しない。問題と代替案の詳細については、バインドの削除を検討するをご覧ください。