このページでは、Starlark 構成のメリットと基本的な使用方法について説明します。Starlark 構成は、プロジェクトのビルド方法をカスタマイズするための Bazel の API です。ビルド設定の定義方法と例について説明します。
これにより、次のことが可能になります。
- プロジェクトのカスタムフラグを定義し、
--defineの必要性をなくします。 - トランジションを記述して、親とは異なる構成（
--compilation_mode=optや--cpu=armなど）で依存関係を構成する - ルールに優れたデフォルトを組み込む（指定された SDK で
//my:android_appを自動的にビルドするなど）
これらはすべて .bzl ファイルから完全に実行されます（Bazel リリースは不要）。例については、bazelbuild/examples リポジトリをご覧ください。
ユーザー定義のビルド設定
ビルド設定は、単一の構成情報です。構成は Key-Value マップとして考えてください。--cpu=ppc と --copt="-DFoo" を設定すると、{cpu: ppc, copt: "-DFoo"} のような構成が生成されます。各エントリはビルド設定です。
cpu や copt などの従来のフラグはネイティブ設定です。キーが定義され、値がネイティブの bazel java コード内で設定されます。Bazel ユーザーは、コマンドラインとネイティブに維持されている他の API を介してのみ、これらを読み書きできます。ネイティブ フラグと、それらを公開する API を変更するには、bazel リリースが必要です。ユーザー定義のビルド設定は .bzl ファイルで定義されます（そのため、変更を登録するために bazel リリースは必要ありません）。コマンドラインで設定することもできます（flags として指定されている場合。詳しくは下記をご覧ください）。また、ユーザー定義のトランジションで設定することもできます。
ビルド設定の定義
build_setting rule() パラメータ
ビルド設定は他のルールと同様のルールであり、Starlark の rule() 関数の build_setting
属性を使用して区別されます。
# example/buildsettings/build_settings.bzl
string_flag = rule(
implementation = _impl,
build_setting = config.string(flag = True)
)
build_setting 属性は、ビルド設定のタイプを指定する関数を受け取ります。型は、bool や string などの基本的な Starlark 型のセットに制限されます。詳しくは、config モジュールのドキュメントをご覧ください。より複雑な型指定は、ルールの実装関数で行うことができます。詳しくは以下をご覧ください。
config モジュールの関数は、オプションのブール値パラメータ flag を取ります。このパラメータはデフォルトで false に設定されています。flag が true に設定されている場合、ビルド設定は、ユーザーがコマンドラインで設定することも、ルール作成者がデフォルト値とトランジションを介して内部的に設定することもできます。すべての設定をユーザーが設定できるようにすべきではありません。たとえば、ルール作成者がテストルールの内部でオンにしたいデバッグモードがある場合、ユーザーが他のテスト以外のルール内でその機能を無差別にオンにできるようにしたくありません。
ctx.build_setting_value の使用
すべてのルールと同様に、ビルド設定ルールには実装関数があります。ビルド設定の基本的な Starlark 型の値には、ctx.build_setting_value メソッドでアクセスできます。このメソッドは、ビルド設定ルールの ctx オブジェクトでのみ使用できます。これらの実装メソッドは、ビルド設定の値を直接転送することも、型チェックやより複雑な構造体の作成などの追加作業を行うこともできます。enum 型のビルド設定を実装する方法は次のとおりです。
# example/buildsettings/build_settings.bzl
TemperatureProvider = provider(fields = ['type'])
temperatures = ["HOT", "LUKEWARM", "ICED"]
def _impl(ctx):
raw_temperature = ctx.build_setting_value
if raw_temperature not in temperatures:
fail(str(ctx.label) + " build setting allowed to take values {"
+ ", ".join(temperatures) + "} but was set to unallowed value "
+ raw_temperature)
return TemperatureProvider(type = raw_temperature)
temperature = rule(
implementation = _impl,
build_setting = config.string(flag = True)
)
マルチセット文字列フラグを定義する
文字列設定には、コマンドラインまたは bazelrc でフラグを複数回設定できる allow_multiple パラメータが追加されています。デフォルト値は、文字列型の属性で設定されます。
# example/buildsettings/build_settings.bzl
allow_multiple_flag = rule(
implementation = _impl,
build_setting = config.string(flag = True, allow_multiple = True)
)
# example/BUILD
load("//example/buildsettings:build_settings.bzl", "allow_multiple_flag")
allow_multiple_flag(
name = "roasts",
build_setting_default = "medium"
)
フラグの各設定は、単一の値として扱われます。
$ bazel build //my/target --//example:roasts=blonde \
--//example:roasts=medium,dark
上記は {"//example:roasts": ["blonde", "medium,dark"]} に解析され、ctx.build_setting_value はリスト ["blonde", "medium,dark"] を返します。
ビルド設定のインスタンス化
build_setting パラメータで定義されたルールには、暗黙的な必須の build_setting_default 属性があります。この属性は、build_setting パラメータで宣言されたものと同じ型になります。
# example/buildsettings/build_settings.bzl
FlavorProvider = provider(fields = ['type'])
def _impl(ctx):
return FlavorProvider(type = ctx.build_setting_value)
flavor = rule(
implementation = _impl,
build_setting = config.string(flag = True)
)
# example/BUILD
load("//example/buildsettings:build_settings.bzl", "flavor")
flavor(
name = "favorite_flavor",
build_setting_default = "APPLE"
)
事前定義された設定
Skylib ライブラリには、カスタム Starlark を記述しなくてもインスタンス化できる事前定義された設定のセットが含まれています。
たとえば、限られた文字列値のセットを受け入れる設定を定義するには:
# example/BUILD
load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
string_flag(
name = "myflag",
values = ["a", "b", "c"],
build_setting_default = "a",
)
完全なリストについては、一般的なビルド設定ルールをご覧ください。
ビルド設定を使用する
ビルド設定によって異なる
ターゲットが構成情報を読み取る場合は、通常の属性依存関係を介してビルド設定に直接依存できます。
# example/rules.bzl
load("//example/buildsettings:build_settings.bzl", "FlavorProvider")
def _rule_impl(ctx):
if ctx.attr.flavor[FlavorProvider].type == "ORANGE":
...
drink_rule = rule(
implementation = _rule_impl,
attrs = {
"flavor": attr.label()
}
)
# example/BUILD
load("//example:rules.bzl", "drink_rule")
load("//example/buildsettings:build_settings.bzl", "flavor")
flavor(
name = "favorite_flavor",
build_setting_default = "APPLE"
)
drink_rule(
name = "my_drink",
flavor = ":favorite_flavor",
)
言語では、その言語のすべてのルールが依存するビルド設定の正規セットを作成することが望ましい場合があります。fragments のネイティブなコンセプトは、Starlark 構成の世界ではハードコードされたオブジェクトとして存在しなくなりましたが、このコンセプトを変換する方法の 1 つは、共通の暗黙的属性のセットを使用することです。次に例を示します。
# kotlin/rules.bzl
_KOTLIN_CONFIG = {
"_compiler": attr.label(default = "//kotlin/config:compiler-flag"),
"_mode": attr.label(default = "//kotlin/config:mode-flag"),
...
}
...
kotlin_library = rule(
implementation = _rule_impl,
attrs = dicts.add({
"library-attr": attr.string()
}, _KOTLIN_CONFIG)
)
kotlin_binary = rule(
implementation = _binary_impl,
attrs = dicts.add({
"binary-attr": attr.label()
}, _KOTLIN_CONFIG)
コマンドラインでビルド設定を使用する
ほとんどのネイティブ フラグと同様に、コマンドラインを使用して、フラグとしてマークされているビルド設定を設定できます。ビルド設定の名前は、name=value 構文を使用した完全なターゲット パスです。
$ bazel build //my/target --//example:string_flag=some-value # allowed
$ bazel build //my/target --//example:string_flag some-value # not allowed
特別なブール値構文がサポートされています。
$ bazel build //my/target --//example:boolean_flag
$ bazel build //my/target --no//example:boolean_flag
ビルド設定エイリアスの使用
ビルド設定のターゲット パスにエイリアスを設定すると、コマンドラインで読みやすくなります。エイリアスはネイティブ フラグと同様に機能し、二重ダッシュ オプション構文も使用します。
.bazelrc に --flag_alias=ALIAS_NAME=TARGET_PATH を追加して、エイリアスを設定します。たとえば、エイリアスを coffee に設定するには:
# .bazelrc
build --flag_alias=coffee=//experimental/user/starlark_configurations/basic_build_setting:coffee-temp
ベスト プラクティス: エイリアスを複数回設定すると、最も新しいものが優先されます。意図しない解析結果を避けるため、一意のエイリアス名を使用します。
エイリアスを使用するには、ビルド設定のターゲット パスの代わりにエイリアスを入力します。ユーザーの .bazelrc に coffee が設定されている上記の例では、
$ bazel build //my/target --coffee=ICED
これは、以下を置き換えるものです。
$ bazel build //my/target --//experimental/user/starlark_configurations/basic_build_setting:coffee-temp=ICED
ベスト プラクティス: コマンドラインでエイリアスを設定することもできますが、.bazelrc に残しておくと、コマンドラインの煩雑さを軽減できます。
ラベル型のビルド設定
他のビルド設定とは異なり、ラベル型の設定は build_setting ルール パラメータを使用して定義できません。代わりに、bazel には label_flag と label_setting の 2 つの組み込みルールがあります。これらのルールは、ビルド設定が設定されている実際のターゲットのプロバイダを転送します。label_flag と label_setting はトランジションによって読み取り/書き込みが可能で、label_flag は他の build_setting ルールと同様にユーザーが設定できます。唯一の違いは、カスタム定義できないことです。
ラベル型の設定は、最終的に遅延バインディングのデフォルトの機能を置き換えます。遅延バインドのデフォルト属性は、最終値が構成の影響を受ける可能性がある Label 型の属性です。Starlark では、これは configuration_field API に代わるものです。
# example/rules.bzl
MyProvider = provider(fields = ["my_field"])
def _dep_impl(ctx):
return MyProvider(my_field = "yeehaw")
dep_rule = rule(
implementation = _dep_impl
)
def _parent_impl(ctx):
if ctx.attr.my_field_provider[MyProvider].my_field == "cowabunga":
...
parent_rule = rule(
implementation = _parent_impl,
attrs = { "my_field_provider": attr.label() }
)
# example/BUILD
load("//example:rules.bzl", "dep_rule", "parent_rule")
dep_rule(name = "dep")
parent_rule(name = "parent", my_field_provider = ":my_field_provider")
label_flag(
name = "my_field_provider",
build_setting_default = ":dep"
)
ビルド設定と select()
ユーザーは select() を使用して、ビルド設定で属性を構成できます。ビルド設定ターゲットは、config_setting の flag_values 属性に渡すことができます。構成と照合する値は String として渡され、照合用のビルド設定の型に解析されます。
config_setting(
name = "my_config",
flag_values = {
"//example:favorite_flavor": "MANGO"
}
)
ユーザー定義のトランジション
構成の移行は、ビルドグラフ内で、構成されたあるターゲットから別のターゲットへの変換をマッピングします。
定義する
移行は、ルール間の構成変更を定義します。たとえば、「親とは異なる CPU 用に依存関係をコンパイルする」というリクエストは、トランジションによって処理されます。
正式には、遷移は入力構成から 1 つ以上の出力構成への関数です。ほとんどの移行は「--cpu=ppc で入力構成をオーバーライドする」などの 1:1 です。1:2 以上の移行も存在しますが、特別な制限が伴います。
Starlark では、ルールと同様に、定義 transition()
関数と実装関数を使用して遷移を定義します。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {"//example:favorite_flavor" : "MINT"}
hot_chocolate_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//example:favorite_flavor"]
)
transition() 関数は、実装関数、読み取るビルド設定のセット（inputs）、書き込むビルド設定のセット（outputs）を受け取ります。実装関数には settings と attr の 2 つのパラメータがあります。settings は、inputs パラメータで宣言されたすべての設定の String:Object のディクショナリです。transition()
attr は、移行が関連付けられているルールの属性と値の辞書です。発信エッジ遷移として接続されている場合、これらの属性の値はすべて select() 解決後に構成されます。入力エッジ遷移として接続されている場合、attr にはセレクタを使用して値を解決する属性は含まれません。--foo の入力エッジ遷移が属性 bar を読み取り、--foo で選択して属性 bar を設定する場合、入力エッジ遷移が遷移で bar の間違った値を読み取る可能性があります。
実装関数は、適用する新しいビルド設定値のディクショナリ（複数の出力構成を持つトランジションの場合はディクショナリのリスト）を返す必要があります。返される辞書キーセットには、遷移関数の outputs パラメータに渡されたビルド設定のセットが正確に含まれている必要があります。これは、移行中にビルド設定が実際に変更されない場合でも当てはまります。元の値は、返されたディクショナリで明示的に渡す必要があります。
1:2 以上の遷移を定義する
出力エッジ遷移は、単一の入力構成を 2 つ以上の出力構成にマッピングできます。これは、マルチアーキテクチャ コードをバンドルするルールを定義する場合に便利です。
1:2+ の遷移は、遷移実装関数で辞書のリストを返すことで定義されます。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return [
{"//example:favorite_flavor" : "LATTE"},
{"//example:favorite_flavor" : "MOCHA"},
]
coffee_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//example:favorite_flavor"]
)
ルール実装関数が個々の依存関係を読み取るために使用できるカスタムキーを設定することもできます。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {
"Apple deps": {"//command_line_option:cpu": "ppc"},
"Linux deps": {"//command_line_option:cpu": "x86"},
}
multi_arch_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//command_line_option:cpu"]
)
遷移を適用する
遷移は、入力エッジと出力エッジの 2 か所に付加できます。つまり、ルールは独自の構成（入力エッジ遷移）を遷移させ、依存関係の構成（出力エッジ遷移）を遷移させることができます。
注: 現在、Starlark 変換をネイティブ ルールに関連付ける方法はありません。この操作が必要な場合は、bazel-discuss@googlegroups.com にお問い合わせください。回避策の検討についてサポートいたします。
着信エッジの遷移
入力エッジの遷移は、rule() の cfg パラメータに transition オブジェクト（transition() で作成）を付加することで有効になります。
# example/rules.bzl
load("example/transitions:transitions.bzl", "hot_chocolate_transition")
drink_rule = rule(
implementation = _impl,
cfg = hot_chocolate_transition,
...
着信エッジ トランジションは 1:1 トランジションである必要があります。
発信エッジの遷移
発信エッジの遷移は、transition オブジェクト（transition() で作成）を属性の cfg パラメータに付加することで有効になります。
# example/rules.bzl
load("example/transitions:transitions.bzl", "coffee_transition")
drink_rule = rule(
implementation = _impl,
attrs = { "dep": attr.label(cfg = coffee_transition)}
...
発信エッジ遷移は 1:1 または 1:2+ にできます。
これらのキーの読み取り方法については、トランジションを使用した属性へのアクセスをご覧ください。
ネイティブ オプションの切り替え
Starlark 変換では、オプション名の特別な接頭辞を使用して、ネイティブ ビルド構成オプションの読み取りと書き込みを宣言することもできます。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {"//command_line_option:cpu": "k8"}
cpu_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//command_line_option:cpu"]
サポートされていないネイティブ オプション
Bazel は、"//command_line_option:define" を使用した --define での移行をサポートしていません。代わりに、カスタムのビルド設定を使用してください。一般に、ビルド設定を優先して --define の新しい使用は推奨されません。
Bazel は --config での移行をサポートしていません。これは、--config が他のフラグに展開される「展開」フラグであるためです。
重要な点として、--config には --spawn_strategy など、ビルド構成に影響しないフラグが含まれる場合があります。Bazel は、設計上、このようなフラグを個々のターゲットにバインドできません。つまり、遷移でこれらを適用する一貫した方法はありません。
回避策として、移行で構成の一部であるフラグを明示的に列挙できます。これには、--config の展開を 2 か所で維持する必要があり、これは UI の欠陥として知られています。
複数のビルド設定を許可する状態遷移
複数の値が許可されているビルド設定を設定する場合は、設定の値をリストで設定する必要があります。
# example/buildsettings/build_settings.bzl
string_flag = rule(
implementation = _impl,
build_setting = config.string(flag = True, allow_multiple = True)
)
# example/BUILD
load("//example/buildsettings:build_settings.bzl", "string_flag")
string_flag(name = "roasts", build_setting_default = "medium")
# example/transitions/rules.bzl
def _transition_impl(settings, attr):
# Using a value of just "dark" here will throw an error
return {"//example:roasts" : ["dark"]},
coffee_transition = transition(
implementation = _transition_impl,
inputs = [],
outputs = ["//example:roasts"]
)
No-op 遷移
移行が {}、[]、または None を返す場合、これはすべての設定を元の値のままにしておくための省略形です。これは、各出力を明示的にそれ自体に設定するよりも便利です。
# example/transitions/transitions.bzl
def _impl(settings, attr):
_ignore = (attr)
if settings["//example:already_chosen"] is True:
return {}
return {
"//example:favorite_flavor": "dark chocolate",
"//example:include_marshmallows": "yes",
"//example:desired_temperature": "38C",
}
hot_chocolate_transition = transition(
implementation = _impl,
inputs = ["//example:already_chosen"],
outputs = [
"//example:favorite_flavor",
"//example:include_marshmallows",
"//example:desired_temperature",
]
)
トランジションで属性にアクセスする
移行をアウトゴーイング エッジに接続する場合（移行が 1:1 か 1:2+ かに関係なく）、ctx.attr がまだリストでない場合は、リストに強制的に変換されます。このリスト内の要素の順序は指定されていません。
# example/transitions/rules.bzl
def _transition_impl(settings, attr):
return {"//example:favorite_flavor" : "LATTE"},
coffee_transition = transition(
implementation = _transition_impl,
inputs = [],
outputs = ["//example:favorite_flavor"]
)
def _rule_impl(ctx):
# Note: List access even though "dep" is not declared as list
transitioned_dep = ctx.attr.dep[0]
# Note: Access doesn't change, other_deps was already a list
for other_dep in ctx.attr.other_deps:
# ...
coffee_rule = rule(
implementation = _rule_impl,
attrs = {
"dep": attr.label(cfg = coffee_transition)
"other_deps": attr.label_list(cfg = coffee_transition)
})
トランジションが 1:2+ でカスタムキーを設定する場合、ctx.split_attr を使用して各キーの個々の依存関係を読み取ることができます。
# example/transitions/rules.bzl
def _impl(settings, attr):
_ignore = (settings, attr)
return {
"Apple deps": {"//command_line_option:cpu": "ppc"},
"Linux deps": {"//command_line_option:cpu": "x86"},
}
multi_arch_transition = transition(
implementation = _impl,
inputs = [],
outputs = ["//command_line_option:cpu"]
)
def _rule_impl(ctx):
apple_dep = ctx.split_attr.dep["Apple deps"]
linux_dep = ctx.split_attr.dep["Linux deps"]
# ctx.attr has a list of all deps for all keys. Order is not guaranteed.
all_deps = ctx.attr.dep
multi_arch_rule = rule(
implementation = _rule_impl,
attrs = {
"dep": attr.label(cfg = multi_arch_transition)
})
完全な例をご覧ください。
プラットフォームとツールチェーンとの統合
現在、--cpu や --crosstool_top などの多くのネイティブ フラグは、ツールチェーンの解決に関連しています。今後、これらのタイプのフラグの明示的な移行は、ターゲット プラットフォームの移行に置き換えられる可能性があります。
メモリとパフォーマンスに関する考慮事項
ビルドにトランジション（新しい構成）を追加すると、ビルドグラフが大きくなり、ビルドグラフの理解が難しくなり、ビルドが遅くなるというコストが発生します。ビルドルールでトランジションを使用することを検討する際は、これらの費用を考慮する必要があります。以下は、移行によってビルドグラフが指数関数的に増加する例です。
動作不良のビルド: ケーススタディ
図 1. 最上位のターゲットとその依存関係を示すスケーラビリティ グラフ。
このグラフは、2 つのターゲット（//pkg:1_0 と //pkg:1_1）に依存する最上位レベルのターゲット //pkg:app を示しています。これらのターゲットは両方とも、//pkg:2_0 と //pkg:2_1 の 2 つのターゲットに依存しています。これらのターゲットは両方とも、//pkg:3_0 と //pkg:3_1 の 2 つのターゲットに依存しています。この処理は、単一のターゲット //pkg:dep に依存する //pkg:n_0 と //pkg:n_1 まで続きます。
//pkg:app のビルドには \(2n+2\) ターゲットが必要です。
//pkg:app//pkg:dep- \([1..n]\)の \(i\) の
//pkg:i_0と//pkg:i_1
実装したフラグ --//foo:owner=<STRING> と //pkg:i_b が適用されるとします。
depConfig = myConfig + depConfig.owner="$(myConfig.owner)$(b)"
つまり、//pkg:i_b は、すべての依存関係の --owner の古い値に b を追加します。
これにより、次の構成済みターゲットが生成されます。
//pkg:app //foo:owner=""
//pkg:1_0 //foo:owner=""
//pkg:1_1 //foo:owner=""
//pkg:2_0 (via //pkg:1_0) //foo:owner="0"
//pkg:2_0 (via //pkg:1_1) //foo:owner="1"
//pkg:2_1 (via //pkg:1_0) //foo:owner="0"
//pkg:2_1 (via //pkg:1_1) //foo:owner="1"
//pkg:3_0 (via //pkg:1_0 → //pkg:2_0) //foo:owner="00"
//pkg:3_0 (via //pkg:1_0 → //pkg:2_1) //foo:owner="01"
//pkg:3_0 (via //pkg:1_1 → //pkg:2_0) //foo:owner="10"
//pkg:3_0 (via //pkg:1_1 → //pkg:2_1) //foo:owner="11"
...
//pkg:dep は、 \(2^n\) 構成済みのターゲット（config.owner=）を生成します。 \(\{0,1\}\)のすべての \(b_i\) に対して「\(b_0b_1...b_n\)」を生成します。
これにより、ビルドグラフがターゲット グラフよりも指数関数的に大きくなり、メモリとパフォーマンスに影響します。
TODO: これらの問題の測定と軽減のための戦略を追加します。
参考資料
ビルド構成の変更について詳しくは、以下をご覧ください。
- Starlark ビルド構成
- Bazel の構成可能性のロードマップ
- エンドツーエンドの例の完全なセット