このページでは、アスペクトを使用する際の基本とメリットについて説明し、簡単な例と高度な例を示します。
アスペクトは、追加情報とアクションでビルド依存関係グラフを拡張できます。側面が役立つ典型的なシナリオ:
- Bazel を統合する IDE は、アスペクトを使用してプロジェクトに関する情報を収集できます。
- コード生成ツールは、ターゲットに依存しない方法で、入力を利用してアスペクトを実行できます。たとえば、
BUILDファイルでは protobuf ライブラリ定義の階層を指定できます。言語固有のルールでは、アスペクトを使用して、特定の言語の protobuf サポートコードを生成するアクションをアタッチできます。
Aspect の基本
BUILD ファイルでは、プロジェクトのソースコード、つまりプロジェクトに含まれているソースファイル、これらのファイルからビルドされるアーティファクト（ターゲット）、そのファイル間の依存関係などを記述します。Bazel はこの情報を使用して、ビルドを実行するために必要な一連のアーティファクト（コンパイラやリンカーの実行など）を特定して実行します。Bazel は、ターゲット間の依存関係グラフを作成し、このグラフにアクセスして、これらのアクションを収集します。
次の BUILD ファイルについて考えてみます。
java_library(name = 'W', ...)
java_library(name = 'Y', deps = [':W'], ...)
java_library(name = 'Z', deps = [':W'], ...)
java_library(name = 'Q', ...)
java_library(name = 'T', deps = [':Q'], ...)
java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...)
この BUILD ファイルは、次の図のような依存関係グラフを定義します。
図 1. BUILD ファイルの依存関係グラフ。
Bazel は、上記の例のすべてのターゲットに対応するルール（この場合は「java_library」）の実装関数を呼び出して、この依存関係グラフを分析します。ルール実装関数は、.jar ファイルなどのアーティファクトを作成し、それらのアーティファクトの場所や名前などの情報を、プロバイダ内のターゲットの逆依存関係に渡すアクションを生成します。
アスペクトは、アクションを生成してプロバイダを返す実装関数があるという点で、ルールと似ています。ただし、その能力は、依存関係グラフを作成する方法に由来します。アスペクトには、実装と、伝播されるすべての属性のリストがあります。「deps」という名前の属性に合わせて伝播するアスペクト A について考えてみましょう。このアスペクトをターゲット X に適用すると、アスペクト アプリケーション ノード A(X) が生成されます。適用中、アスペクト A は、X が「deps」属性で参照しているすべてのターゲット（A の伝播リスト内のすべての属性）に再帰的に適用されます。
このように、ターゲット A にアスペクト A を適用すると、次の図に示すターゲットの元の依存関係グラフの「シャドウグラフ」が生成されます。
図 2. さまざまな特徴を持つグラフを作成します。
シャドウされるエッジは、伝播セット内の属性に沿ったエッジだけです。この例では、runtime_deps エッジはシャドウされません。その後、元のグラフのノードでルール実装が呼び出された場合と同様に、シャドウ実装のすべてのノードでアスペクト実装関数が呼び出されます。
簡単な例
この例では、ルールのソースファイルと、deps 属性を持つすべての依存関係を再帰的に出力する方法を示します。アスペクトの実装、アスペクトの定義、Bazel コマンドラインからアスペクトを呼び出す方法について説明します。
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
サンプルを分割して、それぞれ個別に見ていきましょう。
アスペクトの定義
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
アスペクトの定義は、ルールの定義と似ており、aspect 関数を使用して定義されます。
ルールと同様に、アスペクトには実装関数があります。この場合は _print_aspect_impl です。
attr_aspects は、アスペクトが伝播するルール属性のリストです。この場合、この適用が適用されるルールの deps 属性に沿って伝播されます。
attr_aspects の一般的なもう一つの引数は ['*'] です。これにより、ルールのすべての属性に側面が伝播されます。
アスペクトの実装
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
アスペクトの実装関数は、ルールの実装関数に似ています。プロバイダを返し、アクションを生成し、次の 2 つの引数を取ります。
実装関数は、ctx.rule.attr を介してターゲット ルールの属性にアクセスできます。これは、適用先のターゲットから（target 引数を介して）提供されるプロバイダを調べることができます。
アスペクトは、プロバイダのリストを返す必要があります。この例では、アスペクトは何も提供しないので、空のリストを返します。
コマンドラインを使用してアスペクトを呼び出す
アスペクトを適用する最も簡単な方法は、コマンドラインから --aspects 引数を使用することです。上記の側面が print.bzl という名前のファイルで定義されていると仮定します。
bazel build //MyExample:example --aspects print.bzl%print_aspect
print_aspect は、ターゲット example と、deps 属性で再帰的にアクセス可能なすべてのターゲット ルールに適用されます。
--aspects フラグは 1 つの引数を取ります。これは、<extension file label>%<aspect top-level name> という形式のアスペクトの仕様です。
高度な例
次の例では、ターゲット内のファイルをカウントし、拡張子でフィルタリングできるターゲット ルールのアスペクトを使用しています。また、プロバイダを使用して値を返す方法、パラメータを使用してアスペクトに引数を渡す方法、ルールからアスペクトを呼び出す方法について説明します。
file_count.bzl ファイル:
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
BUILD.bazel ファイル:
load('//:file_count.bzl', 'file_count_rule')
cc_library(
name = 'lib',
srcs = [
'lib.h',
'lib.cc',
],
)
cc_binary(
name = 'app',
srcs = [
'app.h',
'app.cc',
'main.cc',
],
deps = ['lib'],
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
アスペクトの定義
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
次の例は、deps 属性を使用してそうしたアスペクト比を伝播する方法を示しています。
attrs は、アスペクトの属性のセットを定義します。public アスペクト属性は string 型で、パラメータと呼ばれます。パラメータには values 属性を指定する必要があります。この例には extension というパラメータがあり、このパラメータでは「*」、「h」、「cc」のいずれかの値を使用できます。
アスペクトのパラメータ値は、そのアスペクトをリクエストするルールと同じ名前の文字列属性（file_count_rule の定義を参照）から取得されます。パラメータを定義する構文は、パラメータを定義する構文がないため、コマンドラインでは使用できません。
アスペクトは、label 型または label_list 型のプライベート属性を持つこともできます。プライベート ラベル属性は、さまざまな要素によって生成されたアクションに必要なツールやライブラリへの依存関係を指定するために使用できます。この例で定義されているプライベート属性はありませんが、次のコード スニペットでは、ツールに特定の側面を渡す方法を示しています。
...
attrs = {
'_protoc' : attr.label(
default = Label('//tools:protoc'),
executable = True,
cfg = "exec"
)
}
...
アスペクトの実装
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
ルール実装関数と同様に、アスペクト実装関数は、その依存関係にアクセスできるプロバイダの構造体を返します。
この例では、FileCountInfo は、フィールドが count のプロバイダとして定義されています。fields フィールドを使用してプロバイダのフィールドを明示的に定義することをおすすめします。
アスペクト アプリケーション A（X）のプロバイダ セットは、ターゲット X のルールの実装と、アスペクト A の実装に由来するプロバイダのユニオンです。ルールの実装が伝播するプロバイダは、アスペクトが適用される前に作成されて凍結されるため、アスペクトから変更することはできません。ターゲットとそれに適用されるアスペクトがそれぞれ同じタイプのプロバイダを提供すると、エラーが発生します。ただし、OutputGroupInfo（ルールとアスペクトが異なる出力グループを指定する限り）と InstrumentedFilesInfo（アスペクトから取得）は例外です。つまり、アスペクトの実装は DefaultInfo を返すことはありません。
パラメータとプライベート属性は、ctx の属性で渡されます。この例では、extension パラメータを参照し、カウントするファイルを決定します。
戻りプロバイダでは、（attr_aspects リストから）アスペクトが伝播された属性の値が、それらの側面への適用結果に置き換えられます。たとえば、ターゲット X の依存関係に Y と Z がある場合、A（X）の ctx.rule.attr.deps は [A(Y)、A(Z)] になります。この例の ctx.rule.attr.deps は、アスペクトが適用された元のターゲットの「依存関係」にアスペクトを適用した結果であるターゲット オブジェクトです。
この例では、アスペクトはターゲットの依存関係から FileCountInfo プロバイダにアクセスし、ファイルの合計推移的数を蓄積します。
ルールからアスペクトを呼び出す
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
ルールの実装では、ctx.attr.deps を介して FileCountInfo にアクセスする方法を示します。
ルールの定義は、パラメータ（extension）を定義してデフォルト値（*）を指定する方法を示しています。「cc」、「h」、「*」のいずれかではないデフォルト値があると、アスペクトの定義内のパラメータに課せられる制限によりエラーとなります。
ターゲット ルールでアスペクトを呼び出す
load('//:file_count.bzl', 'file_count_rule')
cc_binary(
name = 'app',
...
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
ここでは、ルールを介して extension パラメータをアスペクトに渡す方法を示します。ルールの実装では extension パラメータにデフォルト値があるため、extension は省略可能なパラメータとみなされます。
file_count ターゲットが構築されると、アスペクト自体が評価され、すべてのターゲットが deps を介して再帰的にアクセスされます。