このセクションでは、多くの関数やビルドルールに共通する用語とコンセプトを定義します。
目次
- Bourne シェルのトークン化
- ラベルの展開
- ほとんどのビルドルールで定義される一般的な属性
- すべてのビルドルールに共通の属性
- すべてのテストルールに共通の属性(*_test)
- すべてのバイナリルールに共通の属性(*_binary)
- 構成可能な属性
- 暗黙的な出力ターゲット
Bourne シェルのトークン化
一部のルールでは、一部の文字列属性は Bourne シェルのトークン化ルールに従って複数の単語に分割されます。引用符で囲まれていないスペースは単語を区切り、一重引用符と二重引用符、バックスラッシュはトークン化を防ぐために使用されます。
このトークン化の対象となる属性は、このドキュメントの定義で明示されています。
「Make」変数展開と Bourne シェルのトークン化の対象となる属性は、通常、任意のオプションをコンパイラやその他のツールに渡すために使用されます。このような属性の例としては、cc_library.copts
や java_library.javacopts
などがあります。これらの置換を組み合わせることで、1 つの文字列変数を構成固有のオプション単語リストに展開できます。
ラベルの拡張
ごく一部のルールでも、ラベル拡張の対象となる文字列属性があります。それらの文字列に、部分文字列として有効なラベル(//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 のテストで特に役立ちます。これらのテストにはランタイム アノテーション機能がありません。タグとサイズ要素を使用すると、コードベースのチェックイン ポリシーに基づいてテストスイートを柔軟に作成できます。
テストルールの
|
target_compatible_with |
ラベルのリスト。デフォルトは
このターゲットが互換性であると見なされるために、ターゲット プラットフォームに存在する必要がある 互換性のないターゲットに推移的に依存しているターゲットは、それ自体が互換性がないと見なされます。ビルドとテストではスキップされます。 空のリスト(デフォルト)は、ターゲットがすべてのプラットフォームと互換性があることを示します。
この属性は、Workspace ルール以外のすべてのルールでサポートされています。
一部のルールでは、この属性は効果がありません。たとえば、
互換性のないターゲットのスキップの詳細については、プラットフォーム ページをご覧ください。 |
testonly |
ブール値。構成不可。デフォルトは
同様に、
テスト( この属性は、本番環境にリリースされるバイナリにターゲットが含まれないことを意味します。 testonly は実行時ではなくビルド時に適用され、依存関係ツリーを介して広範に伝播されるため、適用は慎重に行う必要があります。たとえば、単体テストに役立つスタブとフェイクは、本番環境にリリースされるのと同じバイナリを含む統合テストでも役立つ可能性があるため、テスト専用としてマークしないでください。逆に、通常の動作を無条件にオーバーライドするなど、リンクしても危険なルールは、テスト専用としてマークする必要があります。 |
toolchains |
このターゲットがアクセスできる Make 変数を含むターゲットのセット。これらのターゲットは、
これは、プラットフォームに依存する構成のルール実装で使用されるツールチェーンの解決のコンセプトとは異なります。この属性を使用して、ターゲットが使用する |
visibility |
ラベルのリスト。構成不可。デフォルトは、指定されている場合はパッケージの
ターゲットの |
すべてのテストルールに共通の属性(*_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
とマークされている属性では、この機能を使用できません。通常、属性は構成できません。Bazel は、select()
の解決方法を決定する前に、内部でその値を認識する必要があるからです。
詳しくは、 構成可能なビルド属性をご覧ください。
暗黙的な出力ターゲット
C++ の暗黙的な出力は非推奨となりました。可能であれば、他の言語では使用しないようにしてください。非推奨パスはまだありませんが、最終的には非推奨になります。
BUILD ファイルでビルドルールを定義すると、パッケージ内の新しい名前付きルール ターゲットを明示的に宣言します。多くのビルドルール関数には暗黙的に 1 つ以上の出力ファイル ターゲットも含まれており、その内容と意味はルール固有です。
たとえば、java_binary(name='foo', ...)
ルールを明示的に宣言すると、出力ファイルのターゲット foo_deploy.jar
を同じパッケージのメンバーとして暗黙的に宣言します。(このターゲットは、デプロイに適した自己完結型の Java アーカイブです)。
暗黙的な出力ターゲットは、グローバル ターゲット グラフの第一クラスのメンバーです。他のターゲットと同様に、トップレベルのビルド コマンドで指定した場合、または他のビルド ターゲットの前提条件となる場合に、オンデマンドでビルドされます。BUILD ファイルでは依存関係として参照でき、bazel query
などの分析ツールの出力で確認できます。
ビルドルールの種類ごとに、そのルールのドキュメントには、その種類のルールの宣言に伴う暗黙的な出力の名前と内容について詳しく説明した特別なセクションがあります。
ビルドシステムで使用される 2 つの名前空間は、重要では若干異なりますが、ラベルはターゲット(ルールまたはファイル)を表します。ファイル ターゲットは、ソース(または入力)ファイル ターゲットと派生(または出力)ファイル ターゲットのいずれかに分けられます。BUILD ファイルで指定することも、コマンドラインからビルドすることもできます。また、bazel query
を使用して調べることもできます。これがターゲット名前空間です。各ファイル ターゲットは、ディスク上の 1 つの実際のファイル(「ファイル システムの名前空間」)に対応します。各ルール ターゲットは、ディスク上の実際のファイル(0 個または複数)に対応する場合があります。対応するターゲットのないファイルがディスク上に存在している可能性があります。たとえば、C++ のコンパイル中に生成された .o
オブジェクト ファイルは、BUILD ファイル内またはコマンドラインから参照できません。
これにより、ビルドツールがそのジョブの実行方法に関する特定の実装の詳細を隠す場合があります。詳細については、BUILD のコンセプトのリファレンスをご覧ください。