このセクションでは、多くの関数やビルドルールに共通するさまざまな用語と概念を定義します。
目次
- Bourne シェルのトークン化
- ラベルの拡張
- ほとんどのビルドルールで定義される一般的な属性
- すべてのビルドルールに共通する属性
- すべてのテストルールに共通する属性(*_test)
- すべてのバイナリルールに共通する属性(*_binary)
- 構成可能な属性
- 暗黙的な出力ターゲット
Bourne シェルのトークン化
一部のルールの文字列属性は、Bourne シェルのトークン化ルールに従って複数の単語に分割されます。引用符で囲まれていないスペースは個々の単語を区切り、一重引用符と二重引用符とバックスラッシュはトークン化を防ぐために使用されます。
このトークン化の対象となる属性は、このドキュメントにおける定義の中で明示されています。
通常、「Make」変数展開と Bourne Shell トークン化の対象となる属性は、任意のオプションをコンパイラやその他のツールに渡すために使用されます。このような属性の例としては、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 |
文字列のリスト。構成不可。デフォルトは
タグは任意のルールで使用できます。テストルールと
Bazel は、テストターゲットまたは
テスト上のタグは通常、デバッグとリリースのプロセスでテストの役割にアノテーションを付けるために使用されます。通常、タグは、ランタイム アノテーション機能がない C++ と Python のテストに最も役立ちます。タグとサイズ要素を使用すると、コードベースのチェックイン ポリシーに基づいてテストスイートを柔軟に作成できます。
Bazel は、テストルールの
|
target_compatible_with |
ラベルのリスト。デフォルトは
このターゲットに互換性があるとみなされるには、ターゲット プラットフォームに存在する必要がある 互換性のないターゲットに推移的に依存するターゲット自体は、互換性がないとみなされます。また、ビルドとテストでもスキップされます。 空のリスト(デフォルト)は、ターゲットがすべてのプラットフォームと互換性があることを示します。
Workspace ルール以外のすべてのルールでこの属性がサポートされます。一部のルールでは、この属性は機能しません。たとえば、
互換性のないターゲットのスキップの詳細については、プラットフォーム ページをご覧ください。 |
testonly |
ブール値、設定不可。デフォルトは
同様に、
テスト( この属性は、本番環境にリリースされるバイナリにターゲットを含めないことを意味します。 testonly は実行時ではなくビルド時に適用され、依存関係ツリーを通じて拡散されるため、これは慎重に適用する必要があります。たとえば、単体テストに役立つスタブとフェイクは、本番環境にリリースされるのと同じバイナリを含む統合テストにも役立つため、testonly とマークしないでください。逆に、通常の動作を無条件にオーバーライドするためなど、リンクしても危険なルールは、必ず testonly とマークする必要があります。 |
toolchains |
このターゲットにアクセスを許可する Make 変数を持つターゲットのセット。これらのターゲットは、
これは、プラットフォームに依存する構成のルール実装で使用されるツールチェーンの解決のコンセプトとは異なります。この属性を使用して、ターゲットが使用する特定の |
visibility |
ラベルのリスト。構成不可。デフォルトは、指定された場合は package の
ターゲットの |
すべてのテストルールに共通する属性(*_test)
このセクションでは、すべてのテストルールに共通する属性について説明します。
属性 | 説明 | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
文字列のリスト。$(location) と Make variable の置換、Bourne シェルのトークン化の対象となります。デフォルトは Bazel が
これらの引数は、 |
||||||||||||||||||||
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 個または 1 つ以上の実際のファイルに対応しています。対応するターゲットがないファイルがディスク上に存在する場合があります。たとえば、C++ コンパイル中に生成された .o
オブジェクト ファイルは、BUILD ファイル内またはコマンドラインから参照できません。
このようにして、ビルドツールは自身の役割に関する特定の実装の詳細を非表示にできます。詳しくは、BUILD コンセプトのリファレンスをご覧ください。