Starlark は Python に似た構成言語です。もともと Bazel で使用するために開発され、他のツールで採用されています。Bazel の BUILD
ファイルと .bzl
ファイルは、「Build Language」と呼ばれる Starlark 言語で記述されていますが、単に「Starlark」と呼ばれることもあります。特に、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 fileEvaluation」が出力されます。
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: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 fileEvaluation」と「BUILD file」のどちらも出力されません。Bazel は、実際に実行された場合にのみ print
ステートメントを出力します。
ファイルの作成
ルールをより有用なものにするには、ファイルを生成するようにルールを更新してください。まず、ファイルを宣言して名前を付けます。この例では、ターゲットと同じ名前のファイルを作成します。
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
のドキュメントをご覧ください。booleanや整数のリストなど、他のタイプの属性を使用することもできます。
依存関係
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 について十分に理解してください。
- ルールの他の例が含まれているサンプル リポジトリを確認する。