このページでは、マクロの基本的な使い方について説明し、一般的なユースケース、デバッグ、慣例を紹介します。
マクロは、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 にのみ可視性値を割り当てます。これにより、マクロ作成者は、中間ルールの出力がワークスペース内の他のターゲットから依存しないようにできます。
エキスパンド マクロ
マクロの動作を調査する場合は、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()
ステートメントを必要としないルール)は、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
ファイルの外観を示します。すべてのマクロ、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
属性には、接頭辞として名前引数を含める必要があります。たとえば、macro(name = "foo")
はcc_library
foo
と genrulefoo_gen
を生成できます。ほとんどの場合、オプションのパラメータのデフォルト値は
None
です。None
はネイティブ ルールに直接渡すことができます。この場合、引数を渡さなかった場合と同様に扱われます。したがって、この目的のために0
、False
、[]
に置き換える必要はありません。代わりに、マクロは作成したルールに従います。デフォルトのルールが複雑であったり、時間の経過とともに変化する可能性があるためです。また、明示的にデフォルト値に設定されているパラメータは、クエリ言語またはビルドシステム内部からアクセスされるときに設定されていない(またはNone
に設定されている)パラメータとは異なります。マクロにはオプションの
visibility
引数が必要です。