このページでは、マクロの基本的な使用方法について説明します。また、一般的なユースケース、デバッグ、規則についても説明します。
マクロは、ルールをインスタンス化できる BUILD
ファイルから呼び出される関数です。マクロは主に、既存のルールやその他のマクロのカプセル化やコードの再利用に使用されます。読み込みフェーズが終わるまでに、マクロは存在しなくなり、Bazel はインスタンス化された具体的なルールセットのみを認識します。
使用量
マクロの一般的な使用例は、ルールを再利用したい場合です。
たとえば、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 にのみ割り当てられています。これにより、マクロ作成者は中間ルールの出力を非表示にして、ワークスペース内の他のターゲットから依存されないようにできます。
マクロの展開
マクロの機能を調べるには、--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
ファイルでのみ使用でき、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,
)
デバッグ
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)'
ルール
foo
がBUILD
ファイル内のどこで生成されたかを確認するには、次の方法を試します。BUILD
ファイルの先頭付近にcc_library(name = "foo")
という行を挿入します。Bazel を実行します。ルール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 の規則に沿って docstring を使用する必要があります。
BUILD
ファイルでは、マクロのname
引数は(位置引数ではなく)キーワード引数である必要があります。マクロによって生成されたルールの
name
属性には、接頭辞として name 引数を含める必要があります。たとえば、macro(name = "foo")
はcc_library
foo
と genrulefoo_gen
を生成できます。ほとんどの場合、オプション パラメータのデフォルト値は
None
です。None
はネイティブ ルールに直接渡すことができます。ネイティブ ルールでは、引数を渡していない場合と同様に扱われます。したがって、この目的で0
、False
、[]
に置き換える必要はありません。マクロのデフォルト値は複雑な場合や、時間の経過とともに変更される可能性があるため、作成したルールに従わなければなりません。また、明示的にデフォルト値に設定されたパラメータは、クエリ言語またはビルドシステムの内部からアクセスされた場合、設定されない(またはNone
に設定された)パラメータとは異なって見えます。マクロには省略可能な
visibility
引数が必要です。