このセクションでは、多くの関数またはビルドルールに共通するさまざまな用語と概念を定義します。
目次
- Bourne シェルのトークン化
- ラベルの拡張
- ほとんどのビルドルールで定義される一般的な属性
- すべてのビルドルールに共通する属性
- すべてのテストルールに共通する属性(*_test)
- すべてのバイナリルールに共通する属性(*_binary)
- 構成可能な属性
- 暗黙的な出力ターゲット
Bourne シェルのトークン化
一部のルールでは、Bourne シェルのトークン化ルールに従って、文字列属性が複数の単語に分割されます。引用符で囲まれていないスペースは別々の単語を区切り、一重引用符と二重引用符とバックスラッシュはトークン化を防ぐために使用されます。
このトークン化の対象となる属性は、このドキュメントの定義で明示的に示されています。
通常、「Make」変数の展開と Bourne シェルのトークン化の対象となる属性は、コンパイラやその他のツールに任意のオプションを渡すために使用されます。このような属性の例としては、cc_library.copts
や java_library.javacopts
などがあります。これらの置換を組み合わせることで、単一の文字列変数を、構成固有のオプション ワードのリストに展開できます。
ラベルの展開
ごく少数のルールの文字列属性はラベル展開の対象になります。それらの文字列が部分文字列として有効なラベル(//mypkg:target
など)を含み、そのラベルが現在のルールの前提条件として宣言されている場合、ターゲット
//mypkg:target
で表されるファイルのパス名に展開されます。
属性の例としては、genrule.cmd
や cc_binary.linkopts
などがあります。詳細は、相対ラベルが展開されているかどうか、複数のファイルに展開されるラベルの処理方法などの問題など、それぞれのケースで大きく異なる場合があります。詳細については、ルール属性のドキュメントをご覧ください。
ほとんどのビルドルールで定義されている一般的な属性
このセクションでは、すべてのビルドルールではなく、多くのビルドルールで定義されている属性について説明します。
属性 | 説明 |
---|---|
data |
ラベルのリスト。デフォルトは 実行時にこのルールに必要なファイル。ファイルまたはルールのターゲットを一覧表示できます。通常、任意のターゲットを許可します。
新しいルールで実行時に他の入力を使用する可能性のある入力を処理する場合は、 |
deps |
ラベルのリスト。デフォルトは
このターゲットの依存関係。通常は、ルール ターゲットのみをリストします。(ルールによっては、ファイルを 通常、言語固有のルールにより、リストされるターゲットは特定のプロバイダを持つターゲットに限定されます。
多くの場合、 |
licenses |
文字列のリスト。構成不可。デフォルトは この特定のターゲットに使用されるライセンス タイプの文字列のリスト。これは、Bazel で使用されなくなったライセンス API の一部です。これは使用しないでください。 |
srcs |
ラベルのリスト。デフォルトは
このルールで処理または追加したファイル。通常はファイルを直接リストしますが、デフォルトの出力を含めるためにルール ターゲット( 多くの場合、言語固有のルールでは、リストされるファイルに特定のファイル拡張子を付ける必要があります。 |
すべてのビルドルールに共通する属性
このセクションでは、すべてのビルドルールに暗黙的に追加される属性について説明します。
属性 | 説明 |
---|---|
compatible_with |
デフォルトでサポートされている環境に加えて、このターゲットをビルドできる環境のリスト。 これは Bazel の制約システムの一部であり、ユーザーは相互に依存できるターゲットと依存できないターゲットを宣言できます。たとえば、外部にデプロイ可能なバイナリが、会社秘密のコードを含むライブラリに依存しないようにする必要があります。詳細については、 ConstraintSemantics をご覧ください。 |
deprecation |
文字列、構成不可、デフォルトは このターゲットに関連付けられている説明用の警告メッセージ。 通常、これはターゲットが古くなった、ターゲットが別のルールに置き換わった、パッケージに非公開になっている、なんらかの理由で有害とみなされる可能性があることをユーザーに知らせるために使用されます。このメッセージを回避するためにどのような変更が必要かを簡単に把握できるように、ウェブページ、バグ番号、移行 CL の例などの参照を含めることをおすすめします。ドロップイン代替として使用できる新しいターゲットがある場合は、古いターゲットのすべてのユーザーを移行することをおすすめします。
この属性はビルド方法には影響しませんが、ビルドツールの診断出力には影響する可能性があります。 パッケージ内依存関係はこの警告から除外されます。たとえば、非推奨ルールのテストをビルドしても警告は表示されません。 非推奨のターゲットが別の非推奨のターゲットに依存している場合、警告メッセージは発行されません。 ユーザーが使用を停止したら、ターゲットを削除できます。 |
distribs |
文字列のリスト。構成不可。デフォルトは この特定のターゲットに使用される配布方法の文字列のリスト。 これは、Bazel で使用されなくなったライセンス API の一部です。これは使用しないでください。 |
exec_compatible_with |
このターゲットの実行プラットフォームに存在する必要がある |
exec_properties |
文字列の辞書。デフォルトは このターゲットに対して選択されたプラットフォームの プラットフォーム プロパティとターゲット レベルのプロパティの両方にキーが存在する場合、値はターゲットから取得されます。 |
features |
feature 文字列のリスト。デフォルトは 機能とは、ターゲットで有効または無効にできる文字列タグです。特徴の意味はルール自体によって異なります。 この |
restricted_to |
デフォルトでサポートされている環境の代わりに、このターゲットをビルドできる環境のリスト。
これは Bazel の制約システムの一部です。詳しくは、 |
tags |
文字列のリスト。構成不可。デフォルトは
タグはどのルールでも使用できます。テストルールと
テストまたは
テストのタグは通常、デバッグ プロセスとリリース プロセスでテストのロールにアノテーションを付けるために使用されます。通常、タグは、ランタイム アノテーション機能のない C++ と Python のテストで特に役立ちます。タグとサイズ要素を使用すると、コードベースのチェックイン ポリシーに基づいて一連のテストを柔軟に作成できます。
Bazel は、テストルールの
|
target_compatible_with |
ラベルのリスト。デフォルトは
このターゲットを互換性とみなすためにターゲット プラットフォームに存在する必要がある 互換性のないターゲットに推移的に依存するターゲットは、それ自体は互換性がないと見なされます。また、ビルドとテストではスキップされます。 空のリスト(デフォルト)は、ターゲットがすべてのプラットフォームと互換性があることを示します。
この属性は、ワークスペース ルール以外のすべてのルールでサポートされます。一部のルールでは、この属性は無効になります。たとえば、
互換性のないターゲットのスキップについて詳しくは、プラットフォーム ページをご覧ください。 |
testonly |
ブール値。構成不可。デフォルトは
同様に、
テスト( この属性は、本番環境にリリースされるバイナリにターゲットが含まれないことを意味します。 testonly は実行時ではなくビルド時に適用され、依存関係ツリーを通じてクチコミで伝播されるため、慎重に適用する必要があります。たとえば、単体テストに役立つスタブとフェイクは、本番環境にリリースされるのと同じバイナリに関連する統合テストでも役立つ可能性があるため、testonly としてマークしないでください。逆に、通常の動作を無条件にオーバーライドするなどして、リンクすることさえ危険であるルールは、テスト専用としてマークする必要があります。 |
toolchains |
このターゲットにアクセスを許可する Make 変数のターゲットのセット。これらのターゲットは、
これは、プラットフォームに依存する構成のルール実装で使用されるツールチェーン解決のコンセプトとは異なります。この属性を使用して、ターゲットが使用する特定の |
visibility |
ラベルのリスト。構成不可。デフォルトは、指定されている場合は package から
ターゲットの |
すべてのテストルールに共通の属性(*_test)
このセクションでは、すべてのテストルールに共通する属性について説明します。
属性 | 説明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
文字列のリスト。$(location) と "Make variable" による置換、Bourne シェルのトークン化が適用されます。デフォルトは
これらの引数は、 |
||||||||||||||||||||
env |
文字列の辞書。値は、$(location) と "Make variable" による置換の対象となります。デフォルトは
この属性は、 |
||||||||||||||||||||
env_inherit |
文字列のリスト。デフォルトは
この属性は、 |
||||||||||||||||||||
size |
文字列 テスト ターゲットの「重さ」(実行に必要な時間/リソース)を指定します。 単体テストは「小規模」、統合テストは「中」、エンドツーエンド テストは「大規模」または「巨大」と見なされます。Bazel は、サイズに基づいてデフォルトのタイムアウトを決定します。これは、 テストサイズは次のデフォルト タイムアウトに対応しており、ローカル リソースのピーク使用量を想定しています。
テストの生成時に、環境変数 |
||||||||||||||||||||
timeout |
文字列 結果が返されるまでに想定されるテストの実行時間。
テストのサイズ属性はリソースの見積もりを制御しますが、テストのタイムアウトは個別に設定できます。明示的に指定しない場合、タイムアウトはテストのサイズに基づきます。テストのタイムアウトは、
上記以外の時間については、テストのタイムアウトは
環境変数 |
||||||||||||||||||||
flaky |
ブール値、構成不可。デフォルトは テストが不安定としてマークされます。 設定すると、テストを最大 3 回実行し、毎回失敗した場合にのみ不合格としてマークします。デフォルトでは、この属性は False に設定され、テストは 1 回だけ実行されます。この属性は、通常は使用しないことをおすすめします。アサーションが維持されていれば、テストは確実に合格するはずです。 |
||||||||||||||||||||
shard_count |
50 以下の負ではない整数。デフォルトは テストの実行に使用する並列シャードの数を指定します。 設定すると、この値は、テストを実行する並列シャード数を決定するために使用されるあらゆるヒューリスティックをオーバーライドします。一部のテストルールでは、そもそもシャーディングを有効にするためにこのパラメータが必要になる場合があります。 テストのシャーディングが有効になっている場合、テストの生成時に環境変数 シャーディングを行うには、テストランナーがテストのシャーディング プロトコルをサポートする必要があります。そうしないと、すべてのシャードですべてのテストが実行される可能性が高く、これは望ましいことではありません。 シャーディングの詳細については、テスト百科事典のテストのシャーディングをご覧ください。 |
||||||||||||||||||||
local |
ブール値、構成不可。デフォルトは サンドボックス化を使用せずに、テストを強制的にローカルで実行します。 このフィールドを True に設定すると、「local」をタグ( |
すべてのバイナリルールに共通する属性(*_binary)
このセクションでは、すべてのバイナリルールに共通する属性について説明します。
属性 | 説明 |
---|---|
args |
文字列のリスト。$(location) と "Make variable" による置換、Bourne シェルのトークン化の対象です。構成不可。デフォルトは
注: Bazel の外部でターゲットを実行する場合( |
env |
文字列の辞書。値は $(location) と "Make variable" 置換の対象です。デフォルトは ターゲットが
この属性は、
注: Bazel の外部でターゲットを実行する場合( |
output_licenses |
文字列のリスト。デフォルトは このバイナリが生成する出力ファイルのライセンス。これは、Bazel で使用されなくなったライセンス API の一部です。これは使用しないでください。 |
構成可能な属性
ほとんどの属性は「構成可能」です。つまり、ターゲットの構築方法が異なる場合に値が変わる可能性があります。特に、構成可能な属性は、Bazel コマンドラインに渡されるフラグや、ターゲットをリクエストしているダウンストリームの依存関係によって異なる場合があります。たとえば、複数のプラットフォームやコンパイル モードに合わせてターゲットをカスタマイズできます。
次の例では、ターゲット アーキテクチャごとに異なるソースを宣言しています。bazel build :multiplatform_lib --cpu x86
を実行すると、x86_impl.cc
を使用してターゲットがビルドされ、--cpu arm
に置き換えると arm_impl.cc
が使用されます。
cc_library( name = "multiplatform_lib", srcs = select({ ":x86_mode": ["x86_impl.cc"], ":arm_mode": ["arm_impl.cc"] }) ) config_setting( name = "x86_mode", values = { "cpu": "x86" } ) config_setting( name = "arm_mode", values = { "cpu": "arm" } )
select()
関数は、ターゲットの構成が満たす config_setting
または constraint_value
条件に基づいて、構成可能な属性のさまざまな代替値を選択します。
Bazel は、マクロの処理後、ルールの処理前(厳密には、
読み込みフェーズと分析フェーズの間)に構成可能な属性を評価します。select()
評価前の処理では、select()
がどのブランチを選択するかを認識できません。たとえば、マクロは選択したブランチに基づいて動作を変更できず、bazel query
はターゲットの構成可能な依存関係について控えめに推測するだけで済みます。ルールとマクロで select()
を使用する方法について詳しくは、
こちらのよくある質問をご覧ください。
ドキュメントで nonconfigurable
とマークされている属性では、この機能を使用できません。通常、属性は構成できません。これは、select()
の解決方法を決定する前に、Bazel が内部でその値を知る必要があるためです。
詳細な概要については、 設定可能なビルド属性をご覧ください。
暗黙的な出力ターゲット
C++ の暗黙的な出力は非推奨になりました。可能であれば、他の言語では使用しないでください。非推奨パスはまだありませんが、最終的には非推奨もされる予定です。
BUILD ファイルでビルドルールを定義すると、パッケージ内の新しい名前付きルール ターゲットを明示的に宣言します。多くのビルドルール関数には、内容と意味がルール固有である 1 つ以上の出力ファイル ターゲットも暗黙的に関連します。
たとえば、java_binary(name='foo', ...)
ルールを明示的に宣言すると、同じパッケージのメンバーとして出力ファイルのターゲット foo_deploy.jar
も暗黙的に宣言されます。(このターゲットは、デプロイに適した自己完結型の Java アーカイブです)。
暗黙的な出力ターゲットは、グローバル ターゲット グラフの最高レベルのメンバーです。他のターゲットと同様に、トップレベルのビルドコマンドで指定した場合、または他のビルド ターゲットの前提条件となる場合に、オンデマンドでビルドされます。これらは BUILD ファイル内で依存関係として参照され、bazel query
などの分析ツールの出力で監視できます。
ルールのドキュメントには、ビルドルールの種類ごとに、その種類のルールの宣言に伴う暗黙的な出力の名前と内容について詳しく説明する特別なセクションがあります。
ビルドシステムで使用される 2 つの名前空間は、重要ではあるものの微妙に区別されます。つまり、ラベルはターゲット(ルールまたはファイル)を識別します。ファイル ターゲットは、ソース(または入力)ファイル ターゲットと派生(または出力)ファイル ターゲットのいずれかに分けられます。これらは、BUILD ファイルで指定することも、コマンドラインからビルドすることも、bazel query
を使用して調べることもできます。これがターゲットの名前空間です。各ファイル ターゲットは、ディスク上の 1 つの実際のファイル(「ファイル システムの名前空間」)に対応しています。各ルール ターゲットは、ディスク上の 0 個、1 つ以上の実際のファイルに対応しています。対応するターゲットのないファイルがディスク上に存在している場合もあります。たとえば、C++ コンパイル中に生成された .o
オブジェクト ファイルは、BUILD ファイル内またはコマンドラインから参照できません。このようにして、ビルドツールはジョブの動作に関する特定の実装の詳細を非表示にすることがあります。詳細については、BUILD コンセプトのリファレンスをご覧ください。