マクロ

<ph type="x-smartling-placeholder"></ph> 問題を報告するソースを表示夜間 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

このページでは、マクロの基本的な使用方法について説明します。また、マクロの一般的な使用例も紹介します。デバッグ、規則などについて学習します。

マクロは、ルールをインスタンス化できる 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 ファイルでのみ使用できます。WORKSPACE または 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 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（マクロの 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 と genrule foo_gen です。
ほとんどの場合、オプションパラメータのデフォルト値は None です。 None はネイティブルールに直接渡すことができ、ネイティブルールと同じように扱われます。渡していないことになります。そのため、既存のサーバーを 0、False、または [] に置き換えます。代わりに、マクロはデフォルトが複雑な場合や、ルールによって変更される可能性があるため、あります。また、明示的にデフォルト値に設定されたパラメータはアクセス時に設定されていない（または None に設定されている）ものとは異なっているクエリ言語またはビルドシステムの内部で使用できます
マクロには省略可能な visibility 引数が必要です。