従来のマクロ

従来のマクロは、ターゲットを作成できる BUILD ファイルから呼び出される構造化されていない関数です。読み込みフェーズの終了までに、従来のマクロは存在しなくなり、Bazel はインスタンス化されたルールの具体的なセットのみを認識します。

従来のマクロを使用すべきでない理由（代わりに Symbolic マクロを使用すべき理由）

可能な場合は、Symbolic マクロを使用してください。

Symbolic マクロ

• 遠隔操作を防止する
• きめ細かい可視性により実装の詳細を非表示にできる
• 型付き属性を取得する。つまり、ラベルと選択の自動変換が可能になる。
• 読みやすい
• まもなく遅延評価が可能になる

用途

マクロの一般的なユースケースは、ルールを再利用する場合です。

たとえば、BUILD ファイルの genrule は、コマンドに some_arg 引数がハードコードされた //:generator を使用してファイルを生成します。

genrule(
    name = "file",
    outs = ["file.txt"],
    cmd = "$(location //:generator) some_arg > $@",
    tools = ["//:generator"],
)

異なる引数を使用してさらに多くのファイルを生成する場合は、このコードをマクロ関数に抽出することをおすすめします。name パラメータと arg パラメータを持つ file_generator というマクロを作成するには、genrule を次のように置き換えます。

load("//path:generator.bzl", "file_generator")

file_generator(
    name = "file",
    arg = "some_arg",
)

file_generator(
    name = "file-two",
    arg = "some_arg_two",
)

file_generator(
    name = "file-three",
    arg = "some_arg_three",
)

ここで、//path パッケージにある .bzl ファイルから file_generator シンボルを読み込みます。マクロ関数定義を別の .bzl ファイルに配置することで、BUILD ファイルをクリーンで宣言型に保つことができます。.bzl ファイルは、ワークスペース内の任意のパッケージから読み込むことができます。

最後に、path/generator.bzl で、元の genrule 定義をカプセル化してパラメータ化するマクロの定義を記述します。

def file_generator(name, arg, visibility=None):
  native.genrule(
    name = name,
    outs = [name + ".txt"],
    cmd = "$(location //:generator) %s > $@" % arg,
    tools = ["//:generator"],
    visibility = visibility,
  )

マクロを使用してルールを連結することもできます。次の例は、連結された genrule を示しています。genrule は、前の genrule の出力を入力として使用します。

def chained_genrules(name, visibility=None):
  native.genrule(
    name = name + "-one",
    outs = [name + ".one"],
    cmd = "$(location :tool-one) $@",
    tools = [":tool-one"],
    visibility = ["//visibility:private"],
  )

  native.genrule(
    name = name + "-two",
    srcs = [name + ".one"],
    outs = [name + ".two"],
    cmd = "$(location :tool-two) $< $@",
    tools = [":tool-two"],
    visibility = visibility,
  )

この例では、2 番目の genrule にのみ可視性の値を割り当てています。これにより、マクロ作成者は、ワークスペース内の他のターゲットが依存しないように、中間ルールの出力を非表示にできます。

マクロの展開

マクロの動作を調べる場合は、query コマンドを --output=build で使用して、展開された形式を確認します。

$ bazel query --output=build :file
# /absolute/path/test/ext.bzl:42:3
genrule(
  name = "file",
  tools = ["//:generator"],
  outs = ["//test:file.txt"],
  cmd = "$(location //:generator) some_arg > $@",
)

ネイティブ ルールのインスタンス化

ネイティブ ルール（load() ステートメントを必要としないルール）は、ネイティブ モジュールからインスタンス化できます。

def my_macro(name, visibility=None):
  native.cc_library(
    name = name,
    srcs = ["main.cc"],
    visibility = visibility,
  )

パッケージ名（たとえば、マクロを呼び出している BUILD ファイル）を知る必要がある場合は、関数 native.package_name()を使用します。 native は .bzl ファイルでのみ使用でき、BUILD ファイルでは使用できません。

マクロでのラベル解決

従来のマクロは 読み込みフェーズで評価されるため、従来のマクロで発生する "//foo:bar"などのラベル文字列は、定義されている.bzlファイル ではなく、マクロが使用されている BUILDファイルを基準に解釈されます。この動作は、公開されている Starlark ルールセットの一部であるため、他のリポジトリで使用されるマクロには通常望ましくありません。

Starlark ルールと同じ動作にするには、ラベル文字列を Label コンストラクタでラップします。

# @my_ruleset//rules:defs.bzl
def my_cc_wrapper(name, deps = [], **kwargs):
  native.cc_library(
    name = name,
    deps = deps + select({
      # Due to the use of Label, this label is resolved within @my_ruleset,
      # regardless of its site of use.
      Label("//config:needs_foo"): [
        # Due to the use of Label, this label will resolve to the correct target
        # even if the canonical name of @dep_of_my_ruleset should be different
        # in the main repo, such as due to repo mappings.
        Label("@dep_of_my_ruleset//tools:foo"),
      ],
      "//conditions:default": [],
    }),
    **kwargs,
  )

--incompatible_resolve_select_keys_eagerly フラグが有効になっている場合、ラベル文字列であるすべてのキーは、Label オブジェクトを基準とした select 呼び出しを含むファイルのパッケージに自動的に解決されます。これを選択しない場合は、ラベル文字列を native.package_relative_label() でラップします。

デバッグ

• bazel query --output=build //my/path:all を使用すると、評価後の BUILD ファイルの様子を確認できます。すべての従来のマクロ、glob、ループが展開されます。 既知の制限事項: select 式は出力に表示されません。

• generator_function（ルールを生成した関数）または generator_name（マクロの名前属性）に基づいて出力をフィルタできます。bash $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'

• BUILD ファイルでルール foo が生成される場所を正確に確認するには、次の方法を試してください。 file の先頭付近に cc_library(name = "foo") という行を挿入します。BUILDBazel を実行します。ルール foo が作成されると（名前の競合が原因で）例外が発生し、完全なスタック トレースが表示されます。

• デバッグに print を使用することもできます。読み込みフェーズ中に、メッセージが DEBUG ログ行として表示されます。まれなケースを除き、コードをデポに送信する前に、print 呼び出しを削除するか、デフォルトで False に設定されている debugging パラメータの下で条件付きにします。

エラー

エラーをスローする場合は、fail 関数を使用します。何が問題だったのか、BUILD ファイルを修正する方法をユーザーにわかりやすく説明してください。エラーをキャッチすることはできません。

def my_macro(name, deps, visibility=None):
  if len(deps) < 2:
    fail("Expected at least two values in deps")
  # ...

規則

• ルールをインスタンス化するすべての公開関数（アンダースコアで始まらない関数）には、name 引数が必要です。この引数は省略可能にしないでください（デフォルト値を指定しないでください）。

• 公開関数では、 Python の規則に従ってドキュメント文字列を使用する必要があります。

• BUILD ファイルでは、マクロの name 引数はキーワード引数にする必要があります（位置引数ではありません）。

• マクロによって生成されたルールの name 属性には、名前引数を接頭辞として含める必要があります。たとえば、macro(name = "foo") は cc_library foo と genrule foo_gen を生成できます。

• ほとんどの場合、省略可能なパラメータのデフォルト値は None にする必要があります。 None はネイティブ ルールに直接渡すことができます。ネイティブ ルールでは、引数を渡さなかった場合と同じように処理されます。したがって、この目的で 0、False、[] に置き換える必要はありません。代わりに、マクロは作成するルールに委譲する必要があります。デフォルトは複雑な場合や、時間の経過とともに変更される可能性があるためです。また、クエリ言語またはビルドシステム内部からアクセスした場合、デフォルト値に明示的に設定されたパラメータは、設定されていないパラメータ（または None に設定されたパラメータ）とは異なります。

• マクロには、省略可能な visibility 引数が必要です。