このページでは、 さまざまな側面があり、シンプルかつ高度な 説明します。
アスペクトを使用すると、ビルドの依存関係グラフを追加情報で拡張できる あります。アスペクトが役立つ一般的なシナリオは次のとおりです。
- Bazel を統合する IDE は、アスペクトを使用して、 できます。
- コード生成ツールは、アスペクトを活用して、ターゲット非依存の方法で入力を実行できます。たとえば、
BUILD
ファイルで階層を指定できます。 protobuf ライブラリ 言語固有のルールでは、アスペクトを使用して、 特定の言語の protobuf サポートコードを生成するアクション。
アスペクトの基本
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 をターゲット X に適用する単一のアクションにより、次の図に示すターゲットの元の依存関係グラフの「シャドウグラフ」が生成されます。
図 2. アスペクトを使用してグラフを作成する。
シャドウが適用されるエッジは、伝播セット内の属性に沿ったエッジのみです。そのため、この例では runtime_deps
エッジにはシャドウが適用されません。次に、元のグラフのノードでルール実装が呼び出されるのと同様に、シャドウグラフのすべてのノードでアスペクト実装関数が呼び出されます。
簡単な例
この例では、サンプル ファイルのソースファイルを再帰的に出力する方法を示します。
deps
属性を持つすべての依存関係ルールと、その依存関係のすべてを検出します。内容
アスペクトの実装、アスペクトの定義、アスペクトの呼び出し方法
実行することもできます。
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
のもう 1 つの一般的な引数は ['*']
です。これは、アスペクトをルールのすべての属性に伝播します。
Aspect の実装
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
は、アスペクトの属性セットを定義します。公開アスペクトの属性
パラメータを定義します。型は bool
、int
、string
のいずれかにする必要があります。
ルールが伝播されるアスペクトの場合、int
パラメータと string
パラメータには以下が必要です。
values
が指定されていることを確認します。この例では、extension
というパラメータがあり、値として「*
」、「h
」、「cc
」のいずれかを指定できます。
ルールによって伝播されるアスペクトについては、パラメータ値はリクエスト元ルールから
同じ名前とタイプを持つルールの属性を使用します。
(file_count_rule
の定義を参照)。
コマンドライン アスペクトの場合、パラメータ値は
--aspects_parameters
設定されます。int
パラメータと string
パラメータの values
制限は省略できます。
アスペクトには、label
型または label_list
型の非公開属性を設定することもできます。限定公開ラベル属性を使用すると、リソースへの依存関係を
アスペクトによって生成されたアクションに必要なツールやライブラリ。
この例で定義されている非公開属性ですが、次のコード スニペットは
は、ツールをアスペクトに渡す方法を示しています。
...
attrs = {
'_protoc' : attr.label(
default = Label('//tools:protoc'),
executable = True,
cfg = "exec"
)
}
...
Aspect の実装
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
は 1 つのフィールド 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
は、アスペクトが適用された元のターゲットの「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
を介して再帰的にアクセスできるすべてのターゲットが含まれます。