BazelCon 2024 登録の受け付けを開始しました。

このページは Cloud Translation API によって翻訳されました。

マクロ

このページでは、マクロの基本的な使用方法について説明します。また、一般的なユースケース、デバッグ、規則についても説明します。

マクロは、ルールをインスタンス化できる BUILD ファイルから呼び出される関数です。マクロは主に、既存のルールや他のマクロのカプセル化とコードの再利用に使用されます。

マクロには、このページで説明するシンボリックマクロとレガシーマクロの 2 種類があります。可能であれば、コードの明確化のためにシンボリックマクロを使用することをおすすめします。

シンボリックマクロでは、型付き引数（マクロが呼び出された場所を基準とした文字列からラベルへの変換）と、作成されたターゲットの公開設定を制限して指定する機能が提供されます。遅延評価（今後の Bazel リリースで追加予定）に対応できるように設計されています。Bazel 8 では、シンボリックマクロがデフォルトで使用できます。このドキュメントで macros と記載されている場合は、シンボリックマクロを指しています。

用途

マクロは、attrs と implementation の 2 つのパラメータを指定して macro() 関数を呼び出すことで、.bzl ファイルで定義されます。

属性

attrs は、属性名と属性タイプのディクショナリを受け取り、マクロの引数を表します。2 つの一般的な属性（name と visibility）は、すべてのマクロに暗黙的に追加され、attrs に渡される辞書には含まれません。

# macro/macro.bzl
my_macro = macro(
    attrs = {
        "deps": attr.label_list(mandatory = True, doc = "The dependencies passed to the inner cc_binary and cc_test targets"),
        "create_test": attr.bool(default = False, configurable = False, doc = "If true, creates a test target"),
    },
    implementation = _my_macro_impl,
)

属性型宣言は、パラメータ mandatory、default、doc を受け入れます。ほとんどの属性タイプは、configurable パラメータも受け入れます。このパラメータは、属性が select を受け入れるかどうかを決定します。属性が configurable の場合、select 以外の値は構成不可の select として解析されます。"foo" は select({"//conditions:default": "foo"}) になります。詳しくは、選択をご覧ください。

実装

implementation は、マクロのロジックを含む関数を受け入れます。実装関数は、多くの場合、1 つ以上のルールを呼び出してターゲットを作成します。通常、実装関数は非公開で（先頭にアンダースコアが付いています）。通常、マクロと同じ名前にしますが、接頭辞に _ を付け、末尾に _impl を付けます。

属性への参照を含む単一の引数（ctx）を取るルール実装関数とは異なり、マクロ実装関数は引数ごとにパラメータを受け付けます。

# macro/macro.bzl
def _my_macro_impl(name, deps, create_test):
    cc_library(
        name = name + "_cc_lib",
        deps = deps,
    )

    if create_test:
        cc_test(
            name = name + "_test",
            srcs = ["my_test.cc"],
            deps = deps,
        )

宣言

マクロは、BUILD ファイル内の定義を読み込んで呼び出すことで宣言します。


# pkg/BUILD

my_macro(
    name = "macro_instance",
    deps = ["src.cc"] + select(
        {
            "//config_setting:special": ["special_source.cc"],
            "//conditions:default": [],
        },
    ),
    create_tests = True,
)

これにより、ターゲット //pkg:macro_instance_cc_lib と //pkg:macro_instance_test が作成されます。

詳細

作成されるターゲットの命名規則

シンボリックマクロによって作成されたターゲットまたはサブマクロの名前は、マクロの name パラメータと一致するか、name の前に _（推奨）、.、または - を付ける必要があります。たとえば、my_macro(name = "foo") で作成できるファイルやターゲットは、foo という名前のか、foo_、foo-、foo. の接頭辞（foo_bar など）のみです。

マクロの命名規則に違反するターゲットまたはファイルは宣言できますが、ビルドすることはできず、依存関係として使用することもできません。

マクロインスタンスと同じパッケージ内のマクロ以外のファイルとターゲットの名前は、マクロターゲット名と競合する名前にしない必要がありますが、この排他性は適用されません。Google では、シンボリックマクロのパフォーマンス改善として遅延評価の実装を進めています。この実装は、命名スキーマに違反するパッケージでは損なわれます。

restrictions

シンボリックマクロには、従来のマクロと比較していくつかの制限があります。

シンボリックマクロ

name 引数と visibility 引数を取る必要があります
implementation 関数が必要です
値が返されない
args を変更できない
特別な finalizer マクロでない限り、native.existing_rules() を呼び出せない
native.package() に電話できない
glob() に電話できない
native.environment_group() を呼び出せない
命名スキーマに準拠した名前のターゲットを作成する必要がある
宣言されていない、または引数として渡されていない入力ファイルを参照することはできません（詳しくは、visibility をご覧ください）。

公開設定

TODO: このセクションを展開

ターゲットの可視性

デフォルトでは、シンボリックマクロによって作成されたターゲットは、作成されたパッケージに表示されます。また、visibility 属性も受け入れます。これにより、マクロの呼び出し元（マクロ呼び出しから作成されたターゲットに visibility 属性を直接渡すことによって）と他のパッケージ（ターゲットの公開設定で明示的に指定することによって）に公開範囲を拡張できます。

依存関係の可視性

マクロには、参照するファイルとターゲットへの公開設定が必要です。次のいずれかの方法で行うことができます。

attr 値として明示的にマクロに渡される


# pkg/BUILD
my_macro(... deps = ["//other_package:my_tool"] )

attr 値の暗黙的なデフォルト

# my_macro:macro.bzl
my_macro = macro(
  attrs = {"deps" : attr.label_list(default = ["//other_package:my_tool"])} )

マクロ定義にすでに表示されている

# other_package/BUILD
cc_binary(
    name = "my_tool",
    visibility = "//my_macro:\\__pkg__",
)

選択

属性が configurable の場合、マクロ実装関数は常に属性値を select 値と見なします。たとえば、次のマクロについて考えてみましょう。

my_macro = macro(
    attrs = {"deps": attr.label_list()},  # configurable unless specified otherwise
    implementation = _my_macro_impl,
)

my_macro が deps = ["//a"] で呼び出されると、_my_macro_impl が呼び出され、deps パラメータが select({"//conditions:default": ["//a"]}) に設定されます。

ルールターゲットは、この変換を逆にして、単純な select を無条件の値として保存します。この例では、_my_macro_impl がルールターゲット my_rule(..., deps = deps) を宣言すると、そのルールターゲットの deps は ["//a"] として保存されます。

ファイナライザ

ルールファイナライザは、BUILD ファイル内の字句位置に関係なく、ファイナライザ以外のすべてのターゲットが定義された後、パッケージの読み込みの最終段階で評価される特別な記号マクロです。通常のシンボリックマクロとは異なり、ファイナライザは native.existing_rules() を呼び出すことができます。この場合、従来のマクロとは動作が少し異なります。ファイナライザ以外のルールターゲットのセットのみが返されます。ファイナライザは、そのセットの状態をアサートするか、新しいターゲットを定義します。

ファイナライザを宣言するには、finalizer = True を指定して macro() を呼び出します。

def _my_finalizer_impl(name, visibility, tags_filter):
    for r in native.existing_rules().values():
        for tag in r.get("tags", []):
            if tag in tags_filter:
                my_test(
                    name = name + "_" + r["name"] + "_finalizer_test",
                    deps = [r["name"]],
                    data = r["srcs"],
                    ...
                )
                continue

my_finalizer = macro(
    attrs = {"tags_filter": attr.string_list(configurable = False)},
    implementation = _impl,
    finalizer = True,
)

怠け行為

重要: Google では、遅延マクロ展開と評価の実装を進めています。この機能はまだご利用いただけません。

現在、すべてのマクロは BUILD ファイルが読み込まれるとすぐに評価されます。これにより、関連性のないコストの高いマクロも含まれているパッケージ内のターゲットのパフォーマンスに悪影響が及ぶ可能性があります。今後、ファイナライザ以外のシンボリックマクロは、ビルドに必要な場合にのみ評価されます。接頭辞命名スキーマは、Bazel がリクエストされたターゲットに基づいて展開するマクロを判断するのに役立ちます。

移行のトラブルシューティング

移行に関する一般的な問題とその解決方法は次のとおりです。

従来のマクロが glob() を呼び出す

glob() 呼び出しを BUILD ファイル（または BUILD ファイルから呼び出される以前のマクロ）に移動し、label-list 属性を使用して glob() 値をシンボリックマクロに渡します。

# BUILD file
my_macro(
    ...,
    deps = glob(...),
)

以前のマクロに、有効な Starlark attr 型ではないパラメータが含まれています。

ネストされたシンボリックマクロにできるだけ多くのロジックを組み込みますが、最上位のマクロはレガシーマクロのままにします。

以前のマクロが、命名スキーマに違反するターゲットを作成するルールを呼び出す

問題ありません。ただし、「問題のある」ターゲットに依存しないでください。命名チェックは無視されます。