BazelCon 2024 登録の受け付けを開始しました。

このページは Cloud Translation API によって翻訳されました。

ルールのチュートリアル

7.3 · 7.2 · 7.1 · 7.0 · 6.5

Starlark は、もともと Bazel での使用のために開発された Python のような構成言語で、その後他のツールでも採用されています。Bazel の BUILD ファイルと .bzl ファイルは、Starlark の一種である「Build Language」で記述されています。ただし、特に Bazel の組み込みまたは「ネイティブ」な部分ではなく、Build Language で記述されていることを強調する場合は、単に「Starlark」と呼ばれることもあります。Bazel では、コア言語に glob、genrule、java_binary などの多数のビルド関連関数を追加しています。

詳細については、Bazel と Starlark のドキュメントをご覧ください。新しいルールセットの開始点として、Rules SIG テンプレートもご覧ください。

空のルール

最初のルールを作成するには、foo.bzl ファイルを作成します。

def _foo_binary_impl(ctx):
    pass

foo_binary = rule(
    implementation = _foo_binary_impl,
)

rule 関数を呼び出す場合は、コールバック関数を定義する必要があります。ロジックはここに配置しますが、今のところ関数は空のままにしておきます。ctx 引数は、ターゲットに関する情報を提供します。

ルールは、BUILD ファイルから読み込んで使用できます。

同じディレクトリに BUILD ファイルを作成します。

load(":foo.bzl", "foo_binary")

foo_binary(name = "bin")

これで、ターゲットをビルドできるようになりました。

$ bazel build bin
INFO: Analyzed target //:bin (2 packages loaded, 17 targets configured).
INFO: Found 1 target...
Target //:bin up-to-date (nothing to build)

このルールは何も行いませんが、すでに他のルールと同様に動作します。名前が必須であり、visibility、testonly、tags などの一般的な属性をサポートしています。

評価モデル

先に進む前に、コードの評価方法を理解しておくことが重要です。

print ステートメントを使用して foo.bzl を更新します。

def _foo_binary_impl(ctx):
    print("analyzing", ctx.label)

foo_binary = rule(
    implementation = _foo_binary_impl,
)

print("bzl file evaluation")

BUILD:

load(":foo.bzl", "foo_binary")

print("BUILD file")
foo_binary(name = "bin1")
foo_binary(name = "bin2")

ctx.label は、分析対象のターゲットのラベルに対応します。ctx オブジェクトには、有用なフィールドとメソッドが多数あります。詳しくは、API リファレンスをご覧ください。

コードをクエリします。

$ bazel query :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
//:bin2
//:bin1

次のことを確認します。

「bzl file analysis」が最初に出力されます。BUILD ファイルを評価する前に、Bazel は読み込まれるすべてのファイルを評価します。複数の BUILD ファイルが foo.bzl を読み込む場合、Bazel は評価結果をキャッシュに保存するため、「bzl file Evaluation」は 1 回しか表示されません。
コールバック関数 _foo_binary_impl は呼び出されません。Bazel クエリは BUILD ファイルを読み込みますが、ターゲットを分析しません。

ターゲットを分析するには、cquery（「構成済みクエリ」）または build コマンドを使用します。

$ bazel build :all
DEBUG: /usr/home/bazel-codelab/foo.bzl:8:1: bzl file evaluation
DEBUG: /usr/home/bazel-codelab/BUILD:2:1: BUILD file
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin1
DEBUG: /usr/home/bazel-codelab/foo.bzl:2:5: analyzing //:bin2
INFO: Analyzed 2 targets (0 packages loaded, 0 targets configured).
INFO: Found 2 targets...

ご覧のとおり、_foo_binary_impl は 2 回（ターゲットごとに 1 回）呼び出されるようになりました。

一部のリーダーでは、foo.bzl の評価が bazel query の呼び出し後にキャッシュに保存されていますが、「bzl file Evaluation」が再度出力されています。Bazel はコードを再評価せず、出力イベントのみをリプレイします。キャッシュの状態に関係なく、同じ出力が得られます。

ファイルの作成

ルールをより有用にするには、ファイルを生成するように更新します。まず、ファイルを宣言して名前を付けます。この例では、ターゲットと同じ名前のファイルを作成します。

ctx.actions.declare_file(ctx.label.name)

ここで bazel build :all を実行すると、エラーが発生します。

The following files have no generating action:
bin2

ファイルを宣言するたびに、アクションを作成してファイルを生成する方法を Bazel に指示する必要があります。ctx.actions.write を使用して、指定された内容のファイルを作成します。

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello\n",
    )

コードは有効ですが、何の動作も起こりません。

$ bazel build bin1
Target //:bin1 up-to-date (nothing to build)

ctx.actions.write 関数はアクションを登録し、Bazel にファイルの生成方法を教えました。ただし、Bazel は、ファイルが実際にリクエストされるまでファイルを作成しません。最後に、ファイルがルールの実装内で使用される一時ファイルではなく、ルールの出力であることを Bazel に伝えます。

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello!\n",
    )
    return [DefaultInfo(files = depset([out]))]

後で DefaultInfo 関数と depset 関数を確認します。ここでは、ルールの出力を最後の行で選択するとします。

次に、Bazel を実行します。

$ bazel build bin1
INFO: Found 1 target...
Target //:bin1 up-to-date:
  bazel-bin/bin1

$ cat bazel-bin/bin1
Hello!

ファイルが正常に生成されました。

属性

ルールをより有用なものにするには、attr モジュールを使用して新しい属性を追加し、ルール定義を更新します。

username という文字列属性を追加します。

foo_binary = rule(
    implementation = _foo_binary_impl,
    attrs = {
        "username": attr.string(),
    },
)

次に、BUILD ファイルで設定します。

foo_binary(
    name = "bin",
    username = "Alice",
)

コールバック関数の値にアクセスするには、ctx.attr.username を使用します。次に例を示します。

def _foo_binary_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name)
    ctx.actions.write(
        output = out,
        content = "Hello {}!\n".format(ctx.attr.username),
    )
    return [DefaultInfo(files = depset([out]))]

この属性は必須にすることも、デフォルト値を設定することもできます。詳しくは、attr.string のドキュメントをご覧ください。ブール値や整数のリストなど、他のタイプの属性を使用することもできます。

依存関係

attr.label や attr.label_list などの依存関係属性は、その属性を所有するターゲットから、属性の値にラベルが表示されるターゲットへの依存関係を宣言します。この種の属性は、ターゲットグラフの基礎を形成します。

BUILD ファイルでは、ターゲットラベルは //pkg:name などの文字列オブジェクトとして表示されます。実装関数では、ターゲットに Target オブジェクトとしてアクセスできます。たとえば、Target.files を使用してターゲットから返されたファイルを表示します。

複数のファイル

デフォルトでは、ルールによって作成されたターゲットのみが依存関係として表示されます（foo_library() ターゲットなど）。入力ファイルであるターゲット（リポジトリ内のソースファイルなど）を属性で受け入れるようにする場合は、allow_files を使用して、受け入れ可能なファイル拡張子のリストを指定します（または、任意のファイル拡張子を許可する True を指定します）。

"srcs": attr.label_list(allow_files = [".java"]),

ファイルのリストには ctx.files.<attribute name> でアクセスできます。たとえば、srcs 属性のファイルのリストには、次のコマンドでアクセスできます。

ctx.files.srcs

単一ファイル

必要なファイルが 1 つだけの場合は、allow_single_file を使用します。

"src": attr.label(allow_single_file = [".java"])

このファイルは ctx.file.<attribute name> でアクセスできます。

ctx.file.src

テンプレートを使用してファイルを作成する

テンプレートに基づいて .cc ファイルを生成するルールを作成できます。また、ctx.actions.write を使用して、ルール実装関数で構築された文字列を出力することもできますが、これには 2 つの問題があります。まず、テンプレートのサイズが大きくなるほど、テンプレートを別のファイルに入れて、分析フェーズで大きな文字列を作成せずに済み、メモリ効率が上がります。次に、別のファイルを使用する方が便利です。代わりに、テンプレートファイルの置換を実行する ctx.actions.expand_template を使用してください。

template 属性を作成して、テンプレートファイルへの依存関係を宣言します。

def _hello_world_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name + ".cc")
    ctx.actions.expand_template(
        output = out,
        template = ctx.file.template,
        substitutions = {"{NAME}": ctx.attr.username},
    )
    return [DefaultInfo(files = depset([out]))]

hello_world = rule(
    implementation = _hello_world_impl,
    attrs = {
        "username": attr.string(default = "unknown person"),
        "template": attr.label(
            allow_single_file = [".cc.tpl"],
            mandatory = True,
        ),
    },
)

ルールは次のように使用できます。

hello_world(
    name = "hello",
    username = "Alice",
    template = "file.cc.tpl",
)

cc_binary(
    name = "hello_bin",
    srcs = [":hello"],
)

テンプレートをエンドユーザーに公開せず、常に同じテンプレートを使用する場合、デフォルト値を設定して属性を非公開にできます。

    "_template": attr.label(
        allow_single_file = True,
        default = "file.cc.tpl",
    ),

アンダースコアで始まる属性は非公開であり、BUILD ファイルで設定することはできません。テンプレートは暗黙的な依存関係になります。すべての hello_world ターゲットには、このファイルに対する依存関係があります。BUILD ファイルを更新して exports_files を使用し、このファイルを他のパッケージに表示できるようにしてください。

exports_files(["file.cc.tpl"])

さらに先へ

ルールのリファレンスドキュメントをご覧ください。
depset について理解を深めます。
ルールの他の例が含まれているサンプルリポジトリを確認する。