このページでは、マクロの基本的な使用方法について説明します。また、一般的なユースケース、デバッグ、規則についても説明します。
マクロは、ルールをインスタンス化できる BUILD
ファイルから呼び出される関数です。マクロは、主に既存のルールや他のマクロのカプセル化とコードの再利用に使用されます。読み込みフェーズの終わりまでに、マクロは存在しなくなり、Bazel にはインスタンス化されたルールの具体的なセットのみが表示されます。
用途
マクロの一般的なユースケースは、ルールを再利用する場合です。
たとえば、BUILD
ファイルの genrule は、コマンドにハードコードされた some_arg
引数を使用して //:generator
を使用してファイルを生成します。
genrule(
name = "file",
outs = ["file.txt"],
cmd = "$(location //:generator) some_arg > $@",
tools = ["//:generator"],
)
引数が異なるファイルをさらに生成する場合は、このコードをマクロ関数に抽出することをおすすめします。マクロを file_generator
とします。このマクロには name
パラメータと arg
パラメータがあります。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 にのみ公開設定値を割り当てています。これにより、マクロ作成者は、中間ルールの出力を非表示にして、ワークスペース内の他のターゲットから依存されないようにできます。
マクロの展開
マクロの機能を調べるには、--output=build
を指定して query
コマンドを使用し、展開されたフォームを表示します。
$ 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()
ステートメントを必要としないルール)は、native モジュールからインスタンス化できます。
def my_macro(name, visibility=None):
native.cc_library(
name = name,
srcs = ["main.cc"],
visibility = visibility,
)
パッケージ名(どの BUILD
ファイルがマクロを呼び出しているのかなど)を知る必要がある場合は、native.package_name() 関数を使用します。native
は .bzl
ファイルでのみ使用でき、WORKSPACE
ファイルや 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 workspace, such as due to repo mappings.
Label("@dep_of_my_ruleset//tools:foo"),
],
"//conditions:default": [],
}),
**kwargs,
)
デバッグ
bazel query --output=build //my/path:all
は、評価後のBUILD
ファイルを示しています。すべてのマクロ、グロブ、ループが展開されます。既知の制限事項: 現在、select
式は出力に表示されません。generator_function
(ルールを生成する関数)またはgenerator_name
(マクロの名前属性)に基づいて出力をフィルタできます。bash $ bazel query --output=build 'attr(generator_function, my_macro, //my/path:all)'
BUILD
ファイルでルールfoo
が生成される正確な場所を確認するには、次の方法を試します。BUILD
ファイルの上部付近に、次の行を挿入します。cc_library(name = "foo")
Bazel を実行します。ルールfoo
が作成されると(名前の競合が原因で)、例外が発生し、完全なスタック トレースが表示されます。デバッグには print を使用することもできます。読み込みフェーズ中に、メッセージが
DEBUG
ログ行として表示されます。まれなケースを除き、コードをデポに送信する前に、print
呼び出しを削除するか、debugging
パラメータ(デフォルトはFalse
)で条件付きにします。
エラー
エラーをスローするには、fail 関数を使用します。問題の内容と BUILD
ファイルの修正方法をユーザーに明確に説明します。
エラーをキャッチすることはできません。
def my_macro(name, deps, visibility=None):
if len(deps) < 2:
fail("Expected at least two values in deps")
# ...
規則
ルールをインスタンス化するすべてのパブリック関数(アンダースコアで始まる関数)には
name
引数が必要です。この引数は省略可能です(デフォルト値を指定しないでください)。パブリック関数では、Python の規則に沿って docstring を使用する必要があります。
BUILD
ファイルでは、マクロのname
引数は(位置引数ではなく)キーワード引数である必要があります。マクロによって生成されたルールの
name
属性には、接頭辞として name 引数を含める必要があります。たとえば、macro(name = "foo")
はcc_library
foo
と genrulefoo_gen
を生成できます。ほとんどの場合、オプション パラメータのデフォルト値は
None
です。None
はネイティブ ルールに直接渡すことができます。ネイティブ ルールでは、引数を渡していない場合と同様に扱われます。したがって、この目的で0
、False
、[]
に置き換える必要はありません。マクロのデフォルト値は複雑な場合や、時間の経過とともに変更される可能性があるため、作成したルールに従わなければなりません。また、デフォルト値に明示的に設定されたパラメータは、クエリ言語またはビルドシステムの内部からアクセスしたときに、設定されていないパラメータ(またはNone
に設定されたパラメータ)とは異なるように見えます。マクロにはオプションの
visibility
引数が必要です。