Bzlmod 移行ガイド

問題を報告する ソースを表示 ナイトリー · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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 からマクロを読み込み、必要なデータ依存関係のバージョンを指定できます。@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 をすでに採用して、さまざまなパッケージ マネージャーから依存関係を取得しているルールセットのリストです。

• rules_jvm_external
• rules_go
• rules_python

疑似パッケージ マネージャーを統合する最小限のサンプルは、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 では、次の方法で toolchain を登録できます。

  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 接尾辞に登録されている toolchain。

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

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

• Google 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",
  )
  

  注: local_path_override では、ローカル ディレクトリを Bazel モジュールとしてのみ導入できます。つまり、MODULE.bazel ファイルが存在し、その推移的依存関係が依存関係解決時に考慮されます。また、すべてのモジュール オーバーライド ディレクティブは、ルート モジュールでのみ使用できます。

  モジュール拡張機能を使用してローカル リポジトリを導入することもできます。ただし、モジュール拡張機能で native.local_repository を呼び出すことはできません。すべてのネイティブ リポジトリ ルールを Starlark に変換するための取り組みは継続されています（進捗状況については #18285 をご覧ください）。次に、モジュール拡張機能で対応する Starlark local_repository を呼び出します。これがブロックの問題である場合は、local_repository リポジトリ ルールのカスタム バージョンを実装することも簡単です。

バインド ターゲット

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

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

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

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

• //external:openssl のすべての使用を @my-ssl//src:openssl-lib に置き換えます。

• または、alias ビルドルールを使用します。

  • パッケージに次のターゲットを定義します（例: //third_party）

    ## third_party/BUILD
    alias(
        name = "openssl",
        actual = "@my-ssl//src:openssl-lib",
    )
    

  • //external:openssl のすべての使用を //third_party:openssl に置き換えます。

取得と同期

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

• Google Workspace

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

• Bzlmod

  sync コマンドは使用できなくなりましたが、fetch にはさまざまなオプションがあります。ターゲット、リポジトリ、構成済みリポジトリのセット、または依存関係の解決とモジュール拡張に関連するすべてのリポジトリを取得できます。取得結果はキャッシュに保存されます。強制的に取得するには、取得プロセス中に --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 同期が中断することがあります。

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

bazel query を使用して外部依存関係を調べる

bazel query は、次のコマンドを使用してリポジトリ ルールを検査するために使用できることもご存じでしょう。

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

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

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

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

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

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

注: 実際には、WORKSPACE で「*_deps」マクロを読み込むと、Bzlmod の依存関係との混乱が生じることがよくあります。そのため、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 リポジトリ	すべて表示	非表示	非表示	すべて表示

注: ルート モジュールの場合、リポジトリ @foo が WORKSPACE で定義され、@foo が MODULE.bazel で見かけ上のリポジトリ名としても使用されている場合、@foo は MODULE.bazel で導入されたリポジトリを参照します。

注: モジュール拡張機能によって生成されたリポジトリ @bar の場合、@foo が同じモジュール拡張機能によって生成された別のリポジトリの見かけ上のリポジトリ名として使用され、モジュール拡張機能をホストするモジュールの直接依存関係である場合、リポジトリ @bar では @foo が後者を参照します。

移行プロセス

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

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

移行ツール

インタラクティブな Bzlmod 移行ヘルパー スクリプトを使用して、移行を開始できます。

このスクリプトは次のことを行います。

• WORKSPACE 解決ファイルを生成して解析します。
• 解決されたファイルのリポジトリ情報を人間が判読できる形式で出力します。
• bazel build コマンドを実行し、認識されたエラー メッセージを検出して、移行方法を提案します。
• BCR に依存関係がすでに存在するかどうかを確認します。
• MODULE.bazel ファイルに依存関係を追加します。
• モジュール拡張機能を使用して依存関係を追加します。
• WORKSPACE.bzlmod ファイルに依存関係を追加します。

使用するには、最新の Bazel リリースがインストールされていることを確認し、次のコマンドを実行します。

git clone https://github.com/bazelbuild/bazel-central-registry.git
cd <your workspace root>
<BCR repo root>/tools/migrate_to_bzlmod.py -t <your build targets>

注: 移行スクリプトは完全ではなく、Bzlmod は進化しているため最新の状態ではない可能性があります。推奨されるソリューションが正しいかどうかを常に確認してください。

Bazel モジュールを公開する

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

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

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

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

• アーカイブの 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 に送信します。

リポジトリに BCR に公開 GitHub アプリを設定することを強くおすすめします。これにより、BCR へのモジュールの送信プロセスを自動化できます。

ベスト プラクティス

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

不要な依存関係を取得しないように、ターゲットを異なるパッケージに分割します。

#12835 を確認してください。テスト用の開発依存関係が、それらを必要としないターゲットのビルドのために不必要に強制的にフェッチされています。これは実際には Bzlmod に固有のものではありませんが、この方法に従うと、開発依存関係を正しく指定しやすくなります。

開発依存関係を指定する

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

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

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

問題を報告する

既知の Bzlmod の問題については、Bazel GitHub の問題リストをご覧ください。移行のブロックを解除できる新しい問題や機能リクエストをお気軽に提出してください。