Bzlmod 移行ガイド

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

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

Bzlmod に移行する理由

  • 従来の WORKSPACE システムと比較して多くのメリットがあり、Bazel エコシステムの健全な成長に役立ちます。

  • プロジェクトが他のプロジェクトの依存関係である場合、Bzlmod に移行すると、他のプロジェクトの移行がブロックされなくなり、プロジェクトに依存しやすくなります。

  • Bzlmod への移行は、今後の Bazel バージョンを使用するために必要なステップです（Bazel 9 では必須）。

Bzlmod に移行する方法

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

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

WORKSPACE と Bzlmod

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

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

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

  • 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

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

  • WORKSPACE

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

    ## WORKSPACE
workspace(name = "com_foo_bar")

  • Bzlmod

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

    ## MODULE.bazel
module(
    name = "bar",
    repo_name = "com_foo_bar",
)

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

依存関係が Bazel プロジェクトの場合は、Bzlmod も採用すると、Bazel モジュールとして依存できます。

  • 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 registry で使用できる限り、 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 または モジュール 拡張機能を使用して導入できます。

  • 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
    )

  • 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 には依存関係を解決する適切な方法がないため、これは 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 ビルドルールでホストマシンで使用可能なツールチェーンを検出する必要がある場合、リポジトリ ルールを使用してホストマシンを検査し、ツールチェーン情報を外部リポジトリとして生成します。

  • 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 など）を導入したら、ツールチェーンを登録することをおすすめします。

  • WORKSPACE

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

    1. ツールチェーンを .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()

    2. または、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 ファイルに登録されているツールチェーンと実行プラットフォームは、ツールチェーンの選択時に次の 優先順位で処理されます（高い順）。

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

ローカル リポジトリを導入する

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

  • WORKSPACE

    WORKSPACE では、これは 2 つのネイティブ リポジトリ ルール local_repository と new_local_repository によって実現されます。

    ## 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",
)

    モジュール拡張機能を使用してローカル リポジトリを導入することもできます。 ただし、モジュール拡張機能で 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 に置き換えます。

取得と同期

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

  • WORKSPACE

    同期は、すべてのリポジトリまたは特定の構成済みリポジトリのセットに対して強制的に取得を実行しますが、取得は特定のターゲットの取得にのみ使用されます。

  • Bzlmod

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

手動移行

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

WORKSPACE の依存関係を把握する

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

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

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

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

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

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

  2. 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 移行プロセスは次のようになります。

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

Bazel モジュールを公開する

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

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 Pull Request を使用してモジュールを 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 の問題リストをご覧ください。移行のブロックを解除するのに役立つ新しい問題や機能リクエストを自由に提出してください。