Bzlmod 移行ガイド

問題を報告open_in_new ソースを表示open_in_new

WORKSPACE の欠点により、Bzlmod は今後の Bazel リリースで以前の WORKSPACE システムを置き換える予定です。このガイドでは、プロジェクトを Bzlmod に移行し、WORKSPACE を削除して外部依存関係を取得する方法を説明します。

WORKSPACE と Bzlmod

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

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

WORKSPACE ファイルは Bazel プロジェクトのソースルートをマークします。Bazel バージョン 6.3 以降では、この役割は MODULE.bazel に置き換えられます。6.3 より前のバージョンの Bazel では、ワークスペースのルートに 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 レジストリまたはカスタム 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 モジュールの依存関係をさまざまな方法でオーバーライドできます。

詳しくは、overridesのセクションをご覧ください。

使用例については、サンプル リポジトリをご覧ください。

モジュール拡張機能を使用して外部依存関係を取得する

依存関係が 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",
  )
  

  内部では、モジュール拡張機能を使用して実装されています。単に Repo ルールを呼び出すだけではなく、より複雑なロジックを実行する必要がある場合は、モジュール拡張機能を自分で実装することもできます。定義を .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 では依存関係を解決するための適切な方法が用意されていないため、これは WORKSPACE の最大の課題の一つです。

• 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

疑似パッケージ マネージャーを統合する最小限の例については、サンプル リポジトリをご覧ください。

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

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 では、次の方法でツールチェーンを登録できます。

  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 サフィックスに登録されているツールチェーン。

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

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

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

  モジュール拡張を使用してローカル リポジトリを導入することもできます。ただし、モジュール拡張で native.local_repository を呼び出すことはできません。すべてのネイティブ リポジトリ ルールの明白化が進行中です（進行状況については #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 に置き換えます。

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

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

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

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

取得と同期

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

• Google Workspace

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

• 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_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 リポジトリから
メイン リポジトリ	visible	ルート モジュールが直接的な依存関係である場合	ルート モジュールが、モジュール拡張機能をホストするモジュールの直接的な依存関係である場合	visible
Bazel モジュール リポジトリ	Direct の依存関係	Direct の依存関係	モジュール拡張機能をホストするモジュールの直接依存関係	ルート モジュールの直接依存関係
モジュール拡張機能リポジトリ	Direct の依存関係	Direct の依存関係	モジュール拡張機能をホストするモジュール + 同じモジュール拡張機能によって生成されたすべてのリポジトリの直接依存関係	ルート モジュールの直接依存関係
WORKSPACE リポジトリ	すべて表示可能	非表示	非表示	すべて表示可能

@bar

移行プロセス

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

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

移行ツール

最初に、インタラクティブな Bzlmod 移行ヘルパー スクリプトが用意されています。

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

• WORKSPACE で解決されたファイルを生成して解析します。
• 人間が読める方法で、解決されたファイルからリポジトリ情報を出力します。
• bazel ビルドコマンドを実行して、認識されたエラー メッセージを検出し、移行方法を提案します。
• 依存関係が 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>

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 pull リクエストを使用してモジュールを BCR に送信します。

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

ベスト プラクティス

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

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

#12835 を確認してください。ここでは、テストの開発環境依存関係を必要としないターゲットをビルドする場合に、不必要に取得する必要があります。これは実際には Bzlmod 固有のものではありませんが、この方法に従うと、開発の依存関係を正しく指定しやすくなります。

開発環境の依存関係を指定する

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

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

依存関係がすでに利用可能かどうかは、Bazel Central Registry で確認できます。または、こちらの GitHub ディスカッションにお気軽に参加して、移行の妨げになっている依存関係に賛成または投稿してください。

問題を報告する

Bzlmod の既知の問題については、Bazel GitHub の問題リストをご覧ください。ぜひ、移行の障害となる新しい問題や機能リクエストをお送りください。