一般的な定義

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。
問題を報告 ソースを表示

このセクションでは、多くの関数またはビルドルールに共通するさまざまな用語とコンセプトを定義します。

目次

Bourne シェルのトークン化

一部のルールの特定の文字列属性は、Bourne シェルのトークン化ルールに従って複数の単語に分割されます。引用符で囲まれていないスペースは別々の単語を区切り、単一引用符と二重引用符はトークン化を防止するために使用されます。

このトークン化の対象となる属性は、このドキュメントの定義で明示的に示されています。

一般に、「Make」変数の拡張と Bourne シェルのトークン化の対象となる属性は、コンパイラやその他のツールに任意のオプションを渡すために使用されます。このような属性の例としては、cc_library.coptsjava_library.javacopts があります。これらの置換を組み合わせることで、1 つの文字列変数を、構成固有のオプション単語のリストに展開できます。

ラベルの拡張

ごく一部のルールの文字列属性にはラベル拡張が適用されます。たとえば、//mypkg:target のように、文字列に有効なラベルが部分文字列として含まれており、そのラベルが現在のルールの前提条件として宣言されている場合、ターゲットで表されるファイルのパスに展開されます。

属性の例としては、genrule.cmdcc_binary.linkopts が挙げられます。詳細は、相対ラベルが展開されているかどうか、複数のファイルに展開されるラベルの処理方法など、問題ごとに大きく異なる場合があります。詳細については、ルール属性のドキュメントをご覧ください。

ほとんどのビルドルールで定義されている一般的な属性

このセクションでは、多くのビルドルールで定義されている属性について説明します(すべてではありません)。

属性 説明
data

List of labels ; optional

実行時にこのルールで必要なファイル。ファイルまたはルールのターゲットを一覧表示できます。通常、すべてのターゲットを許可します。

data 属性内のターゲットのデフォルトの出力とランファイルは、このターゲットによって出力される、またはこのターゲットへのランタイムの依存関係がある実行ファイルの *.runfiles 領域に表示されます。これには、このターゲットの srcs の実行時に使用されるデータファイルまたはバイナリが含まれる場合があります。データファイルに依存して使用する方法について詳しくは、データの依存関係をご覧ください。

実行時に他の入力を使用する可能性がある入力を処理する場合は、新しいルールで data 属性を定義する必要があります。ルールの実装関数は、任意の data 属性の出力とランファイルからターゲットのランファイルを入力することも、ソースコードまたはランタイム依存関係を提供する任意の依存関係属性のランファイルにも入力する必要があります。

deps

List of labels ; optional

このターゲットの依存関係。通常は、ルール ターゲットのみを一覧表示します。(一部のルールではファイルを直接 deps にリストできますが、これは可能な限り避ける必要があります)。

言語固有のルールは通常、リストされたターゲットを特定のプロバイダを持つルールに制限します。

deps を使用してターゲットが依存しようとすることの意味の正確なセマンティクスは、ルールの種類によって異なります。また、ルール固有のドキュメントで詳しく説明しています。ソースコードを処理するルールの場合、deps は通常、srcs のコードで使用されるコード依存関係を指定します。

ほとんどの場合、deps 依存関係は、あるモジュールが別のプログラミング言語で定義されたシンボルを同じプログラミング言語で使用し、個別にコンパイルできるようにするために使用します。言語横断的な依存関係も多くの場合許可されています。たとえば、java_library ターゲットを cc_library 属性の C++ コードに依存する場合、後者を deps 属性にリストします。詳細については、依存関係の定義をご覧ください。

licenses

List of strings; optional; nonconfigurable

このターゲットに使用するライセンス タイプの文字列のリスト。これは、Bazel で使用されなくなった非推奨のライセンス API の一部です。この属性は使用しないでください。

srcs

List of labels ; optional

このルールによって処理または含まれているファイル。通常、ファイルを直接リストしますが、ルール ターゲット(filegroupgenrule など)を表示してデフォルト出力を含めることもできます。

多くの場合、言語固有のルールでは、リストにあるファイルに特定のファイル拡張子が必要です。

すべてのビルドルールに共通の属性

このセクションでは、すべてのビルドルールに暗黙的に追加される属性について説明します。

属性 説明
compatible_with

List of labels ; optional; nonconfigurable

デフォルトのサポート対象環境に加えて、このターゲットのビルド先となる環境のリスト。

これは Bazel の制約システムの一部であり、ユーザーは依存可能なターゲットと依存できないターゲットを宣言できます。たとえば、外部にデプロイ可能なバイナリは、会社のシークレット コードがあるライブラリに依存しないでください。詳しくは、ConstraintSemantics をご覧ください。

deprecation

String; optional; nonconfigurable

このターゲットに関連付けられた警告の警告メッセージ。通常、これはターゲットが古くなった、別のルールに置き換わった、パッケージで非公開になっている、またはなんらかの理由で有害であると見なされることをユーザーに知らせるために使用されます。メッセージを回避するために必要な変更点を簡単に確認できるように、いくつかの参照(ウェブページ、バグ番号、移行 CL の例など)を含めることをおすすめします。代替として使用できる新しいターゲットがある場合は、古いターゲットのすべてのユーザーを移行することをおすすめします。

この属性はビルド方法には影響しませんが、ビルドツールの診断出力に影響する可能性があります。deprecation 属性を含むルールが別のパッケージのターゲットによって依存されている場合は、ビルドツールによって警告が発行されます。

パッケージ内の依存関係はこの警告から除外されます。たとえば、非推奨のルールのテストを作成しても、警告は発生しません。

非推奨のターゲットが別の非推奨のターゲットに依存している場合、警告メッセージは発行されません。

ターゲットの使用を停止すると、ターゲットを削除できます。

distribs

List of strings; optional; nonconfigurable

この特定のターゲットに使用される配布方法の文字列のリスト。これは、Bazel で使用されなくなった非推奨のライセンス API の一部です。この属性は使用しないでください。

exec_compatible_with

List of labels ; optional; nonconfigurable

このターゲットの実行プラットフォームに存在する必要がある constraint_values のリスト。これは、ルールタイプによってすでに設定されている制約とは別に適用されます。制約は、使用可能な実行プラットフォームのリストを制限するために使用されます。詳細については、ツールチェーンの解決をご覧ください。

exec_properties

Dictionary of strings; optional

このターゲット用に選択されたプラットフォームの exec_properties に追加される文字列の辞書。プラットフォーム ルールの exec_properties をご覧ください。

プラットフォーム レベルとターゲット レベルのプロパティの両方にキーがある場合、値はターゲットから取得されます。

features

List of feature strings; optional

特徴は、ターゲットで有効または無効にできる文字列タグです。機能の意味はルール自体によって異なります。

この features 属性は、パッケージ レベルの features 属性と組み合わされます。たとえば、機能 ["a"、"b"] がパッケージ レベルで有効で、ターゲットの features 属性に ["-a", "c"] が含まれている場合、ルールで有効になる機能は「b」と「c」です。 例を見る

restricted_to

List of labels ; optional; nonconfigurable

デフォルトでサポートされる環境ではなく、このターゲット用に構築できる環境のリスト。

これは Bazel の制約システムの一部です。詳しくは、compatible_with をご覧ください。

tags

List of strings; optional; nonconfigurable

タグはあらゆるルールで使用できます。テストルールと test_suite ルールに対するタグは、テストの分類に役立ちます。テストされていないターゲットのタグは、genruleStarlark アクションのサンドボックス実行を制御するため、また人間や外部ツールによる解析に使用されます。

テストまたは genrule ターゲットの tags 属性、または Starlark アクションの execution_requirements のキーに次のキーワードが見つかった場合、Bazel はサンドボックス化コードの動作を変更します。

  • no-sandbox キーワードの結果、アクションまたはテストはサンドボックス化されません。キャッシュまたはリモートで実行できます。no-cache または no-remote を使用して、これらの両方またはいずれかを防ぐことができます。
  • no-cache キーワードの結果、アクションまたはテストは(リモートまたはローカルで)キャッシュに保存されません
  • no-remote-cache キーワードの結果、アクションまたはテストはリモートでキャッシュに保存されません(ただし、ローカルにキャッシュされる場合があります。また、リモートで実行される場合もあります)。注: このタグでは、ディスク キャッシュはローカル キャッシュとみなされ、http キャッシュと gRPC キャッシュはリモートとみなされます。キャッシュの組み合わせ(つまり、ローカル コンポーネントとリモート コンポーネントを含むキャッシュ)を指定すると、リモート キャッシュとして扱われます。ただし、--incompatible_remote_results_ignore_disk が設定されていない場合はローカル コンポーネントが使用されます。
  • no-remote-exec キーワードを指定すると、アクションまたはテストはリモートで実行されなくなります(ただし、リモートではキャッシュされる場合があります)。
  • no-remote キーワードは、アクションまたはテストがリモートで実行されないように、またはリモートでキャッシュに保存されないようにします。これは、no-remote-cacheno-remote-exec の両方を使用する場合と同じです。
  • no-remote-cache-upload キーワードは、スポーンのリモート キャッシュのアップロードを無効にします。リモート実行は無効になりません。
  • local キーワードによって、アクションまたはテストがリモートでキャッシュまたはリモートで実行またはサンドボックス内で実行できなくなります。genrules とテストの場合、local = True 属性でルールをマークしても結果は同じです。
  • requires-network キーワードを使用すると、サンドボックス内から外部ネットワークにアクセスできます。このタグが有効なのは、サンドボックスが有効になっている場合のみです。
  • block-network キーワードは、サンドボックス内からの外部ネットワークへのアクセスをブロックします。この場合、localhost との通信のみが許可されます。このタグが有効なのは、サンドボックスが有効になっている場合のみです。
  • requires-fakeroot は、テストまたはアクションを uid と gid 0(root ユーザー)として実行します。これは Linux でのみサポートされています。このタグは、--sandbox_fake_username コマンドライン オプションよりも優先されます。

通常、テストのタグは、デバッグおよびリリース プロセスにおけるテストの役割にアノテーションを付けるために使用されます。通常、タグは、ランタイムのアノテーションがない C++ テストと Python テストで特に便利です。タグとサイズの要素を使用すると、コードベースのチェックイン ポリシーに基づいて一連のテストを柔軟に組み立てることができます。

テストルールの tags 属性に次のキーワードが見つかった場合、Bazel はテスト実行の動作を変更します。

  • exclusive は、テストを強制的に「排他的」モードで実行し、他のテストが同時に実行されないようにします。このようなテストは、すべてのビルド アクティビティと非独占テストの完了後に、シリアルで実行されます。Bazel はリモートマシンで実行されているものを制御できないため、このようなテストではリモート実行は無効になります。
  • exclusive-if-local は、ローカルで実行した場合はテストを「排他的」モードに実行しますが、リモートで実行した場合はテストを並行して実行します。
  • manual キーワードを使用すると、ターゲット パターンのワイルドカード(...:*:all など)と test_suite ルールが除外されます。これらのルールでは、buildtestcoverage コマンドのビルドと実行に使用するトップレベル ターゲットのセットを計算する際に、テストを明示的に指定することはできません。query コマンドを含む他のコンテキストでは、ターゲット ワイルドカードやテストスイートの拡張には影響しません。manual は、継続的なビルドシステムやテストシステムによって自動的にターゲットがビルドまたは実行されるべきということを意味しません。たとえば、特定の Bazel フラグを必要とするものの、適切に構成された presubmit または継続的テスト実行に含まれているターゲットを bazel test ... から除外することが望ましい場合があります。
  • external キーワードは、(--cache_test_results の値に関係なく)無条件にテストを実行します。
テスト ターゲットに添付されるタグに関するその他の規則については、テスト百科事典のタグ規則をご覧ください。
target_compatible_with

List of labels ; optional

このターゲットが互換性があると見なされるには、ターゲット プラットフォームに存在する必要がある constraint_value のリスト。これは、ルールタイプですでに設定されている制約に加えて適用されます。ターゲット プラットフォームがリストにあるすべての制約を満たしていない場合、ターゲットは互換性がないとみなされます。互換性のないターゲットは、ターゲット パターンが拡張されている場合(例: //...:all)に、ビルドとテストのためにスキップされます。互換性のないターゲットがコマンドラインで明示的に指定された場合、Bazel はエラーを出力し、ビルドまたはテストの失敗を引き起こします。

互換性のないターゲットに推移的に依存するターゲット自体は互換性がないとみなされます。また、ビルドとテストもスキップされます。

空のリスト(デフォルト)は、ターゲットがすべてのプラットフォームと互換性があることを示します。

Workspace ルール以外のすべてのルールでこの属性がサポートされます。一部のルールでは、この属性は効果がありません。たとえば、cc_toolchaintarget_compatible_with を指定しても意味がありません。

互換性のないターゲットのスキップについて詳しくは、プラットフォームのページをご覧ください。

testonly

Boolean; optional; default False except for test and test suite targets; nonconfigurable

True の場合、テスト専用ターゲット(テストなど)のみがこのターゲットに依存できます。

同様に、testonly でないルールを testonly であるルールに依存することはできません。

テスト(*_test ルール)とテストスイート(test_suite ルール)はデフォルトで testonly です。

この属性は、本番環境にリリースされるバイナリにターゲットが含まれないようにすることを目的としています。

testonly は実行時ではなくビルド時に適用され、依存関係ツリーにクチコミが拡散するため、慎重に適用する必要があります。たとえば、単体テストに役立つスタブと疑似も、本番環境にリリースされるのと同じバイナリを使用する統合テストに役立つ可能性があるため、テスト専用としてマークするべきではありません。逆に、通常の動作を無条件にオーバーライドするなど、リンクするのも危険なルールは、確実にテスト専用としてマークする必要があります。

toolchains

List of labels ; optional; nonconfigurable

この変数に変数の作成を許可するターゲットのセット。これらのターゲットは、TemplateVariableInfo を提供するルールのインスタンスか、Bazel に組み込まれているツールチェーン タイプ用の特別なターゲットです。次に例を示します。

  • @bazel_tools//tools/cpp:current_cc_toolchain
  • @bazel_tools//tools/jdk:current_java_runtime

これは、プラットフォームに依存する構成のルール実装で使用されるツールチェーンの解決のコンセプトとは異なることに注意してください。この属性を使用して、ターゲットで使用する特定の cc_toolchain または java_toolchain を決定することはできません。

visibility

List of labels ; optional; default default_visibility from package if specified, or //visibility:private otherwise; nonconfigurable

ターゲットの visibility 属性は、ターゲットを他のパッケージで使用できるかどうかを制御します。可視性に関するドキュメントをご覧ください。

すべてのテストルールに共通の属性(*_test)

このセクションでは、すべてのテストルールに共通の属性について説明します。

属性 説明
args

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization

bazel test で Bazel がターゲットに渡されるときに渡すコマンドライン引数。

これらの引数は、bazel test コマンドラインで指定された --test_arg 値の前に渡されます。

env

Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution

bazel test によってテストの実行時に設定される追加の環境変数を指定します。

この属性は、cc_testpy_testsh_test などのネイティブ ルールにのみ適用されます。Starlark で定義されたテストルールには適用されません。独自の Starlark ルールでは、「env」属性を追加し、それを使用して TestEnvironment プロバイダにデータを入力できます。

env_inherit

List of strings; optional

bazel test によってテストが実行されたときに、外部環境から継承する追加の環境変数を指定します。

この属性は、cc_testpy_testsh_test などのネイティブ ルールにのみ適用されます。Starlark で定義されたテストルールには適用されません。

size

String "enormous", "large" "medium" or "small", default is "medium"; optional; nonconfigurable

テスト ターゲットの「負荷」を指定します。実行に必要な時間やリソースの量などです。

単体テストは「小規模」、統合テストは「中」、エンドツーエンド テストは「大規模」または「大規模」とみなされます。Bazel は、サイズを使用してデフォルトのタイムアウトを決定します。これは timeout 属性でオーバーライドできます。タイムアウトは、個々のテストではなく、BUILD ターゲット内のすべてのテストで発生します。テストをローカルで実行する場合、スケジューリングのために size も使用します。Bazel は --local_{ram,cpu}_resources を優先し、大量の負荷を同時にテストすることでローカルマシンに負荷をかけないようにしようとします。

テストサイズは、次のデフォルトのタイムアウトに対応し、ローカル リソースのピーク使用量を想定しています。

サイズ RAM(MB) CPU(CPU コア数) デフォルトのタイムアウト
small 20 1 短い(1 分)
中程度の幅 100 1 中(5 分)
300 1 長い(15 分)
膨大な 800 1 eternal(60 分)

テストを生成するときに、環境変数 TEST_SIZE がこの属性の値に設定されます。

timeout

String "short", "moderate", "long", "eternal" (with the default derived from the test's size attribute); nonconfigurable

テストの実行が終わるまでの推定時間。

テストのサイズ属性はリソースの見積もりを制御しますが、テストのタイムアウトは個別に設定できます。明示的に指定しない場合、タイムアウトはテストのサイズに基づきます。テスト タイムアウトは、--test_timeout フラグを使用してオーバーライドできます。たとえば、低速であることが判明している特定の条件の下で実行できます。テストのタイムアウト値は、次の期間に対応します。

タイムアウト値 期間
short 1 分
やや不足 5 分
long 15 分
エターナル 60 分

上記以外の場合、テスト タイムアウトは --test_timeout bazel フラグでオーバーライドできます。たとえば、低速であることがわかっている条件で手動で実行する場合などです。--test_timeout 値は秒単位です。たとえば、--test_timeout=120 の場合、テストのタイムアウトは 2 分に設定されます。

環境変数 TEST_TIMEOUT は、テストを生成するときにテスト タイムアウト(秒単位)に設定されます。

flaky

Boolean; optional; default False; nonconfigurable

テストを不安定とマークします。

設定すると、テストが最大 3 回実行され、失敗するたびにテストが失敗します。この属性はデフォルトで False に設定されており、テストは 1 回だけ実行されます。一般に、この属性の使用はおすすめしません。アサーションがサポートされている場合は、テストに必ず合格する必要があります。

shard_count

Non-negative integer less than or equal to 50; optional

テストの実行に使用する並列シャードの数を指定します。

この値は、テストを実行する並列シャードの数を決定するために使用されるヒューリスティックをオーバーライドします。一部のテストルールでは、最初にシャーディングを有効にするためにこのパラメータが必要になることがあります。--test_sharding_strategy もご覧ください。

テストのシャーディングが有効になっている場合、テストを生成するときに、環境変数 TEST_TOTAL_SHARDS がこの値に設定されます。

シャーディングでは、テストランナーがテスト シャーディング プロトコルをサポートする必要があります。そうしない場合、ほとんどのシャードごとにすべてのテストが実行される可能性がありますが、これは望ましいことではありません。

シャーディングの詳細については、Test Encyclopedia のテストのシャーディングをご覧ください。

local

Boolean; default False; nonconfigurable

サンドボックス化せずに、テストをローカルで強制的に実行します。

True に設定すると、タグ「tags=["local"]」として「ローカル」が提供されます。

すべてのバイナリルールに共通する属性(*_binary)

このセクションでは、すべてのバイナリルールに共通の属性について説明します。

属性 説明
args

List of strings; optional; subject to $(location) and "Make variable" substitution, and Bourne shell tokenization; nonconfigurable

Bazel が run コマンドまたはテストとしてターゲットに渡される場合のコマンドライン引数。これらの引数は、bazel run または bazel test コマンドラインで指定された引数の前に渡されます。

注: Bazel の外部でターゲットを実行した場合(bazel-bin/ でバイナリを手動で実行した場合など)、引数は渡されません。

env

Dictionary of strings; optional; values are subject to $(location) and "Make variable" substitution

bazel run によってターゲットの実行時に設定される追加の環境変数を指定します。

この属性は、cc_binarypy_binarysh_binary などのネイティブ ルールにのみ適用されます。Starlark で定義された実行可能ルールには適用されません。

注: Bazel の外部でターゲットを実行する場合(たとえば、bazel-bin/ でバイナリを手動で実行する場合)、環境変数は設定されません。

output_licenses

List of strings; optional

このバイナリによって生成された出力ファイルのライセンス。 これは、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 つの Namespace の重要な違いはわずかです。ラベルはルールまたはファイルであるターゲットを識別します。ファイル ターゲットは、ソース(または入力)ファイル ターゲットと派生(出力)ファイル ターゲットに分割できます。これらは、BUILD ファイルで記述することも、コマンドラインからビルドすることも、bazel query を使用して調べることもできます。これがターゲット名前空間です。各ファイル ターゲットは、ディスク上の 1 つの実際のファイル(ファイル システム名前空間)に対応します。各ルール ターゲットは、ディスク上の 0 個以上の実際のファイルに対応しています。対応するターゲットのないディスク上のファイルが存在する可能性があります。たとえば、C++ コンパイル中に生成された .o オブジェクト ファイルは、BUILD ファイル内から、またはコマンドラインから参照できません。 このように、ビルドツールはジョブの実行方法に関する特定の実装の詳細を非表示にできます。詳細については、BUILD コンセプト リファレンスをご覧ください。