このページでは、マクロの基本的な使用方法について説明します。また、マクロの一般的な使用例も紹介します。 デバッグ、規則などについて学習します。
マクロは、ルールをインスタンス化できる 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",
)
ここでは、file_generator
シンボルを、次の場所にある .bzl
ファイルから読み込みます。
//path
パッケージ。マクロ関数の定義を個別の
.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 の出力を入力として使用します。
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
ファイルでのみ使用でき、BUILD
ファイルでは使用できません。
マクロでのラベルの解決
マクロは読み込みフェーズで評価されるため、
マクロ内に出現する "//foo:bar"
などのラベル文字列は解釈される
マクロが使用される BUILD
ファイルの相対パスではなく、
定義されている .bzl
ファイル。この動作は一般に、望ましい状態ではありません。
他のリポジトリで使用することを想定したマクロに使用しないでください。
公開済みの 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
(マクロの 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
パラメータ Depot です。
エラー
エラーをスローするには、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
と genrulefoo_gen
です。ほとんどの場合、オプション パラメータのデフォルト値は
None
です。None
はネイティブ ルールに直接渡すことができ、ネイティブ ルールと同じように扱われます。 渡していないことになります。そのため、既存のサーバーを0
、False
、または[]
に置き換えます。代わりに、マクロは デフォルトが複雑な場合や、ルールによって変更される可能性があるため、 あります。また、明示的にデフォルト値に設定されたパラメータは アクセス時に設定されていない(またはNone
に設定されている)ものとは異なっている クエリ言語またはビルドシステムの内部で 使用できますマクロには省略可能な
visibility
引数が必要です。