このページでは、マクロの使用の基本について説明します。一般的なユースケース、デバッグ、慣例についても説明します。
マクロは、BUILD ファイルから呼び出される関数で、ルールをインスタンス化できます。
マクロは主に、既存のルールや他のマクロのカプセル化とコードの再利用に使用されます。
マクロには、このページで説明するシンボリック マクロと、 レガシー マクロの 2 種類があります。可能な場合は、コードをわかりやすくするためにシンボリック マクロを使用することをおすすめします。
シンボリック マクロには、型付き引数（マクロが呼び出された場所を基準とした文字列からラベルへの変換）と、作成されたターゲットの可視性を制限して指定する機能があります。遅延評価（今後の Bazel リリースで追加予定）に対応するように設計されています。シンボリック マクロは、Bazel 8 でデフォルトで使用できます。このドキュメントで macros と記載されている場合は、シンボリック マクロ を指します。
シンボリック マクロの実行可能な例は、 サンプル リポジトリにあります。
用途
マクロは、.bzl ファイルで
macro() 関数を
2 つの必須パラメータ attrs と implementation を指定して呼び出すことで定義されます。
属性
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"}) になります。詳しくは、select をご覧ください。
属性の継承
マクロはルール（または別のマクロ）をラップすることを目的としていることが多く、マクロの作成者は、ラップされたシンボルの属性の大部分を **kwargs を使用して変更せずに、マクロのメイン ターゲット（またはメインの内部マクロ）に転送したいと考えています。
このパターンをサポートするために、マクロは、ルールまたは別の
マクロから属性を継承できます。これを行うには、ルールまたは
マクロ シンボルをmacro()'s
inherit_attrs引数に渡します。（ルールまたはマクロのシンボルの代わりに特別な文字列 "common"
を使用し、すべての Starlark ビルドルールに定義されている
共通属性を継承することもできます）。
継承されるのは公開属性のみで、マクロ独自の attrs ディクショナリ内の属性は、同じ名前の継承された属性をオーバーライドします。attrs ディクショナリの値として None を使用して、継承された属性を削除することもできます。
# macro/macro.bzl
my_macro = macro(
inherit_attrs = native.cc_library,
attrs = {
# override native.cc_library's `local_defines` attribute
"local_defines": attr.string_list(default = ["FOO"]),
# do not inherit native.cc_library's `defines` attribute
"defines": None,
},
...
)
必須ではない継承された属性のデフォルト値は、元の属性定義のデフォルト値に関係なく、常に None にオーバーライドされます。継承された必須ではない属性を調べるか変更する必要がある場合（たとえば、継承された tags 属性にタグを追加する場合）、マクロの実装関数で None のケースを処理する必要があります。
# macro/macro.bzl
def _my_macro_impl(name, visibility, tags, **kwargs):
# Append a tag; tags attr is an inherited non-mandatory attribute, and
# therefore is None unless explicitly set by the caller of our macro.
my_tags = (tags or []) + ["another_tag"]
native.cc_library(
...
tags = my_tags,
**kwargs,
)
...
実装
implementation は、マクロのロジックを含む関数を受け取ります。
実装関数は、多くの場合、1 つ以上のルールを呼び出してターゲットを作成します。通常、これらの関数は非公開です（先頭にアンダースコアが付いています）。慣例として、
マクロと同じ名前が付けられますが、先頭に _ が付き、末尾に
_impl が付きます。
属性への参照を含む単一の引数（ctx）を取るルール実装関数とは異なり、マクロ実装関数は引数ごとにパラメータを受け取ります。
# macro/macro.bzl
def _my_macro_impl(name, visibility, 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,
)
マクロが属性を継承する場合、その実装関数には、継承されたルールまたはサブマクロを呼び出す呼び出しに転送できる **kwargs 残留キーワード パラメータが必要です。 （これにより、継承元のルールまたはマクロが新しい属性を追加した場合でも、マクロが破損しないようにできます）。
宣言
マクロは、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 が作成されます。
ルール呼び出しと同様に、マクロ呼び出しの属性値が None に設定されている場合、その属性はマクロの呼び出し元によって省略されたものとして扱われます。たとえば、次の 2 つのマクロ呼び出しは同じです。
# pkg/BUILD
my_macro(name = "abc", srcs = ["src.cc"], deps = None)
my_macro(name = "abc", srcs = ["src.cc"])
これは通常、BUILD ファイルでは役に立ちませんが、マクロを別のマクロ内にプログラムでラップする場合に便利です。
詳細
作成されたターゲットの命名規則
シンボリック マクロによって作成されたターゲットまたはサブマクロの名前は、マクロの name パラメータと一致するか、name の後に _（推奨）、.、- を付けて接頭辞を付ける必要があります。たとえば、my_macro(name = "foo") は、foo という名前のファイルまたはターゲット、または foo_、foo-、foo. で始まるファイルまたはターゲット（foo_bar など）のみを作成できます。
マクロの命名規則に違反するターゲットまたはファイルは宣言できますが、ビルドすることはできず、依存関係として使用することもできません。
マクロ インスタンスと同じパッケージ内のマクロ以外のファイルとターゲットは、マクロ ターゲット名と競合する名前を付けないでください。 ただし、この排他性は強制されません。現在、シンボリック マクロのパフォーマンスを向上させるために 遅延評価を実装しています。 命名スキーマに違反するパッケージでは、パフォーマンスが低下します。
制限事項
シンボリック マクロには、レガシー マクロと比較して追加の制限があります。
シンボリック マクロ
name引数とvisibility引数を受け取る必要があります。implementation関数が必要です。- 値を返すことはできません。
- 引数を変更することはできません。
- 特別な
finalizerマクロでない限り、native.existing_rules()を呼び出すことはできません。 native.package()を呼び出すことはできません。glob()を呼び出すことはできません。native.environment_group()を呼び出すことはできません。- 名前が命名スキーマに準拠するターゲットを作成する必要があります。
- 宣言されていない入力ファイルや、引数として渡されていない入力ファイルを参照することはできません。
- 呼び出し元の非公開ターゲットを参照することはできません（詳しくは、 可視性とマクロをご覧ください）。
可視性とマクロ
可視性システムは、（シンボリック）マクロとその呼び出し元の実装 の詳細を保護するのに役立ちます。
デフォルトでは、シンボリック マクロで作成されたターゲットはマクロ自体内では表示されますが、マクロの呼び出し元には表示されません。マクロは、独自の visibility属性の値を転送することで、
ターゲットを公開 API として「エクスポート」できます。some_rule(..., visibility = visibility)
マクロの可視性の重要な考え方は次のとおりです。
可視性は、マクロを呼び出したパッケージではなく、ターゲットを宣言したマクロに基づいてチェックされます。
- つまり、同じパッケージ内にあるだけでは、あるターゲットが別のターゲットに表示されるわけではありません。これにより、マクロの内部ターゲットが、パッケージ内の他のマクロや最上位ターゲットの依存関係になるのを防ぐことができます。
ルールとマクロの両方のすべての
visibility属性には、ルールまたはマクロが呼び出された場所が自動的に含まれます。- したがって、ターゲットは、同じマクロ（またはマクロ内にない場合は
BUILDファイル）で宣言された他のターゲットに対して無条件に表示されます。
- したがって、ターゲットは、同じマクロ（またはマクロ内にない場合は
実際には、マクロが visibility を設定せずにターゲットを宣言すると、ターゲットはデフォルトでマクロの内部になります。（パッケージの
デフォルトの可視性はマクロ内では適用されません）。ターゲットをエクスポートすると、ターゲットは、マクロの呼び出し元がマクロの visibility 属性で指定した内容、マクロの呼び出し元自体のパッケージ、マクロ独自のコードに表示されます。別の考え方としては、マクロの可視性によって、マクロ自体以外の誰がマクロのエクスポートされたターゲットを表示できるかが決まります。
# tool/BUILD
...
some_rule(
name = "some_tool",
visibility = ["//macro:__pkg__"],
)
# macro/macro.bzl
def _impl(name, visibility):
cc_library(
name = name + "_helper",
...
# No visibility passed in. Same as passing `visibility = None` or
# `visibility = ["//visibility:private"]`. Visible to the //macro
# package only.
)
cc_binary(
name = name + "_exported",
deps = [
# Allowed because we're also in //macro. (Targets in any other
# instance of this macro, or any other macro in //macro, can see it
# too.)
name + "_helper",
# Allowed by some_tool's visibility, regardless of what BUILD file
# we're called from.
"//tool:some_tool",
],
...
visibility = visibility,
)
my_macro = macro(implementation = _impl, ...)
# pkg/BUILD
load("//macro:macro.bzl", "my_macro")
...
my_macro(
name = "foo",
...
)
some_rule(
...
deps = [
# Allowed, its visibility is ["//pkg:__pkg__", "//macro:__pkg__"].
":foo_exported",
# Disallowed, its visibility is ["//macro:__pkg__"] and
# we are not in //macro.
":foo_helper",
]
)
my_macro が visibility = ["//other_pkg:__pkg__"] で呼び出された場合、または
//pkg パッケージが default_visibility をその値に設定した場合、
//pkg:foo_exported は //other_pkg/BUILD 内または
//other_pkg:defs.bzl で定義されたマクロ内でも使用できますが、
//pkg:foo_helper は保護されたままになります。
マクロは、
visibility = ["//some_friend:__pkg__"]（内部ターゲットの場合）または
visibility = visibility + ["//some_friend:__pkg__"]（エクスポートされたターゲットの場合）を渡すことで、ターゲットがフレンド パッケージに表示されることを宣言できます。
マクロが公開
可視性（visibility = ["//visibility:public"]）でターゲットを宣言するのはアンチパターンです。これは、呼び出し元がより制限された可視性を指定した場合でも、ターゲットがすべてのパッケージに無条件に表示されるためです。
すべての可視性チェックは、現在実行中の最も内側のシンボリック マクロに対して行われます。ただし、可視性の委任メカニズムがあります。マクロがラベルを属性値として内部マクロに渡すと、内部マクロでのラベルの使用は外部マクロに対してチェックされます。詳しくは、 可視性のページをご覧ください。
レガシー マクロは可視性システムに対して完全に透過的であり、呼び出し元の BUILD ファイルまたはシンボリック マクロの場所であるかのように動作します。
ファイナライザと可視性
ルール ファイナライザで宣言されたターゲットは、通常のシンボリック マクロの可視性ルールに従うターゲットに加えて、ファイナライザ ターゲットのパッケージに表示されるすべてのターゲットも表示できます。
つまり、native.existing_rules() ベースのレガシー マクロをファイナライザに移行した場合でも、ファイナライザによって宣言されたターゲットは古い依存関係を表示できます。
ただし、シンボリック マクロでターゲットを宣言して、ファイナライザのターゲットが可視性システムでターゲットを表示できないようにすることは可能です。ファイナライザは native.existing_rules() を使用して属性をイントロスペクトできます。
Select
属性が configurable（デフォルト）で、その値が None でない場合、マクロ実装関数は属性値をトリビアルな select でラップされたものとして認識します。これにより、マクロの作成者は、属性値が 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"]}) に設定されます。これにより、実装関数が失敗した場合（たとえば、コードが deps[0] のように値にインデックスを付けようとした場合。これは select では許可されていません）、マクロの作成者は、select と互換性のあるオペレーションのみを使用するようにマクロを書き換えるか、属性を構成不可（attr.label_list(configurable = False)）としてマークするかを選択できます。後者により、ユーザーは select 値を渡すことができなくなります。
ルール ターゲットはこの変換を逆にして、トリビアルな select を無条件の値として保存します。上記の例では、_my_macro_impl がルール ターゲット my_rule(..., deps = deps) を宣言した場合、そのルール ターゲットの deps は ["//a"] として保存されます。これにより、select ラッピングによって、マクロによってインスタンス化されたすべてのターゲットにトリビアルな select 値が保存されることはありません。
構成可能な属性の値が None の場合、select でラップされません。これにより、my_attr == None などのテストは引き続き機能し、属性が計算されたデフォルト値を持つルールに転送されると、ルールは適切に動作します（つまり、属性がまったく渡されなかった場合と同様に動作します）。属性が None 値を取ることは常に可能ではありませんが、attr.label() 型と、継承された必須ではない属性では発生する可能性があります。
ファイナライザ
ルール ファイナライザは特別なシンボリック マクロです。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,
)
怠惰
重要: 現在、マクロの遅延展開と評価を実装しています。この機能は今後公開予定です。
現在、すべてのマクロは BUILD ファイルが読み込まれるとすぐに評価されます。これにより、コストのかかる無関係なマクロも含むパッケージ内のターゲットのパフォーマンスに悪影響が生じる可能性があります。今後、ファイナライザ以外のシンボリック マクロは、ビルドに必要な場合にのみ評価されます。接頭辞の命名スキーマを使用すると、リクエストされたターゲットに基づいて展開するマクロを Bazel が判断できます。
移行のトラブルシューティング
移行でよく発生する問題とその解決方法を以下に示します。
- レガシー マクロが
glob()を呼び出す
glob() 呼び出しを BUILD ファイル（または BUILD ファイルから呼び出されるレガシー マクロ）に移動し、ラベルリスト属性を使用して glob() 値をシンボリック マクロに渡します。
# BUILD file
my_macro(
...,
deps = glob(...),
)
- レガシー マクロに、有効な Starlark
attr型ではないパラメータがある。
可能な限り多くのロジックをネストされたシンボリック マクロにプルしますが、最上位のマクロはレガシー マクロのままにします。
- レガシー マクロが、命名スキーマに違反するターゲットを作成するルールを呼び出す
問題ありません。問題のあるターゲットに依存しないでください。命名チェックは自動的に無視されます。