このページでは、マクロの基本的な使用方法について説明します。また、一般的なユースケース、デバッグ、規則についても説明します。
マクロは、ルールをインスタンス化できる 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
ファイルでのみ使用でき、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
ファイルの状態が表示されます。すべてのマクロ、グロブ、ループが展開されます。既知の制限事項: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
属性には、名前引数を接頭辞として含める必要があります。たとえば、macro(name = "foo")
はcc_library
foo
と genrulefoo_gen
を生成できます。ほとんどの場合、オプション パラメータのデフォルト値は
None
にする必要があります。None
はネイティブ ルールに直接渡すことができます。この場合、引数を渡さなかった場合と同じように処理されます。そのため、この目的で0
、False
、[]
に置き換える必要はありません。マクロのデフォルト値は複雑な場合や、時間の経過とともに変更される可能性があるため、作成したルールに従わなければなりません。また、明示的にデフォルト値に設定されたパラメータは、クエリ言語またはビルドシステムの内部からアクセスされた場合、設定されない(またはNone
に設定された)パラメータとは異なって見えます。マクロには、省略可能な
visibility
引数が必要です。