実行グループを使用すると、1 つのターゲットに複数の実行プラットフォームを設定できます。各実行グループには独自のツールチェーン依存関係があり、それぞれツールチェーンの解決を行います。
背景
実行グループにより、ルール作成者は、それぞれが異なる実行プラットフォームを持つ可能性がある一連のアクションを定義できます。複数の実行プラットフォームでは、アクションの実行が異なります。たとえば、iOS(リモート)Linux ワーカーでコンパイルしてから、ローカル Mac ワーカーでリンク/コード署名を実行できます。
アクションのグループを定義できることで、アクションを指定するための代用としてアクション ニーモニックを使用するのも軽減できます。ネモニクスは一意性を保証するものではなく、1 つのアクションのみを参照できます。これは、特にメモリに負荷をかけずに、特定のメモリにリソースを多く割り当てる場合や、C++ ビルドのリンクなどの負荷の高い処理を行う場合に便利です。
実行グループの定義
ルールの定義時、ルールの作成者は一連の実行グループを宣言できます。ルール実行者は各実行グループに対して、その実行グループの実行プラットフォームの選択に必要なものすべてを指定できます。つまり、exec_compatible_with
による制約と、toolchain
によるツールチェーン タイプを指定できます。
# foo.bzl
my_rule = rule(
_impl,
exec_groups = {
“link”: exec_group(
exec_compatible_with = [ "@platforms//os:linux" ]
toolchains = ["//foo:toolchain_type"],
),
“test”: exec_group(
toolchains = ["//foo_tools:toolchain_type"],
),
},
attrs = {
"_compiler": attr.label(cfg = config.exec("link"))
},
)
上のコード スニペットでは、ツールの依存関係で cfg
属性パラメータと config
モジュールを使用して exec グループの遷移を指定することもできます。このモジュールは、依存関係を構築する exec グループの名前である単一の文字列パラメータを受け取る exec
関数を公開します。
ネイティブ ルールと同様に、Starlark テストルールには test
実行グループがデフォルトで存在します。
実行グループの継承
新しい実行グループは、独自の制約とツールチェーンを定義するだけでなく、copy_from_rule = True
パラメータを渡すことで、ルールのデフォルトの実行グループから継承することを宣言できます。copy_from_rule
を true に設定し、exec_compatible_with
または toolchains
を渡すとエラーが発生します。
デフォルトの実行グループを継承する実行グループは、デフォルトの制約、ツールチェーン、実行プロパティをコピーします。これには、ルール自体で指定されているものだけでなく、ターゲット レベルで設定された制約と実行プロパティも含まれます。つまり、次のようになります。
# foo.bzl
my_rule = rule(
_impl,
exec_groups = {
“copied”: exec_group(
copy_from_rule = True,
# This will inherit exec_compatible_with and toolchains.
# Setting them here directly would be an error, however.
),
},
toolchains = ["//foo_tools:toolchain_type"],
exec_compatible_with = ["@platforms//os:linux"],
)
# BUILD
my_rule(
name = "demo",
exec_compatible_with = [":local_constraint"],
)
構成されたターゲット demo
の copied
実行グループには、次のすべてが含まれます。
- //fool_tools:toolchain_type
- @platforms//os:linux
- :local_constraint
実行グループへのアクセス
ルールの実装では、実行グループの実行プラットフォームで実行するアクションを宣言できます。これを行うには、アクション生成メソッドの exec_group
パラメータ(具体的には ctx.actions.run
と ctx.actions.run_shell
)を使用します。
# foo.bzl
def _impl(ctx):
ctx.actions.run(
inputs = [ctx.attr._some_tool, ctx.srcs[0]]
exec_group = "compile",
# ...
)
ルールの作成者は、ターゲットの解決済みツールチェーンにアクセスする場合と同様に、実行グループの解決済みツールチェーンにもアクセスできます。
# foo.bzl
def _impl(ctx):
foo_info = ctx.exec_groups["link"].toolchains["//foo:toolchain_type"].fooinfo
ctx.actions.run(
inputs = [foo_info, ctx.srcs[0]]
exec_group = "link",
# ...
)
実行グループを使用した実行プロパティの設定
実行グループは、すべてのルールに存在する exec_properties
属性と統合されています。ターゲット ライターは、実行マシンに渡すプロパティの文字列辞書を指定できます。たとえば、ターゲットに対してメモリなどのプロパティを設定し、特定のアクションにより高いメモリ割り当てを付与する場合は、次のように、実行グループ拡張キーを使用して exec_properties
エントリを記述します。
# BUILD
my_rule(
name = 'my_target',
exec_properties = {
'mem': '12g',
'link.mem': '16g'
}
…
)
exec_group = "link"
を含むすべてのアクションは、exec プロパティ ディクショナリを {"mem": "16g"}
と見なします。このように、実行グループレベルの設定がターゲット レベルの設定よりも優先されます。
ネイティブ ルールの実行グループ
ネイティブ ルールで定義されたアクションでは、次の実行グループを使用できます。
test
: ランナー アクションをテストします。cpp_link
: C++ リンク アクション。
exec グループを作成して exec プロパティを設定する
場合によっては、実行グループを使用して特定のアクションに異なる実行プロパティを設定できますが、実際には、ルールとは異なるツールチェーンまたは制約は必要ありません。そのような場合は、copy_from_rule
パラメータを使用して実行グループを作成できます。
# foo.bzl
# Creating an exec group with `copy_from_rule=True` is the same as explicitly
# setting the exec group's toolchains and constraints to the same values as the
# rule's respective parameters.
my_rule = rule(
_impl,
exec_compatible_with = ["@platforms//os:linux"],
toolchains = ["//foo:toolchain_type"],
exec_groups = {
# The following two groups have the same toolchains and constraints:
“foo”: exec_group(copy_from_rule = True),
"bar": exec_group(
exec_compatible_with = ["@platforms//os:linux"],
toolchains = ["//foo:toolchain_type"],
),
},
)
#
実行グループとプラットフォームの実行プロパティ
プラットフォーム ターゲットの任意の実行グループに対して exec_properties
を定義できます(不明な実行グループのプロパティが拒否されるターゲットに直接設定される exec_properties
とは異なります)。ターゲットは、デフォルトの実行グループやその他の関連する実行グループに影響する実行プラットフォームの exec_properties
を継承します。
たとえば、C++ テストを実行するにはいくつかのリソースが必要ですが、そのコンパイルとリンクは必要ないとします。これは、次のようにモデル化できます。
constraint_setting(name = "resource")
constraint_value(name = "has_resource", constraint_setting = ":resource")
platform(
name = "platform_with_resource",
constraint_values = [":has_resource"],
exec_properties = {
"test.resource": "...",
},
)
cc_test(
name = "my_test",
srcs = ["my_test.cc"],
exec_compatible_with = [":has_resource"],
)
ターゲットに直接定義された exec_properties
は、実行プラットフォームから継承されたものよりも優先されます。