.bzl ファイル

_ で始まる暗黙的属性には、デフォルト値と label または label_list の型が必要です。

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

宣言された属性は、None をデフォルト値に変換します。

ネストされていないプロバイダのリストは、プロバイダのリストが 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 です。

慣例として、実装関数には、マクロが検査、変更、または「メイン」以外のターゲットに渡す必要がある属性に名前付きパラメータが必要です。一方、「メイン」ターゲットに変更せずに渡される「一括」継承属性は、**kwargs として渡されます。

実装関数は値を返さないでください。代わりに、実装関数はルールまたはマクロ記号を呼び出してターゲットを宣言します。

シンボリック マクロによって宣言されたターゲットまたは内部シンボリック マクロの名前（マクロの実装関数が帰属的に呼び出す Starlark 関数を含む）は、name に等しいか（「メイン」ターゲット）、name で始まり、その後に区切り文字（"_"、"-"、"."）と文字列接尾辞が続く必要があります。（この命名規則に違反するターゲットは宣言できますが、ビルド、構成、依存は行えません）。

デフォルトでは、シンボリック マクロで宣言されたターゲット（マクロの実装関数が参照する Starlark 関数を含む）は、マクロを定義する .bzl ファイルを含むパッケージでのみ表示されます。シンボリック マクロの呼び出し元を含む外部に公開されるターゲットを宣言するには、実装関数で visibility を適切に設定する必要があります。通常は、呼び出されるルールまたはマクロ シンボルに visibility = visibility を渡します。

次の API は、マクロ実装関数内と、その関数が呼び出す Starlark 関数内では使用できません。

• package()、licenses()
• environment_group()
• native.glob() - 代わりに、ラベルリスト属性を介してマクロにグロブを渡すことができます。
• native.subpackages()
• （ルールのファイナライザでのみ許可されます。下記の finalizer をご覧ください） native.existing_rules()、 native.existing_rule()
• （WORKSPACE スレッドの場合） workspace()、 register_toolchains()、 register_execution_platforms()、 bind()、リポジトリ ルールのインスタンス化

特別な name 属性は事前宣言されているため、辞書に含めることはできません。visibility 属性名は予約済みであり、辞書に含めることはできません。

名前が _ で始まる属性は非公開です。ルールの呼び出しサイトで渡すことはできません。このような属性には、（attr.label(default="//pkg:foo") のように）デフォルト値を割り当てて、ラベルに対する暗黙的な依存関係を作成できます。

メモリ使用量を制限するため、宣言できる属性の数には上限があります。

inherit_attrs が文字列 "common" に設定されている場合、マクロはすべての Starlark ルールで使用される共通のルール属性定義を継承します。

rule() または macro() の戻り値が .bzl ファイルのグローバル変数に割り当てられていない場合、そのような値はルールまたはマクロ記号として登録されていないため、inherit_attrs に使用できません。

継承メカニズムは次のように機能します。

1. 特別な name 属性と visibility 属性は決して継承されません。
2. 非表示属性（名前が "_" で始まる属性）は継承されません。
3. 名前が attrs ディクショナリですでに定義されている属性は、継承されません（attrs のエントリが優先されます。エントリは None に設定され、その名前の属性がマクロで定義されないようにすることができます）。
4. 他のすべての属性はルールまたはマクロから継承され、attrs ディクショナリに効果的に統合されます。

必須ではない属性が継承されると、元のルールまたはマクロで指定された値に関係なく、属性のデフォルト値は None にオーバーライドされます。これにより、マクロが属性の値をラップされたルールまたはマクロのインスタンスに転送するときに（変更されていない **kwargs を渡すなど）、外側のマクロの呼び出しに存在しなかった値が内部のルールまたはマクロの呼び出しにも存在しなくなるようにします（None を属性に渡すことは、属性を省略することと同じように扱われるためです）。これは、属性を省略すると、見かけのデフォルト値を渡す場合とはセマンティクスが微妙に異なるため、重要です。特に、省略された属性は一部の bazel query 出力形式には表示されず、計算されたデフォルトは値が省略されている場合にのみ実行されます。マクロで継承された属性を調べたり変更したりする必要がある場合（継承された tags 属性に値を追加する場合など）は、マクロの実装関数で None ケースを処理する必要があります。

たとえば、次のマクロは、cxxopts（属性リストから削除）と copts（新しい定義が指定）を除き、native.cc_library からすべての属性を継承します。また、追加のタグを追加する前に、継承された tags 属性のデフォルトの None 値を確認します。

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

inherit_attrs が設定されている場合、マクロの実装関数には **kwargs 残留キーワード パラメータが必要です。

慣例として、マクロは、オーバーライドされていない継承された属性を、マクロがラップする「メイン」ルールまたはマクロ記号に変更せずに渡す必要があります。通常、継承された属性のほとんどは、実装関数のパラメータ リストにパラメータを持たず、単に **kwargs を介して渡されます。マクロでこれらの属性を「メイン」と「メイン以外」の両方のターゲットに渡す必要がある場合は、実装関数に一部継承された属性（最も一般的には tags と testonly）の明示的なパラメータがあると便利です。ただし、マクロでこれらの属性を検査または操作する必要がある場合は、必須ではない継承された属性の None デフォルト値を慎重に処理する必要があります。

通常のシンボリック マクロとは異なり、ルール ファイナライザは native.existing_rule() と native.existing_rules() を呼び出して、現在のパッケージで定義されているファイナライザ以外のルール ターゲットのセットをクエリする場合があります。native.existing_rule() と native.existing_rules() は、このファイナライザを含むルール ファイナライザによって定義されたターゲットにアクセスできません。

• フィールドのリスト:
  

  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 = ...)

宣言された属性は、None をデフォルト値に変換します。

宣言された属性は、None をデフォルト値に変換します。

事前宣言された出力を定義するためのスキーマ。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]（すべてのラベルリスト属性に対して）

rule()、aspect()、repository_rule() とは異なり、宣言された属性では None がデフォルト値に変換されません。デフォルトを使用するには、呼び出し元が属性を完全に省略する必要があります。

パッケージの仕様は 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" の値は常に使用できます。"//..." は常に「現在のリポジトリ内のすべてのパッケージ」として解釈されます。