.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` には、`deps` の 1 つとしてターゲット `charlie` があるとします。アスペクトの `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() - 代わりに、ラベルリスト属性を介してマクロに 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() は、このルール ファイナライザーを含む、ルール ファイナライザーで定義されたターゲットにアクセスできません。

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

• フィールドのリスト:
  

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

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

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

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

provider() を呼び出して作成されたプロバイダ シンボルを P とします。概念的には、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. P の新しいインスタンスは、c(**d) のように、d のエントリをキーワード引数としてデフォルトのコンストラクタを呼び出すかのように生成されます。

注: 上記の手順は、*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 によってサブルールの実装関数に自動的に渡されます（したがって、実装関数は属性名と一致する名前付きパラメータを受け入れる必要があります）。これらの値の型は次のようになります。

• executable=True を含むラベル属性の FilesToRunProvider
• allow_single_file=True を含むラベル属性の File
• その他のラベル属性の場合は Target
• すべての label-list 属性の [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" の値は常に使用可能で、"//..." は常に「現在のリポジトリ内のすべてのパッケージ」として解釈されます。