BazelCon 2025 の登録と CFP が開始されました。

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

Bzlmod 移行ガイド

問題を報告ソースを表示 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

WORKSPACE の欠点により、Bzlmod は以前の WORKSPACE システムに代わるものです。WORKSPACE ファイルは Bazel 8（2024 年後半）ですでに無効になっており、Bazel 9（2025 年後半）で削除されます。このガイドでは、プロジェクトを Bzlmod に移行し、外部依存関係の管理に WORKSPACE を使用しないようにする方法について説明します。

Bzlmod に移行する理由

従来の WORKSPACE システムと比較して多くのメリットがあり、Bazel エコシステムの健全な成長を確保するのに役立ちます。
プロジェクトが他のプロジェクトの依存関係である場合、Bzlmod に移行すると、他のプロジェクトの移行がブロックされなくなり、プロジェクトへの依存が容易になります。
Bzlmod への移行は、将来の Bazel バージョンを使用するために必要なステップです（Bazel 9 では必須）。

Bzlmod に移行する方法

推奨される移行プロセス:

移行ツールをヘルパーツールとして使用し、移行プロセスを可能な限り効率化します。移行ツールとツールの使用方法のセクションを確認します。
移行ツールを使用してもエラーが残っている場合は、手動で解決します。WORKSPACE ファイルと MODULE.bazel ファイルのコンセプトの主な違いについては、WORKSPACE と Bzlmod のセクションをご覧ください。

移行ツール

WORKSPACE から Bzlmod への移行という複雑なプロセスを簡素化するため、移行スクリプトを使用することを強くおすすめします。このヘルパーツールは、外部依存関係管理システムの移行に関連する多くの手順を自動化します。

コア機能

スクリプトの主な機能は次のとおりです。

依存関係情報の収集: プロジェクトの WORKSPACE ファイルを分析して、指定されたビルドターゲットで使用される外部リポジトリを特定します。Bazel の experimental_repository_resolved_file フラグを使用して、この情報を含む resolved_deps.py ファイルを生成します。
直接依存関係の特定: bazel query を使用して、指定されたターゲットの直接依存関係であるリポジトリを特定します。
Bzlmod 移行: 関連する WORKSPACE 依存関係を Bzlmod の同等のものに変換します。手順は次の 2 つです。
1. 特定されたすべての直接的な依存関係を MODULE.bazel ファイルに導入しようとします。
2. Bzlmod を有効にして指定されたターゲットのビルドを試み、認識可能なエラーを繰り返し特定して修正します。このステップは、最初のステップで一部の依存関係が欠落している可能性があるため必要です。
移行レポートの生成: 移行プロセスを文書化した migration_info.md ファイルを作成します。このレポートには、直接依存関係のリスト、生成された Bzlmod 宣言、移行を完了するために必要な手動の手順が含まれています。

移行ツールは次の機能をサポートしています。

Bazel Central Registry で利用可能な依存関係
ユーザー定義のカスタムリポジトリルール
[近日公開] パッケージマネージャーの依存関係

重要な注意事項: 移行ツールはベストエフォートユーティリティです。常に、その推奨事項が正しいかどうかを再確認してください。

移行ツールの使用方法

始める前に、次のことを行います。

WORKSPACE と Bzlmod の両方を強力にサポートする最新の Bazel 7 リリースにアップグレードします。
プロジェクトのメインビルドターゲットに対して次のコマンドが正常に実行されることを確認します。
```
bazel build --nobuild --enable_workspace --noenable_bzlmod <targets>
```

前提条件を満たしたら、次のコマンドを実行して移行ツールを使用します。

# Clone the Bazel Central Registry repository
git clone https://github.com/bazelbuild/bazel-central-registry.git
cd bazel-central-registry

# Build the migration tool
bazel build //tools:migrate_to_bzlmod

# Create a convenient alias for the tool
alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)

# Navigate to your project's root directory and run the tool
cd <your workspace root>
migrate2bzlmod -t <your build targets>

WORKSPACE と Bzlmod

Bazel の WORKSPACE と Bzlmod は、構文は異なりますが同様の機能を提供します。このセクションでは、特定の WORKSPACE 機能から Bzlmod に移行する方法について説明します。

Bazel ワークスペースのルートを定義する

WORKSPACE ファイルは Bazel プロジェクトのソースルートをマークします。この役割は、Bazel バージョン 6.3 以降では MODULE.bazel に置き換えられています。Bazel バージョン 6.3 より前のバージョンでは、ワークスペースのルートに WORKSPACE ファイルまたは WORKSPACE.bazel ファイルがまだ存在しているはずです。次のようなコメントが含まれている可能性があります。

Google Workspace

# This file marks the root of the Bazel workspace.
# See MODULE.bazel for external dependencies setup.

bazelrc で Bzlmod を有効にする

.bazelrc を使用すると、Bazel を実行するたびに適用されるフラグを設定できます。Bzlmod を有効にするには、--enable_bzlmod フラグを使用して common コマンドに適用し、すべてのコマンドに適用されるようにします。

.bazelrc

# Enable Bzlmod for every Bazel command
common --enable_bzlmod

ワークスペースのリポジトリ名を指定する

Google Workspace

workspace 関数は、ワークスペースのリポジトリ名を指定するために使用されます。これにより、ワークスペース内のターゲット //foo:bar を @<workspace name>//foo:bar として参照できます。指定しない場合、ワークスペースのデフォルトのリポジトリ名は __main__ です。
```
## WORKSPACE
workspace(name = "com_foo_bar")
```
Bzlmod

@<repo name> を使用せずに //foo:bar 構文を使用して、同じワークスペース内のターゲットを参照することをおすすめします。ただし、古い構文が必要な場合は、module 関数で指定されたモジュール名をリポジトリ名として使用できます。モジュール名が必要なリポジトリ名と異なる場合は、module 関数の repo_name 属性を使用してリポジトリ名をオーバーライドできます。
```
## MODULE.bazel
module(
    name = "bar",
    repo_name = "com_foo_bar",
)
```

外部依存関係を Bazel モジュールとして取得する

依存関係が Bazel プロジェクトの場合、Bzlmod も採用していれば、Bazel モジュールとして依存関係を持つことができます。

Google Workspace

WORKSPACE では、http_archive または git_repository リポジトリルールを使用して Bazel プロジェクトのソースをダウンロードするのが一般的です。

## WORKSPACE
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "bazel_skylib",
    urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.4.2/bazel-skylib-1.4.2.tar.gz"],
    sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa",
)
load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
bazel_skylib_workspace()

http_archive(
    name = "rules_java",
    urls = ["https://github.com/bazelbuild/rules_java/releases/download/6.1.1/rules_java-6.1.1.tar.gz"],
    sha256 = "76402a50ae6859d50bd7aed8c1b8ef09dae5c1035bb3ca7d276f7f3ce659818a",
)
load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains")
rules_java_dependencies()
rules_java_toolchains()

ご覧のとおり、ユーザーが依存関係のマクロから推移的依存関係を読み込む必要があるのは一般的なパターンです。bazel_skylib と rules_java の両方が platform に依存していると仮定します。platform 依存関係の正確なバージョンは、マクロの順序によって決まります。

Bzlmod

Bzlmod では、依存関係が Bazel Central Registry またはカスタム Bazel レジストリで使用可能である限り、bazel_dep ディレクティブを使用して依存関係を簡単に指定できます。
```
## MODULE.bazel
bazel_dep(name = "bazel_skylib", version = "1.4.2")
bazel_dep(name = "rules_java", version = "6.1.1")
```
Bzlmod は、MVS アルゴリズムを使用して Bazel モジュールの依存関係を推移的に解決します。そのため、platform の最大必須バージョンが自動的に選択されます。

依存関係を Bazel モジュールとしてオーバーライドする

ルートモジュールとして、さまざまな方法で Bazel モジュールの依存関係をオーバーライドできます。

詳しくは、オーバーライドのセクションをご覧ください。

使用例は、examples リポジトリで確認できます。

モジュール拡張機能を使用して外部依存関係をフェッチする

依存関係が Bazel プロジェクトでない場合や、Bazel レジストリでまだ利用できない場合は、use_repo_rule またはモジュール拡張機能を使用して導入できます。

Google Workspace

http_file リポジトリルールを使用してファイルをダウンロードします。

## WORKSPACE
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")

http_file(
    name = "data_file",
    url = "http://example.com/file",
    sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
)

Bzlmod

Bzlmod では、MODULE.bazel ファイルで use_repo_rule ディレクティブを使用して、リポジトリを直接インスタンス化できます。
```
## MODULE.bazel
http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
http_file(
    name = "data_file",
    url = "http://example.com/file",
    sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
)
```
内部的には、これはモジュール拡張機能を使用して実装されています。単にリポジトリルールを呼び出すよりも複雑なロジックを実行する必要がある場合は、モジュール拡張機能を自分で実装することもできます。定義を .bzl ファイルに移動する必要があります。これにより、移行期間中に WORKSPACE と Bzlmod 間で定義を共有することもできます。
```
## repositories.bzl
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def my_data_dependency():
    http_file(
        name = "data_file",
        url = "http://example.com/file",
        sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    )
```
モジュール拡張機能を実装して、依存関係マクロを読み込みます。マクロの同じ .bzl ファイルで定義できますが、古い Bazel バージョンとの互換性を維持するため、別の .bzl ファイルで定義することをおすすめします。
```
## extensions.bzl
load("//:repositories.bzl", "my_data_dependency")
def _non_module_dependencies_impl(_ctx):
    my_data_dependency()

non_module_dependencies = module_extension(
    implementation = _non_module_dependencies_impl,
)
```
リポジトリをルートプロジェクトから見えるようにするには、MODULE.bazel ファイルでモジュール拡張機能とリポジトリの使用状況を宣言する必要があります。
```
## MODULE.bazel
non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies")
use_repo(non_module_dependencies, "data_file")
```

モジュール拡張機能を使用して外部依存関係の競合を解決する

プロジェクトは、呼び出し元からの入力に基づいて外部リポジトリを導入するマクロを提供できます。ただし、依存関係グラフに複数の呼び出し元があり、競合が発生した場合はどうなるでしょうか。

プロジェクト foo が、version を引数として受け取る次のマクロを提供するとします。

## repositories.bzl in foo {:#repositories.bzl-foo}
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
    http_file(
        name = "data_file",
        url = "http://example.com/file-%s" % version,
        # Omitting the "sha256" attribute for simplicity
    )

Google Workspace

WORKSPACE を使用すると、@foo からマクロを読み込み、必要なデータ依存関係のバージョンを指定できます。別の依存関係 @bar があり、これも @foo に依存しているが、異なるバージョンのデータ依存関係を必要としているとします。
```
## WORKSPACE

# Introduce @foo and @bar.
...

load("@foo//:repositories.bzl", "data_deps")
data_deps(version = "2.0")

load("@bar//:repositories.bzl", "bar_deps")
bar_deps() # -> which calls data_deps(version = "3.0")
```
この場合、エンドユーザーは WORKSPACE のマクロの順序を慎重に調整して、必要なバージョンを取得する必要があります。これは、依存関係を解決する適切な方法が提供されていないため、WORKSPACE の最大の難点の 1 つです。

Bzlmod

Bzlmod を使用すると、プロジェクト foo の作成者はモジュール拡張機能を使用して競合を解決できます。たとえば、すべての Bazel モジュールの中で、データ依存関係の最大必要バージョンを常に選択することが理にかなっているとします。

## extensions.bzl in foo
load("//:repositories.bzl", "data_deps")

data = tag_class(attrs={"version": attr.string()})

def _data_deps_extension_impl(module_ctx):
    # Select the maximal required version in the dependency graph.
    version = "1.0"
    for mod in module_ctx.modules:
        for data in mod.tags.data:
            version = max(version, data.version)
    data_deps(version)

data_deps_extension = module_extension(
    implementation = _data_deps_extension_impl,
    tag_classes = {"data": data},
)

## MODULE.bazel in bar
bazel_dep(name = "foo", version = "1.0")

foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
foo_data_deps.data(version = "3.0")
use_repo(foo_data_deps, "data_file")

## MODULE.bazel in root module
bazel_dep(name = "foo", version = "1.0")
bazel_dep(name = "bar", version = "1.0")

foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension")
foo_data_deps.data(version = "2.0")
use_repo(foo_data_deps, "data_file")

この場合、ルートモジュールはデータバージョン 2.0 を必要とし、依存関係 bar は 3.0 を必要とします。foo のモジュール拡張機能は、この競合を正しく解決し、データ依存関係にバージョン 3.0 を自動的に選択できます。

サードパーティのパッケージマネージャーを統合する

前のセクションで説明したように、モジュール拡張機能は依存関係グラフから情報を収集し、依存関係を解決するカスタムロジックを実行し、リポジトリルールを呼び出して外部リポジトリを導入する方法を提供するため、ルール作成者はこれを利用して、特定の言語のパッケージマネージャーを統合するルールセットを強化できます。

モジュール拡張機能の使用方法について詳しくは、モジュール拡張機能のページをご覧ください。

Bzlmod を採用してさまざまなパッケージマネージャーから依存関係を取得しているルールセットのリストは次のとおりです。

疑似パッケージマネージャーを統合する最小限の例は、examples リポジトリで入手できます。

ホストマシン上のツールチェーンを検出する

Bazel ビルドルールでホストマシンで使用可能なツールチェーンを検出する必要がある場合、リポジトリルールを使用してホストマシンを検査し、ツールチェーン情報を外部リポジトリとして生成します。

Google Workspace

シェルツールチェーンを検出する次のリポジトリルールがあるとします。

## local_config_sh.bzl
def _sh_config_rule_impl(repository_ctx):
    sh_path = get_sh_path_from_env("SH_BIN_PATH")

    if not sh_path:
        sh_path = detect_sh_from_path()

    if not sh_path:
        sh_path = "/shell/binary/not/found"

    repository_ctx.file("BUILD", """
load("@bazel_tools//tools/sh:sh_toolchain.bzl", "sh_toolchain")
sh_toolchain(
    name = "local_sh",
    path = "{sh_path}",
    visibility = ["//visibility:public"],
)
toolchain(
    name = "local_sh_toolchain",
    toolchain = ":local_sh",
    toolchain_type = "@bazel_tools//tools/sh:toolchain_type",
)
""".format(sh_path = sh_path))

sh_config_rule = repository_rule(
    environ = ["SH_BIN_PATH"],
    local = True,
    implementation = _sh_config_rule_impl,
)

リポジトリルールは WORKSPACE に読み込むことができます。

## WORKSPACE
load("//:local_config_sh.bzl", "sh_config_rule")
sh_config_rule(name = "local_config_sh")

Bzlmod

Bzlmod では、モジュール拡張機能を使用して同じリポジトリを導入できます。これは、前のセクションで @data_file リポジトリを導入するのと同様です。

## local_config_sh_extension.bzl
load("//:local_config_sh.bzl", "sh_config_rule")

sh_config_extension = module_extension(
    implementation = lambda ctx: sh_config_rule(name = "local_config_sh"),
)

次に、MODULE.bazel ファイルで拡張機能を使用します。

## MODULE.bazel
sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
use_repo(sh_config_ext, "local_config_sh")

ツールチェーンと実行プラットフォームを登録する

前のセクションに続いて、リポジトリホスティングツールチェーン情報（local_config_sh など）を導入したら、ツールチェーンを登録することをおすすめします。

Google Workspace

WORKSPACE を使用すると、次の方法でツールチェーンを登録できます。

ツールチェーンを .bzl ファイルに登録し、WORKSPACE ファイルでマクロを読み込むことができます。

## local_config_sh.bzl
def sh_configure():
    sh_config_rule(name = "local_config_sh")
    native.register_toolchains("@local_config_sh//:local_sh_toolchain")

## WORKSPACE
load("//:local_config_sh.bzl", "sh_configure")
sh_configure()

または、WORKSPACE ファイルにツールチェーンを直接登録します。

## WORKSPACE
load("//:local_config_sh.bzl", "sh_config_rule")
sh_config_rule(name = "local_config_sh")
register_toolchains("@local_config_sh//:local_sh_toolchain")

Bzlmod

Bzlmod では、register_toolchains API と register_execution_platforms API は MODULE.bazel ファイルでのみ使用できます。モジュール拡張機能で native.register_toolchains を呼び出すことはできません。
```
## MODULE.bazel
sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension")
use_repo(sh_config_ext, "local_config_sh")
register_toolchains("@local_config_sh//:local_sh_toolchain")
```

WORKSPACE、WORKSPACE.bzlmod、各 Bazel モジュールの MODULE.bazel ファイルに登録されているツールチェーンと実行プラットフォームは、ツールチェーンの選択時に次の優先順位（高い順）に従います。

ルートモジュールの MODULE.bazel ファイルに登録されているツールチェーンと実行プラットフォーム。
WORKSPACE ファイルまたは WORKSPACE.bzlmod ファイルに登録されているツールチェーンと実行プラットフォーム。
ルートモジュールの（推移的）依存関係であるモジュールによって登録されたツールチェーンと実行プラットフォーム。
WORKSPACE.bzlmod を使用しない場合: WORKSPACE 接尾辞に登録されているツールチェーン。

ローカルリポジトリの概要

デバッグ用に依存関係のローカルバージョンが必要な場合や、ワークスペース内のディレクトリを外部リポジトリとして組み込む場合は、依存関係をローカルリポジトリとして導入する必要があります。

Google Workspace

WORKSPACE では、local_repository と new_local_repository の 2 つのネイティブリポジトリルールでこれを実現します。
```
## WORKSPACE
local_repository(
    name = "rules_java",
    path = "/Users/bazel_user/workspace/rules_java",
)
```
Bzlmod

Bzlmod では、local_path_override を使用して、ローカルパスでモジュールをオーバーライドできます。
```
## MODULE.bazel
bazel_dep(name = "rules_java")
local_path_override(
    module_name = "rules_java",
    path = "/Users/bazel_user/workspace/rules_java",
)
```
注: local_path_override を使用して Bazel モジュールとして導入できるのはローカルディレクトリのみです。つまり、MODULE.bazel ファイルが存在し、依存関係の解決時に推移的依存関係が考慮される必要があります。また、すべてのモジュールオーバーライドディレクティブは、ルートモジュールでのみ使用できます。
モジュール拡張機能を使用してローカルリポジトリを導入することもできます。ただし、モジュール拡張機能で native.local_repository を呼び出すことはできません。すべてのネイティブリポジトリルールを Starlark 化する作業が進行中です（進捗状況については #18285 をご覧ください）。その後、モジュール拡張機能で対応する starlark local_repository を呼び出すことができます。これがブロックの問題である場合は、local_repository リポジトリルールのカスタムバージョンを簡単に実装することもできます。

バインドターゲット

WORKSPACE の bind ルールは非推奨であり、Bzlmod ではサポートされていません。これは、特別な //external パッケージでターゲットにエイリアスを付与するために導入されました。これに依存しているすべてのユーザーは移行する必要があります。

たとえばチェックアウトマイクロサービスを呼び出す

## WORKSPACE
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

これにより、他のターゲットが //external:openssl に依存できるようになります。この問題を回避するには、次の方法で移行できます。

//external:openssl のすべての使用を @my-ssl//src:openssl-lib に置き換えます。
- ヒント: bazel query --output=build --noenable_bzlmod --enable_workspace [target] コマンドを使用して、ターゲットに関する関連情報を検索します。
または、alias ビルドルールを使用します。
- パッケージ（//third_party など）で次のターゲットを定義します。
```
## third_party/BUILD
alias(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)
```
- //external:openssl のすべての使用を //third_party:openssl に置き換えます。

取得と同期

fetch コマンドと sync コマンドは、外部リポジトリをローカルにダウンロードして最新の状態に保つために使用されます。ビルドに必要なすべてのリポジトリを取得した後、--nofetch フラグを使用してオフラインでビルドできるようにする場合もあります。

Google Workspace

Sync は、すべてのリポジトリまたは構成された特定のリポジトリのセットに対して強制フェッチを実行しますが、fetch は特定のターゲットのフェッチにのみ使用されます。
Bzlmod

sync コマンドは使用できなくなりましたが、fetch にはさまざまなオプションがあります。ターゲット、リポジトリ、構成済みリポジトリのセット、または依存関係の解決とモジュール拡張機能に関与するすべてのリポジトリを取得できます。フェッチ結果はキャッシュに保存されます。フェッチを強制するには、フェッチプロセスで --force オプションを指定する必要があります。

手動移行

このセクションでは、手動の Bzlmod 移行プロセスに役立つ情報とガイダンスを提供します。自動化された移行プロセスの詳細については、推奨される移行プロセスのセクションをご覧ください。

WORKSPACE の依存関係を把握する

移行の最初のステップは、依存関係を把握することです。推移的依存関係は *_deps マクロで読み込まれることが多いため、WORKSPACE ファイルで導入される正確な依存関係を把握することは難しい場合があります。

ワークスペース解決済みファイルを使用して外部依存関係を検査する

幸いなことに、フラグ --experimental_repository_resolved_file が役立ちます。このフラグは、基本的に、最後の Bazel コマンドで取得されたすべての外部依存関係の「ロックファイル」を生成します。詳しくは、こちらのブログ投稿をご覧ください。

次の 2 つの方法で使用できます。

特定のターゲットのビルドに必要な外部依存関係の情報を取得します。

bazel clean --expunge
bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar

WORKSPACE ファイルで定義されているすべての外部依存関係の情報を取得します。
```
bazel clean --expunge
bazel sync --experimental_repository_resolved_file=resolved.bzl
```
bazel sync コマンドを使用すると、WORKSPACE ファイルで定義されたすべての依存関係を取得できます。これには次のものが含まれます。
- bind の使用状況
- register_toolchains と register_execution_platforms の使用状況
ただし、プロジェクトがクロスプラットフォームの場合、一部のリポジトリルールはサポートされているプラットフォームでのみ正しく実行されるため、特定のプラットフォームで bazel sync が失敗することがあります。

コマンドを実行すると、外部依存関係の情報が resolved.bzl ファイルに保存されます。

`bazel query` を使用して外部依存関係を検査する

bazel query を使用して、次のリポジトリルールを検査することもできます。

bazel query --output=build //external:<repo name>

bazel query は外部依存関係のバージョンについて嘘をつく可能性があるため、使用には注意が必要です。Bzlmod を使用した外部依存関係のクエリと検査は、新しいサブコマンドによって実現されます。

組み込みのデフォルトの依存関係

--experimental_repository_resolved_file で生成されたファイルを確認すると、WORKSPACE で定義されていない依存関係が多数見つかります。これは、Bazel がユーザーの WORKSPACE ファイルのコンテンツに接頭辞と接尾辞を追加して、通常はネイティブルール（@bazel_tools、@platforms、@remote_java_tools など）で必要となるデフォルトの依存関係を挿入するためです。Bzlmod では、これらの依存関係は組み込みモジュール bazel_tools で導入されます。これは、他のすべての Bazel モジュールのデフォルトの依存関係です。

段階的な移行のためのハイブリッドモード

Bzlmod と WORKSPACE は並行して動作できるため、WORKSPACE ファイルから Bzlmod への依存関係の移行を段階的に行うことができます。

WORKSPACE.bzlmod

移行中、Bazel ユーザーは Bzlmod が有効になっているビルドと有効になっていないビルドを切り替える必要がある場合があります。プロセスをスムーズにするために、WORKSPACE.bzlmod のサポートが実装されています。

WORKSPACE.bzlmod の構文は WORKSPACE とまったく同じです。Bzlmod が有効になっている場合、ワークスペースのルートに WORKSPACE.bzlmod ファイルも存在する場合は、次のようになります。

WORKSPACE.bzlmod が有効になり、WORKSPACE の内容は無視されます。
WORKSPACE.bzlmod ファイルに接頭辞または接尾辞は追加されません。

WORKSPACE.bzlmod ファイルを使用すると、移行が容易になります。理由は次のとおりです。

Bzlmod が無効になっている場合、元の WORKSPACE ファイルから依存関係を取得するようにフォールバックします。
Bzlmod を有効にすると、WORKSPACE.bzlmod を使用して、移行する依存関係をより適切に追跡できます。

リポジトリの公開設定

Bzlmod は、特定のリポジトリから他のリポジトリを可視にするかどうかを制御できます。詳細については、リポジトリ名と厳密な依存関係をご覧ください。

WORKSPACE も考慮した場合の、さまざまなタイプのリポジトリのリポジトリの公開設定の概要は次のとおりです。

	メインリポジトリから	Bazel モジュールリポジトリから	モジュール拡張機能リポジトリから	WORKSPACE リポジトリから
メインリポジトリ	表示	ルートモジュールが直接依存関係の場合	ルートモジュールがモジュール拡張機能をホストするモジュールの直接の依存関係である場合	表示
Bazel モジュールリポジトリ	直接の依存関係	直接の依存関係	モジュール拡張機能をホストするモジュールの直接依存関係	ルートモジュールの直接依存関係
モジュール拡張機能リポジトリ	直接の依存関係	直接の依存関係	モジュール拡張機能をホストするモジュールの直接依存関係 + 同じモジュール拡張機能によって生成されたすべてのリポジトリ	ルートモジュールの直接依存関係
WORKSPACE リポジトリ	すべて表示	非表示	非表示	すべて表示

手動移行プロセス

一般的な Bzlmod 移行プロセスは次のようになります。

WORKSPACE にどのような依存関係があるかを把握します。
プロジェクトのルートに空の MODULE.bazel ファイルを追加します。
空の WORKSPACE.bzlmod ファイルを追加して、WORKSPACE ファイルの内容をオーバーライドします。
Bzlmod を有効にしてターゲットをビルドし、どのリポジトリが欠落しているかを確認します。
解決された依存関係ファイルで、不足しているリポジトリの定義を確認します。
不足している依存関係を Bazel モジュールとして、モジュール拡張機能を通じて導入するか、後で移行するために WORKSPACE.bzlmod に残します。
4 に戻り、すべての依存関係が使用可能になるまで繰り返します。

Bazel モジュールを公開する

Bazel プロジェクトが他のプロジェクトの依存関係である場合は、Bazel 中央レジストリにプロジェクトを公開できます。

BCR でプロジェクトをチェックインするには、プロジェクトのソースアーカイブ URL が必要です。ソースアーカイブを作成する際は、次の点に注意してください。

アーカイブが特定のバージョンを指していることを確認します。

BCR は、バージョン付きのソースアーカイブのみを受け入れることができます。これは、Bzlmod が依存関係の解決中にバージョン比較を行う必要があるためです。
アーカイブ URL が安定していることを確認します。

Bazel はハッシュ値でアーカイブの内容を検証するため、ダウンロードしたファイルのチェックサムが変更されないようにする必要があります。URL が GitHub のものである場合は、リリースページでリリースアーカイブを作成してアップロードしてください。GitHub は、オンデマンドで生成されたソースアーカイブのチェックサムを保証しません。つまり、https://github.com/<org>/<repo>/releases/download/... の形式の URL は安定していると見なされますが、https://github.com/<org>/<repo>/archive/... は安定しているとは見なされません。詳細については、GitHub アーカイブチェックサムの停止をご覧ください。
ソースツリーが元のリポジトリのレイアウトに従っていることを確認します。

リポジトリが非常に大きく、不要なソースを削除してサイズを縮小した配布アーカイブを作成する場合は、削除したソースツリーが元のソースツリーのサブセットであることを確認してください。これにより、エンドユーザーは archive_override と git_override を使用して、モジュールを非リリースバージョンに簡単にオーバーライドできます。
最も一般的な API をテストするテストモジュールをサブディレクトリに含めます。

テストモジュールは、ソースアーカイブのサブディレクトリに独自の WORKSPACE ファイルと MODULE.bazel ファイルを持つ Bazel プロジェクトです。このサブディレクトリは、公開される実際のモジュールに依存します。最も一般的な API をカバーする例や統合テストを含める必要があります。設定方法については、テストモジュールをご覧ください。

ソースアーカイブの URL が準備できたら、BCR 投稿ガイドラインに沿って、GitHub プルリクエストでモジュールを BCR に送信します。

リポジトリに Publish to BCR GitHub アプリを設定して、モジュールを BCR に送信するプロセスを自動化することを強くおすすめします。

ベストプラクティス

このセクションでは、外部依存関係をより適切に管理するために従うべきベストプラクティスをいくつか説明します。

不要な依存関係の取得を避けるため、ターゲットを異なるパッケージに分割します。

#12835 を確認してください。ここでは、テストのデベロッパー依存関係が、必要のないビルドターゲットのために不必要に取得されるようになっています。これは Bzlmod 固有のものではありませんが、このプラクティスに従うことで、開発依存関係を正しく指定しやすくなります。

開発依存関係を指定する

bazel_dep ディレクティブと use_extension ディレクティブの dev_dependency 属性を true に設定すると、依存プロジェクトに伝播されなくなります。ルートモジュールとして、--ignore_dev_dependency フラグを使用して、ターゲットが開発依存関係とオーバーライドなしでビルドされるかどうかを確認できます。

コミュニティの移行の進行状況

Bazel Central Registry を確認して、依存関係がすでに利用可能かどうかを確認できます。それ以外の場合は、この GitHub ディスカッションに参加して、移行を妨げている依存関係に賛成票を投じるか、投稿してください。

問題を報告する

既知の Bzlmod の問題については、Bazel GitHub の問題リストをご確認ください。移行のブロックを解除するのに役立つ新しい問題や機能リクエストを、お気軽にお送りください。

Bzlmod 移行ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Bzlmod に移行する理由

Bzlmod に移行する方法

移行ツール

コア機能

移行ツールの使用方法

WORKSPACE と Bzlmod

Bazel ワークスペースのルートを定義する

bazelrc で Bzlmod を有効にする

ワークスペースのリポジトリ名を指定する

外部依存関係を Bazel モジュールとして取得する

依存関係を Bazel モジュールとしてオーバーライドする

モジュール拡張機能を使用して外部依存関係をフェッチする

モジュール拡張機能を使用して外部依存関係の競合を解決する

サードパーティのパッケージ マネージャーを統合する

ホストマシン上のツールチェーンを検出する

ツールチェーンと実行プラットフォームを登録する

ローカル リポジトリの概要

バインド ターゲット

取得と同期

手動移行

WORKSPACE の依存関係を把握する

ワークスペース解決済みファイルを使用して外部依存関係を検査する

bazel query を使用して外部依存関係を検査する

組み込みのデフォルトの依存関係

段階的な移行のためのハイブリッド モード

WORKSPACE.bzlmod

リポジトリの公開設定

手動移行プロセス

Bazel モジュールを公開する

ベスト プラクティス

不要な依存関係の取得を避けるため、ターゲットを異なるパッケージに分割します。

開発依存関係を指定する

コミュニティの移行の進行状況

問題を報告する

Bzlmod 移行ガイド

サードパーティのパッケージマネージャーを統合する

ローカルリポジトリの概要

バインドターゲット

`bazel query` を使用して外部依存関係を検査する

段階的な移行のためのハイブリッドモード

ベストプラクティス