モジュール拡張機能

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

モジュール拡張機能を使用すると、依存関係グラフ全体のモジュールから入力データを読み取り、依存関係を解決するために必要なロジックを実行し、repo ルールを呼び出してリポジトリを作成することで、モジュールシステムを拡張できます。これらの拡張機能は repo ルールと同様の機能を備えているため、ファイルの I/O やネットワークリクエストの送信などを行うことができます。特に、Bazel モジュールから構築された依存関係グラフを尊重しながら、Bazel が他のパッケージ管理システムとやり取りできるようにします。

repo ルールと同様に、.bzl ファイルでモジュール拡張機能を定義できます。モジュール拡張機能は直接呼び出されません。各モジュールは、拡張機能が読み取るデータの断片（タグ）を指定します。Bazel は、拡張機能を評価する前にモジュール解決を実行します。拡張機能は、依存関係グラフ全体で、その拡張機能に属するすべてのタグを読み取ります。

拡張機能の使用

拡張機能は Bazel モジュール自体でホストされます。モジュールで拡張機能を使用するには、まず、拡張機能をホストするモジュールにbazel_depを追加し、use_extension組み込み関数を呼び出してスコープに含めます。次の例は、 MODULE.bazel ファイルから「maven」拡張機能を使用するための rules_jvm_external モジュールのスニペットです。

bazel_dep(name = "rules_jvm_external", version = "4.5")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")

これにより、use_extension の戻り値が変数にバインドされ、ユーザーはドット構文を使用して拡張機能のタグを指定できます。タグは、拡張機能の定義で指定された対応するタグクラスによって定義されたスキーマに準拠する必要があります。 maven.install タグと maven.artifact タグを指定する例を次に示します。

maven.install(artifacts = ["org.junit:junit:4.13.2"])
maven.artifact(group = "com.google.guava",
               artifact = "guava",
               version = "27.0-jre",
               exclusions = ["com.google.j2objc:j2objc-annotations"])

use_repo ディレクティブを使用して、拡張機能によって生成されたリポジトリを現在のモジュールのスコープに含めます。

use_repo(maven, "maven")

拡張機能によって生成されたリポジトリは、その API の一部です。この例では、「maven」モジュール拡張機能はmavenというリポジトリを生成することを約束しています。上記の宣言により、拡張機能は @maven//:org_junit_junitなどのラベルを適切に解決して、「maven」拡張機能によって生成されたリポジトリを指すようにします。

拡張機能の定義

`module_extension` 関数を使用して、repo ルールと同様にモジュール拡張機能を定義できます。module_extensionただし、repo ルールには多数の属性がありますが、モジュール拡張機能には tag_classes があり、それぞれに多数の属性があります。タグクラスは、この拡張機能で使用されるタグのスキーマを定義します。たとえば、上記の「maven」拡張機能は次のように定義できます。

# @rules_jvm_external//:extensions.bzl

_install = tag_class(attrs = {"artifacts": attr.string_list(), ...})
_artifact = tag_class(attrs = {"group": attr.string(), "artifact": attr.string(), ...})
maven = module_extension(
  implementation = _maven_impl,
  tag_classes = {"install": _install, "artifact": _artifact},
)

これらの宣言は、maven.install タグと maven.artifact タグを指定された属性スキーマを使用して指定できることを示しています。

モジュール拡張機能の実装関数は、repo ルールの実装関数と似ていますが、module_ctxオブジェクトを取得します。このオブジェクトは、拡張機能を使用するすべてのモジュールとすべての関連タグへのアクセスを許可します。実装関数は、repo ルールを呼び出してリポジトリを生成します。

# @rules_jvm_external//:extensions.bzl

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")  # a repo rule
def _maven_impl(ctx):
  # This is a fake implementation for demonstration purposes only

  # collect artifacts from across the dependency graph
  artifacts = []
  for mod in ctx.modules:
    for install in mod.tags.install:
      artifacts += install.artifacts
    artifacts += [_to_artifact(artifact) for artifact in mod.tags.artifact]

  # call out to the coursier CLI tool to resolve dependencies
  output = ctx.execute(["coursier", "resolve", artifacts])
  repo_attrs = _process_coursier_output(output)

  # call repo rules to generate repos
  for attrs in repo_attrs:
    http_file(**attrs)
  _generate_hub_repo(name = "maven", repo_attrs)

拡張機能の ID

モジュール拡張機能は、`use_extension`の呼び出しに表示される名前と.bzlファイルによって識別されます。use_extension次の例では、拡張機能 maven は.bzlファイル@rules_jvm_external//:extension.bzlと名前mavenによって識別されます。

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

別の.bzlファイルから拡張機能を再エクスポートすると、新しい ID が割り当てられます。推移的なモジュールグラフで両方のバージョンの拡張機能が使用されている場合、それらは個別に評価され、その特定の ID に関連付けられたタグのみが表示されます。

拡張機能の作成者は、ユーザーが 1 つの.bzlファイルからのみモジュール拡張機能を使用するようにする必要があります。

リポジトリ名と公開設定

拡張機能によって生成されたリポジトリには、module_repo_canonical_name+extension_name+repo_nameという形式の正規名が付けられます。正規名形式は、依存すべき API ではありません。随時変更される可能性があります。

この命名ポリシーでは、各拡張機能に独自の「リポジトリ名前空間」があります。2 つの異なる拡張機能で、競合のリスクなしに同じ名前のリポジトリを定義できます。また、repository_ctx.name はリポジトリの正規名を報告します。これは、repo ルールの呼び出しで指定された名前と同じではありません。

モジュール拡張機能によって生成されたリポジトリを考慮すると、リポジトリの公開設定には次のルールがあります。

Bazel モジュールリポジトリは、MODULE.bazel ファイルを介して、bazel_dep と use_repo に導入されたすべてのリポジトリを表示できます。
モジュール拡張機能によって生成されたリポジトリは、拡張機能をホストするモジュールに表示されるすべてのリポジトリと、さらに同じモジュール拡張機能によって生成された他のすべてのリポジトリ（repo ルールの呼び出しで指定された名前を明示的な名前として使用）を表示できます。
- 競合が発生する可能性があります。モジュールリポジトリが明示的な名前 foo のリポジトリを表示でき、拡張機能が指定された名前 foo のリポジトリを生成する場合、その拡張機能によって生成されたすべてのリポジトリで foo は前者を参照します。
同様に、モジュール拡張機能の実装関数では、拡張機能によって作成されたリポジトリは、作成順序に関係なく、属性内の明示的な名前で相互に参照できます。
- モジュールに表示されるリポジトリとの競合が発生した場合、リポジトリルール属性に渡されるラベルを Labelの呼び出しでラップして、同じ名前の拡張機能によって生成されたリポジトリではなく、モジュールに表示されるリポジトリを参照するようにします。

モジュール拡張機能のリポジトリのオーバーライドと挿入

ルートモジュールは、 override_repo と inject_repo を使用して、モジュール拡張機能のリポジトリをオーバーライドまたは挿入できます。

例: `rules_java` の `java_tools` をベンダー提供のコピーに置き換える

# MODULE.bazel
local_repository = use_repo_rule("@bazel_tools//tools/build_defs/repo:local.bzl", "local_repository")
local_repository(
  name = "my_java_tools",
  path = "vendor/java_tools",
)

bazel_dep(name = "rules_java", version = "7.11.1")
java_toolchains = use_extension("@rules_java//java:extension.bzl", "toolchains")

override_repo(java_toolchains, remote_java_tools = "my_java_tools")

例: Go の依存関係をパッチして、システムの zlib ではなく `@zlib` に依存するようにする

# MODULE.bazel
bazel_dep(name = "gazelle", version = "0.38.0")
bazel_dep(name = "zlib", version = "1.3.1.bcr.3")

go_deps = use_extension("@gazelle//:extensions.bzl", "go_deps")
go_deps.from_file(go_mod = "//:go.mod")
go_deps.module_override(
  patches = [
    "//patches:my_module_zlib.patch",
  ],
  path = "example.com/my_module",
)
use_repo(go_deps, ...)

inject_repo(go_deps, "zlib")

# patches/my_module_zlib.patch
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -1,6 +1,6 @@
 go_binary(
     name = "my_module",
     importpath = "example.com/my_module",
     srcs = ["my_module.go"],
-    copts = ["-lz"],
+    cdeps = ["@zlib"],
 )

ベストプラクティス

このセクションでは、拡張機能を記述する際のベストプラクティスについて説明します。これにより、拡張機能は使いやすく、保守しやすく、時間の経過に伴う変化に適切に対応できます。

各拡張機能を個別のファイルに配置する

拡張機能が異なるファイルにある場合、1 つの拡張機能で別の拡張機能によって生成されたリポジトリを読み込むことができます。この機能を使用しない場合でも、後で必要になる場合に備えて、個別のファイルに配置することをおすすめします。拡張機能の ID はそのファイルに基づいているため、後で拡張機能を別のファイルに移動すると、公開 API が変更され、ユーザーにとって下位互換性のない変更になります。

再現性を指定してファクトを使用する

拡張機能が、同じ入力（拡張機能タグ、読み取るファイルなど）を指定すると常に同じリポジトリを定義し、特にチェックサムで保護されていないダウンロードに依存しない場合は、 extension_metadata を指定して reproducible = True を返すことを検討してください。これにより、Bazel はロックファイルへの書き込み時にこの拡張機能をスキップできるため、ロックファイルを小さく保ち、マージの競合が発生する可能性を減らすことができます。MODULE.bazelBazel は、再現可能な拡張機能の結果をサーバーの再起動後も保持される方法でキャッシュに保存するため、実行時間の長い拡張機能でも、パフォーマンスの低下を招くことなく再現可能としてマークできます。

拡張機能が、ビルドの外部から取得した事実上不変のデータ（通常はネットワークから取得）に依存しているが、ダウンロードを保護するためのチェックサムがない場合は、facts パラメータを使用して、そのようなデータを永続的に記録し、拡張機能を再現可能にすることを検討してください。extension_metadatafacts は、文字列キーと任意の JSON のような Starlark 値を持つディクショナリであることが想定されています。このディクショナリは常にロックファイルに保存され、拡張機能の今後の評価で facts フィールドを介して使用できます。module_ctx

factsはモジュール拡張機能のコードが変更されても無効にならないため、 factsの構造が変更される場合に備えてください。 Bazel は、同じ拡張機能の 2 つの異なる評価によって生成された 2 つの異なる facts ディクショナリを浅くマージできる（つまり、2 つのディクショナリで | 演算子を使用する場合と同様）と想定しています。これは、module_ctx.facts がエントリの列挙をサポートせず、キーによるルックアップのみをサポートすることで部分的に強制されます。

facts を使用する例としては、SDK のバージョン番号から、そのバージョンのダウンロード URL とチェックサムを含むオブジェクトへのマッピングを記録することが挙げられます。拡張機能が最初に評価されるときに、このマッピングをネットワークから取得できますが、後で評価するときにfacts のマッピングを使用してネットワークリクエストを回避できます。

オペレーティングシステムとアーキテクチャへの依存関係を指定する

拡張機能がオペレーティングシステムまたはそのアーキテクチャタイプに依存している場合は、ブール値属性を使用して、拡張機能の定義でこれを示すようにしてください。os_dependentarch_dependentこれにより、Bazel は、いずれかに変更があった場合に再評価が必要であることを認識します。

ホストへのこのような依存関係により、この拡張機能のロックファイルエントリの維持が難しくなるため、可能であれば拡張機能を再現可能としてマークすることを検討してください。

リポジトリ名に直接影響を与えるのはルートモジュールのみにする

拡張機能がリポジトリを作成すると、そのリポジトリは拡張機能の名前空間内に作成されます。つまり、異なるモジュールが同じ拡張機能を使用し、同じ名前のリポジトリを作成すると、競合が発生する可能性があります。これは多くの場合、モジュール拡張機能のtag_classに、リポジトリルールのname値として渡されるname 引数がある場合に発生します。

たとえば、ルートモジュール A がモジュール B に依存しているとします。どちらのモジュールもモジュールmylangに依存しています。A と B の両方が mylang.toolchain(name="foo")を呼び出すと、両方とも mylang モジュール内に fooという名前のリポジトリを作成しようとするため、エラーが発生します。

これを回避するには、リポジトリ名を直接設定する機能を削除するか、ルートモジュールのみが設定できるようにします。ルートモジュールには何も依存しないため、ルートモジュールにこの機能を許可しても問題ありません。別のモジュールが競合する名前を作成することを心配する必要はありません。