Bzlmod 移行ツール

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

注: AI を活用した Bzlmod 移行を試す場合は、Bzlmod 移行エージェントの設定をご覧ください。

コア機能

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

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

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

  • Bazel Central Registry で利用可能な依存関係
  • ユーザー定義のカスタム リポジトリ ルール
  • パッケージ マネージャーの依存関係
    • Maven
    • Go
    • Python

注意事項:

  • 移行ツールはベスト エフォート型のユーティリティです。推奨事項が正しいかどうかを必ず再確認してください。
  • 移行ツールは Bazel 7 で使用します（Bazel 8 ではサポートされていません）。

移行ツールの使用方法

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

  • 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 
migrate2bzlmod -t

このスクリプトで生成されるファイル

  • MODULE.bazel - Bzlmod の中心となるマニフェスト ファイル。プロジェクトのメタデータと、他の Bazel モジュールへの直接的な依存関係を宣言します。
  • migration_info.md - 移行ツールの実行方法に関する手順ガイドを提供するファイル。必要に応じて、移行プロセスの手動完了を支援するように設計されています。
  • resolved_deps.py - プロジェクトの WORKSPACE ファイルを分析して生成された、プロジェクトの外部依存関係の包括的なリストが含まれています。移行時の参照として使用されます。
  • query_direct_deps - 利用されたターゲットに関する移行関連の情報が含まれます。これは、プロジェクトの WORKSPACE ファイルで --output=build を使用して Bazel を呼び出すことで取得されます。このファイルは主に移行スクリプトで使用されます。
  • extension_for_XXX - モジュール拡張機能の定義を含むファイル。移行ツールは、標準の Bazel モジュールではないが、Bzlmod のモジュール拡張機能を使用して管理できる依存関係に対して、これらのファイルを生成します。

フラグ

この移行スクリプトで使用できるフラグは次のとおりです。

  • --t/--target: 移行するターゲット。このフラグは繰り返し可能で、ターゲットは累積されます。
  • --i/--initial: MODULE.bazel、resolved_deps.py、migration_info.md ファイルを削除して最初からやり直します。直接依存関係を検出し、MODULE.bazel に導入して、解決済みの依存関係の生成を再実行します。

移行後のクリーンアップ

  • migration_info.md、resolved_deps.py、query_direct_deps を削除します。
  • 移行に使用された MODULE.bazel ファイル（# -- bazel_dep definitions -- # など）からコメントを削除します。

移行の例

移行スクリプトの動作を確認するには、WORKSPACE ファイルで Python、Maven、Go の依存関係が宣言されている次のシナリオを検討してください。

WORKSPACE ファイルを表示するには、こちらをクリックしてください。 

workspace(name="example")

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

http_archive(
    name = "rules_cc",
    sha256 = "b8b918a85f9144c01f6cfe0f45e4f2838c7413961a8ff23bc0c6cdf8bb07a3b6",
    strip_prefix = "rules_cc-0.1.5",
    urls = ["https://github.com/bazelbuild/rules_cc/releases/download/0.1.5/rules_cc-0.1.5.tar.gz"],
)

# Module dependency
# -------------------
http_archive(
    name = "rules_shell",
    sha256 = "3e114424a5c7e4fd43e0133cc6ecdfe54e45ae8affa14fadd839f29901424043",
    strip_prefix = "rules_shell-0.4.0",
    url = "https://github.com/bazelbuild/rules_shell/releases/download/v0.4.0/rules_shell-v0.4.0.tar.gz",
)

# Repo rule
# -------------------
http_archive(
    name = "com_github_cockroachdb_cockroach",
    sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
    strip_prefix = "cockroach-22.1.6",
    url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
)

# Module extension
# -------------------
# Macro which invokes repository_rule
my_custom_macro(
    name = "my_custom_repo",
)

# Go dependencies
# -------------------
http_archive(
    name = "io_bazel_rules_go",
    integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
    urls = [
        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
        "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
    ],
)

http_archive(
    name = "bazel_gazelle",
    integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
    urls = [
        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
    ],
)

load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")

go_rules_dependencies()
go_register_toolchains(version = "1.23.1")
gazelle_dependencies()

go_repository(
    name = "org_golang_x_net",
    importpath = "golang.org/x/net",
    sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=",
    version = "v0.0.0-20190311183353-d8887717615a",
    build_file_proto_mode = "disable",
    build_naming_convention = "import",
)

# Python dependencies
# -------------------
http_archive(
    name = "rules_python",
    integrity = "sha256-qDdnnxOC8mlowe5vg5x9r5B5qlMSgGmh8oFd7KpjcwQ=",
    strip_prefix = "rules_python-1.4.0",
    url = "https://github.com/bazelbuild/rules_python/releases/download/1.4.0/rules_python-1.4.0.tar.gz",
)

load("@rules_python//python:repositories.bzl", "py_repositories")
py_repositories()

load("@rules_python//python:pip.bzl", "pip_parse")
pip_parse(
   name = "my_python_deps",
   requirements_lock = "@example//:requirements_lock.txt",
)

load("@my_python_deps//:requirements.bzl", "install_deps")
install_deps()

load("@rules_python//python:repositories.bzl", "python_register_toolchains")
python_register_toolchains(
    name = "python_3_11",
    python_version = "3.11",
)

# Maven dependencies
# __________________

RULES_JVM_EXTERNAL_TAG = "4.5"
RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6"

http_archive(
    name = "rules_jvm_external",
    strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
    sha256 = RULES_JVM_EXTERNAL_SHA,
    url = "https://github.com/bazelbuild/rules_jvm_external/archive/%s.zip" % RULES_JVM_EXTERNAL_TAG,
)

load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
rules_jvm_external_deps()
load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
rules_jvm_external_setup()

load("@rules_jvm_external//:defs.bzl", "maven_install")
maven_install(
    name = "px_deps",
    artifacts = [
        "org.antlr:antlr4:4.11.1",
    ],
    repositories = [
        "https://repo1.maven.org/maven2",
    ],
)

また、モジュール拡張機能の使用方法を示すために、WORKSPACE からカスタム マクロが呼び出され、my_custom_macro.bzl で定義されています。

my_custom_macro.bzl ファイルを表示するには、こちらをクリックしてください。 

"""Repo rule and macro used for testing"""

def _test_repo_rule_impl(repository_ctx):
    repository_ctx.file(
        "BUILD",
        content = """
genrule(
    name = "foo",
    outs = ["rule_name.out"],
    cmd = "touch $@",
    visibility = ["//visibility:public"],
)
"""
    )

_test_repo_rule = repository_rule(
    implementation = _test_repo_rule_impl,
)

def my_custom_macro(name):
    _test_repo_rule(name = name)

最終的な目標は、ユーザー エクスペリエンスに影響を与えることなく MODULE.bazel ファイルを作成し、WORKSPACE ファイルを削除することです。

最初の手順は、移行ツールの使用方法に沿って行うことです。主に、bazel バージョンの確認（Bazel 7 である必要があります）と、移行スクリプトへのエイリアスの追加を行います。

migrate2bzlmod -t=//... を実行すると、次の出力が得られます。

  bazel 7.6.1

  Generating ./resolved_deps.py file - It might take a while...

  RESOLVED: rules_java has been introduced as a Bazel module.
  RESOLVED: bazel_gazelle has been introduced as a Bazel module.
  RESOLVED: io_bazel_rules_go has been introduced as a Bazel module.
  RESOLVED: rules_python has been introduced as a Bazel module.
  IMPORTANT: 3.11 is used as a default python version. If you need a different version, please change it manually and then rerun the migration tool.
  RESOLVED: my_python_deps has been introduced as python extension.
  RESOLVED: org_golang_x_net has been introduced as go extension.
  RESOLVED: rules_jvm_external has been introduced as a Bazel module.
  RESOLVED: org.antlr has been introduced as maven extension.
  RESOLVED: rules_shell has been introduced as a Bazel module.

  Congratulations! All external repositories needed for building //... are available with Bzlmod!
  IMPORTANT: Fix potential build time issues by running the following command:
      bazel build --enable_bzlmod --noenable_workspace //...

  IMPORTANT: For details about the migration process, check `migration_info.md` file.

これにより、次の重要な情報が得られます。

  • WORKSPACE ファイルを使用して宣言および読み込まれたすべての外部リポジトリに関する情報を含む ./resolved_deps.py ファイルを生成します。
  • RESOLVED キーワードは、ツールによって解決され、MODULE.bazel ファイルに追加されるすべての依存関係を表します。
  • IMPORTANT キーワードは、時間をかける価値のある重要な情報を表します。
  • この例では、少なくとも --nobuild フラグを使用して、すべての依存関係が解決されています。
  • フルビルド（指定されたコマンド）を実行し、潜在的なエラー（ツールチェーンが正しく登録されていないなど）を手動で修正することが重要です。
  • migration_info.md ファイルには、移行の詳細が含まれています。詳しくは、こちらのセクションをご覧ください。

変換

このセクションでは、WORKSPACE ファイルから MODULE.bazel へのコードの移行について説明します。

WORKSPACE - Bazel モジュール

http_archive(
    name = "rules_shell",
    sha256 = "3e114424a5c7e4fd43e0133cc6ecdfe54e45ae8affa14fadd839f29901424043",
    strip_prefix = "rules_shell-0.4.0",
    url = "https://github.com/bazelbuild/rules_shell/releases/download/v0.4.0/rules_shell-v0.4.0.tar.gz",
)

MODULE.bazel - Bazel モジュール

bazel_dep(name = "rules_shell", version = "0.6.1")

WORKSPACE - Go 拡張機能

http_archive(
    name = "io_bazel_rules_go",
    integrity = "sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=",
    urls = [
        "https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
        "https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip",
    ],
)
http_archive(
    name = "bazel_gazelle",
    integrity = "sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=",
    urls = [
        "https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
        "https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz",
    ],
)

load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies")
load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies", "go_repository")

go_rules_dependencies()
go_register_toolchains(version = "1.23.1")
gazelle_dependencies()

go_repository(
    name = "org_golang_x_net",
    importpath = "golang.org/x/net",
    sum = "h1:oWX7TPOiFAMXLq8o0ikBYfCJVlRHBcsciT5bXOrH628=",
    version = "v0.0.0-20190311183353-d8887717615a",
    build_file_proto_mode = "disable",
    build_naming_convention = "import",
)

MODULE.bazel - Go 拡張機能

go_deps = use_extension("@bazel_gazelle//:extensions.bzl", "go_deps")
go_sdk = use_extension("@io_bazel_rules_go//go:extensions.bzl", "go_sdk")

go_deps.from_file(go_mod = "//:go.mod")
use_repo(go_deps, "org_golang_x_net")
go_sdk.from_file(go_mod = "//:go.mod")

go_deps.gazelle_override(
    path = "golang.org/x/net",
    directives = [
        "gazelle:proto disable",
         "gazelle:go_naming_convention import",
    ],
)

WORKSPACE - Python Extension

http_archive(
    name = "rules_python",
    integrity = "sha256-qDdnnxOC8mlowe5vg5x9r5B5qlMSgGmh8oFd7KpjcwQ=",
    strip_prefix = "rules_python-1.4.0",
    url = "https://github.com/bazelbuild/rules_python/releases/download/1.4.0/rules_python-1.4.0.tar.gz",
)

load("@rules_python//python:repositories.bzl", "py_repositories")
py_repositories()

load("@rules_python//python:pip.bzl", "pip_parse")
pip_parse(
   name = "my_python_deps",
   requirements_lock = "@example//:requirements_lock.txt",
)

load("@my_python_deps//:requirements.bzl", "install_deps")
install_deps()

load("@rules_python//python:repositories.bzl", "python_register_toolchains")
python_register_toolchains(
    name = "python_3_11",
    python_version = "3.11",
)

MODULE.bazel - Python 拡張機能

pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
pip.parse(
    hub_name = "my_python_deps",
    python_version = "3.11",
    requirements_lock = "//:requirements_lock.txt",
)
use_repo(pip, "my_python_deps")

python = use_extension("@rules_python//python/extensions:python.bzl", "python")
python.defaults(python_version = "3.11")
python.toolchain(python_version = "3.11")

WORKSPACE - Maven 拡張機能

RULES_JVM_EXTERNAL_TAG = "4.5"
RULES_JVM_EXTERNAL_SHA = "b17d7388feb9bfa7f2fa09031b32707df529f26c91ab9e5d909eb1676badd9a6"

http_archive(
    name = "rules_jvm_external",
    strip_prefix = "rules_jvm_external-%s" % RULES_JVM_EXTERNAL_TAG,
    sha256 = RULES_JVM_EXTERNAL_SHA,
    url = "https://github.com/bazelbuild/rules_jvm_external/archive/%s.zip" % RULES_JVM_EXTERNAL_TAG,
)

load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps")
rules_jvm_external_deps()
load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup")
rules_jvm_external_setup()

load("@rules_jvm_external//:defs.bzl", "maven_install")
maven_install(
    name = "px_deps",
    artifacts = [
        "org.antlr:antlr4:4.11.1",
    ],
    repositories = [
        "https://repo1.maven.org/maven2",
    ],
)

MODULE.bazel - Maven 拡張機能

bazel_dep(name = "rules_jvm_external", version = "6.8")

maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
use_repo(maven, "px_deps")

maven.artifact(
    name = "px_deps",
    group = "org.antlr",
    artifact = "antlr4",
    version = "4.11.1"
)

WORKSPACE - リポジトリルール

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

http_archive(
    name = "com_github_cockroachdb_cockroach",
    sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
    strip_prefix = "cockroach-22.1.6",
    url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
)

MODULE.bazel - Repo ルール

http_archive = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
  name = "com_github_cockroachdb_cockroach",
  url = "https://github.com/cockroachdb/cockroach/archive/v22.1.6.tar.gz",
  sha256 = "6c3568ef244ce6b874694eeeecb83ed4f5d5dff6cf037c952ecde76828a6c502",
  strip_prefix = "cockroach-22.1.6",
)

WORKSPACE - モジュール拡張機能

load(":my_custom_macro.bzl", "my_custom_macro")

my_custom_macro(
    name = "my_custom_repo",
)

MODULE.bazel - モジュール拡張機能

extension_for_my_custom_macro = use_extension("//:extension_for_my_custom_macro.bzl", "extension_for_my_custom_macro")
use_repo(extension_for_my_custom_macro, "my_custom_repo")

extension_for_my_custom_macro.bzl

load("//:my_custom_macro.bzl", "my_custom_macro")

def _extension_for_my_custom_macro_impl(ctx):
  my_custom_macro(
    name = "my_custom_repo",
  )

extension_for_my_custom_macro = module_extension(implementation = _extension_for_my_custom_macro_impl)

デバッグのヒント

このセクションでは、Bzlmod 移行中に発生する可能性のある問題のデバッグに役立つコマンドと情報を提供します。

ヒント

  • バージョンのオーバーライド - 依存関係のバージョンをアップグレードすると問題が発生することがあります。Bzlmod は、MVS アルゴリズムにより、依存関係のバージョンを変更する可能性があります。WORKSPACE で使用されていたものと同じバージョンまたは類似のバージョンを使用するには、single_version_override でオーバーライドします。これは WORKSPACE と Bzlmod の違いをデバッグするのに役立ちますが、この機能を長期的に使用することは避けるべきです。

    single_version_override(module_name = "{dep_name}", version = "{version}")

  • bazel mod コマンドを使用します。

    • show_repo コマンドを使用して、指定したリポジトリのバージョンを確認します。次に例を示します。

      bazel mod show_repo @rules_python

    • show_extension コマンドを使用して、モジュール拡張機能に関する情報を確認します。次に例を示します。

      bazel mod show_extension @rules_python//python/extensions:pip.bzl%pip

  • リポジトリのソースをモニタリングまたは制御する場合は、ベンダーモードを使用してリポジトリのローカルコピーを作成します。次に例を示します。

    bazel vendor --enable_bzlmod --vendor_dir=vendor_src --repo=@protobuf

移行レポートの生成

このファイルは、移行スクリプトの実行ごとに更新されます。初回実行の場合や、--i フラグが使用されている場合は、ゼロから生成されます。レポートには次の情報が含まれます。

  • ローカルテスト用のコマンド。
  • 直接依存関係のリスト（少なくともプロジェクトで直接使用されているもの）。

  • 各依存関係について、リポジトリが WORKSPACE ファイルで宣言された場所を確認するためのプルダウン メニュー。これはデバッグに特に役立ちます。これは次のように解釈できます。

    > Click here to see where and how the repo was declared in the WORKSPACE
file

  • 各依存関係について、MODULE.bazel ファイルでどのように実装されたか。前の移行の例では、次のようになります。

    1. Bazel モジュールの依存関係 - Migration of rules_python

      Found perfect name match in BCR: rules_python
Found partially name matches in BCR: rules_python_gazelle_plugin

It has been introduced as a Bazel module:
    `bazel_dep(name = "rules_python", version = "1.6.1")`
      • スクリプトは perfect name match を検出すると、自動的に使用します。エラーが発生した場合は、名前が正しく追加されたかどうかを再確認できます。

    2. Python 拡張機能 - Migration of my_python_deps

      pip.parse(
    hub_name = "my_python_deps",
    requirements_lock = "//:requirements_lock.txt",
    python_version = "3.11",
)
use_repo(pip, "my_python_deps")

    3. Maven 拡張機能 - Migration of org.antlr (px_deps):

      maven.artifact(
    name = "px_deps",
    group = "org.antlr",
    artifact = "antlr4",
    version = "4.11.1"
)

    4. Go 拡張機能 - Migration of org_golang_x_net

      go_deps.from_file(go_mod = "//:go.mod")
go_sdk.from_file(go_mod = "//:go.mod")

go_deps.gazelle_override(
    path = "golang.org/x/net",
    directives = [
        "gazelle:proto disable",
        "gazelle:go_naming_convention import",
    ],
)
      • go.mod の助けを借りて、Go モジュールとして導入されました。go.mod と go.sum が使用できない場合、go モジュールは MODULE.bazel ファイルに直接追加されます。
      • gazelle_override は、特定のディレクティブを追加するために使用されます。

フィードバック

コントリビューションを行う場合は、bazel-central-registry で Issue または PR を作成してください。