.bzl ファイル

_ で始まる暗黙的な属性は、デフォルト値を持ち、label または label_list 型にする必要があります。

明示的な属性は、string 型にする必要があります。また、values 制限を使用する必要があります。明示的な属性では、制限に従って、同じ名前、タイプ、有効な値の属性を持つルールでのみアスペクトが使用されるように制限されます。

ネストされていないプロバイダのリストは、プロバイダのリストが 1 つ含まれるリストに自動的に変換されます。つまり、[FooInfo, BarInfo] は自動的に [[FooInfo, BarInfo]] に変換されます。

ルール（some_rule など）のターゲットをアスペクトに表示するには、some_rule が、必須のベンダーリストの少なくとも 1 つからすべてのベンダーを宣伝する必要があります。たとえば、アスペクトの required_providers が [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] の場合、このアスペクトは、some_rule が FooInfo、または BarInfo、または BazInfo と QuxInfo の両方を提供する場合にのみ、some_rule ターゲットを参照できます。

ネストされていないプロバイダのリストは、プロバイダのリストが 1 つ含まれるリストに自動的に変換されます。つまり、[FooInfo, BarInfo] は自動的に [[FooInfo, BarInfo]] に変換されます。

別のアスペクト（other_aspect など）をこのアスペクトに表示するには、other_aspect が少なくとも 1 つのリストのすべてのプロバイダを提供する必要があります。[[FooInfo], [BarInfo], [BazInfo, QuxInfo]] の例では、このアスペクトは、other_aspect が FooInfo、または BarInfo、または BazInfo と QuxInfo の両方を提供する場合にのみ、other_aspect を参照できます。

実装関数で、ここで説明するプロバイダのいずれかの型が戻り値から省略されている場合はエラーです。ただし、実装関数はここに記載されていない追加のプロバイダを返す場合があります。

リストの各要素は、provider() から返される *Info オブジェクトです。ただし、以前のプロバイダは文字列名で表されます。ルールのターゲットが、必要なプロバイダを宣言するターゲットの依存関係として使用される場合、そのプロバイダをここで指定する必要はありません。実装関数が返すだけで十分です。ただし、必須ではないものの、指定することをおすすめします。ただし、アスペクトの required_providers フィールドでは、プロバイダをここで指定する必要があります。

たとえば、アスペクトが属性「deps」を介して伝播し、ターゲット「alpha」に適用されているとします。alpha に「deps = [':beta_output']」があるとします。ここで、beta_output はターゲット beta の宣言された出力です。beta にターゲット「charlie」が「deps」の 1 つとしてあるとします。アスペクトの「apply_to_generating_rules=True」の場合、アスペクトは「alpha」、「beta」、「charlie」を介して伝播します。False の場合、アスペクトは「alpha」にのみ伝播します。

デフォルトは false です。

• フィールドのリスト:
  

  provider(fields = ['a', 'b'])

• 辞書フィールド名 -> ドキュメント:
  

  provider(
         fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })

正確な説明については後述します。直感的な説明とユースケースについては、ルール（プロバイダのカスタム初期化）をご覧ください。

P を、provider() を呼び出して作成したプロバイダ シンボルにします。概念的には、P のインスタンスはデフォルトのコンストラクタ関数 c(*args, **kwargs) を呼び出して生成されます。この関数は次の処理を行います。

• args が空でない場合、エラーが発生します。
• provider() の呼び出し時に fields パラメータが指定され、kwargs に fields にリストされていないキーが含まれている場合、エラーが発生します。
• それ以外の場合、c は、kwargs の k: v エントリごとに、値が v の k という名前のフィールドを持つ新しいインスタンスを返します。

MyInfo = provider()
m = MyInfo(foo = 1)

ただし、init が指定されている場合、P(*args, **kwargs) 呼び出しは代わりに次の手順を実行します。

1. コールバックは init(*args, **kwargs) として呼び出されます。つまり、P に渡されたものと同じ位置引数とキーワード引数で呼び出されます。
2. init の戻り値は、キーがフィールド名の文字列である辞書 d です。有効になっていない場合は、エラーが発生します。
3. c(**d) のように、d のエントリをキーワード引数としてデフォルト コンストラクタを呼び出す場合と同様に、P の新しいインスタンスが生成されます。

注: 上記の手順は、*args または **kwargs が init のシグネチャと一致しない場合、init の本文の評価が失敗した場合（fail() の呼び出しによって意図的に失敗した場合も含む）、または init の戻り値が想定されるスキーマの辞書でない場合、エラーが発生することを意味します。

このように、init コールバックは、位置引数と任意のロジックを事前処理と検証に使用できるようにすることで、通常のプロバイダの作成を一般化します。許可された fields のリストを回避することはできません。

init を指定すると、provider() の戻り値はタプル (P, r) になります。ここで、r は未加工のコンストラクタです。実際、r の動作は、前述のデフォルト コンストラクタ関数 c の動作とまったく同じです。通常、r は、名前の先頭にアンダースコアが付いた変数にバインドされるため、現在の .bzl ファイルのみが直接アクセスできます。

MyInfo, _new_myinfo = provider(init = ...)

事前宣言された出力を定義するためのスキーマ。output 属性や output_list 属性とは異なり、ユーザーはこれらのファイルのラベルを指定しません。事前宣言された出力の詳細については、ルールのページをご覧ください。

この引数の値は、ディクショナリまたはディクショナリを生成するコールバック関数です。コールバックは、計算された依存関係属性と同様に機能します。関数のパラメータ名はルールの属性と照合されます。たとえば、定義 def _my_func(srcs, deps): ... で outputs = _my_func を渡すと、関数は属性 srcs と deps にアクセスできます。辞書は直接指定するか、関数を介して指定しますが、どちらの場合も次のように解釈されます。

ディクショナリ内の各エントリは、事前に宣言された出力を作成します。キーは識別子で、値は出力ラベルを決定する文字列テンプレートです。ルールの実装関数では、識別子は ctx.outputs の出力の File にアクセスするために使用されるフィールド名になります。出力のラベルはルールと同じパッケージで、パッケージの後の部分は、"%{ATTR}" 形式の各プレースホルダを属性 ATTR の値から形成された文字列に置き換えることで生成されます。

• 文字列型の属性はそのまま置換されます。
• ラベル型の属性は、パッケージの後の部分（ファイル拡張子を除く）としてラベルの一部になります。たとえば、ラベル "//pkg:a/b.c" は "a/b" になります。
• 出力型の属性は、ファイル拡張子（上記の例では "a/b.c"）を含め、パッケージの後のラベルの一部になります。
• プレースホルダで使用されるリスト型の属性（attr.label_list など）には、要素が 1 つだけ必要です。リスト以外のバージョン（attr.label）と同じコンバージョンです。
• 他の属性タイプはプレースホルダに表示されない場合があります。
• 属性以外の特別なプレースホルダ %{dirname} と %{basename} は、パッケージを除き、ルールのラベルの該当する部分に展開されます。たとえば、"//pkg:a/b.c" では、dirname は a、basename は b.c です。

実際には、最も一般的な置換プレースホルダは "%{name}" です。たとえば、foo という名前のターゲットの場合、出力ディクショナリ {"bin": "%{name}.exe"} は、実装関数で ctx.outputs.bin としてアクセスできる foo.exe という名前の出力を事前宣言します。

実装関数で、ここで説明するプロバイダのいずれかの型が戻り値から省略されている場合はエラーです。ただし、実装関数はここに記載されていない追加のプロバイダを返す場合があります。

リストの各要素は、provider() から返される *Info オブジェクトです。ただし、以前のプロバイダは文字列名で表されます。ルールのターゲットが、必要なプロバイダを宣言するターゲットの依存関係として使用される場合、そのプロバイダをここで指定する必要はありません。実装関数で返すだけで十分です。必須ではありませんが、指定することをおすすめします。ただし、アスペクトの required_providers フィールドでは、プロバイダをここで指定する必要があります。

注: 分析テストルールは、主にコア Starlark ライブラリで提供されるインフラストラクチャを使用して定義されます。ガイダンスについては、テストをご覧ください。

ルールが分析テストルールとして定義されている場合、その属性で analysis_test_transition を使用して定義された構成遷移を使用できますが、一部の制限が適用されます。

• このルールのターゲットには、持つことができる伝播依存関係の数に制限があります。
• このルールは、（test=True が設定されている場合と同様に）テストルールと見なされます。これは test の値に優先されます。
• ルール実装関数でアクションが登録されない場合があります。代わりに、AnalysisTestResultInfo を提供して合格/不合格の結果を登録する必要があります。

この関数は、ルールのインスタンスごとに読み込み時に呼び出されます。name と、ルールで定義された公開属性の値（汎用属性（tags など）ではない）で呼び出されます。

属性名から目的の値へのディクショナリを返す必要があります。返されない属性は影響を受けません。None を値として返すと、属性定義で指定されたデフォルト値が使用されます。

イニシャライザは、属性定義で指定されたデフォルト値の前に評価されます。したがって、イニシャライザのシグネチャのパラメータにデフォルト値が含まれている場合、属性定義のデフォルト値が上書きされます（None を返す場合を除く）。

同様に、イニシャライザのシグネチャのパラメータにデフォルトがない場合、そのパラメータは必須になります。このような場合は、属性定義のデフォルト設定または必須設定を省略することをおすすめします。

処理されない属性には **kwargs を使用することをおすすめします。

拡張ルールの場合、すべての初期化子は子から祖先に向かって順番に呼び出されます。各イニシャライザには、認識している公開属性のみが渡されます。

サブルールは、ラベル型（ラベルまたはラベルリスト）の非公開属性のみを持つことができます。これらのラベルに対応する解決済み値は、Bazel によってサブルールの実装関数に名前付き引数として自動的に渡されます（そのため、実装関数は属性名に一致する名前付きパラメータを受け入れる必要が生じます）。値の型は次のとおりです。

• FilesToRunProvider: executable=True を含むラベル属性
• File: allow_single_file=True を含むラベル属性
• Target（その他のラベル属性の場合）
• [Target]: すべてのラベルリスト属性

パッケージの仕様は package_group と同じ形式ですが、負のパッケージの仕様は許可されません。つまり、仕様の形式は次のようになります。

• "//foo": パッケージ //foo
• "//foo/...": パッケージ //foo とそのすべてのサブパッケージ。
• "public" または "private": すべてのパッケージまたはパッケージなし

「@」構文は使用できません。すべての仕様は、現在のモジュールのリポジトリを基準に解釈されます。

value が文字列のリストの場合、このモジュールに可視性が付与されたパッケージのセットは、各仕様で表されるパッケージの結合になります。（空のリストの効果は private と同じです）。value が単一の文字列の場合は、シングルトン リスト [value] として扱われます。

フラグ --incompatible_package_group_has_public_syntax と --incompatible_fix_package_group_reporoot_syntax は、この引数には影響しません。"public" と "private" の値は常に使用でき、"//..." は常に「現在のリポジトリ内のすべてのパッケージ」として解釈されます。