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 をすでに採用しているルールセットのリストは次のとおりです。

• rules_jvm_external
• rules_go
• rules_python

疑似パッケージ マネージャーを統合する最小限の例は、 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",
  )
  

  注: 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 フラグを使用してオフラインでビルドできるようにする場合もあります。

• WORKSPACE

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

• Bzlmod

  sync コマンドは適用されなくなりましたが、fetch には さまざまなオプションがあります。 ターゲット、リポジトリ、構成済みリポジトリのセット、または依存関係の解決とモジュール拡張機能に関わるすべてのリポジトリを取得できます。fetch の結果はキャッシュに保存されます。強制的に fetch を行うには、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 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 で "*_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 に戻り、すべての依存関係が使用可能になるまで繰り返します。

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