変数を作成する

問題を報告する ソースを表示 Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

「作成」変数は、「変数を作成」の置換の対象としてマークされた属性で使用できる、拡張可能な文字列変数の特別なクラスです。

たとえば、ユーザーが作成したビルドアクションに特定のツールチェーン パスを挿入するために使用できます。

Bazel には、すべてのターゲットで使用できる事前定義変数と、依存関係ターゲットで定義され、依存するターゲットでのみ使用できるカスタム変数の両方が用意されています。

「Make」という用語が使用されているのは、これらの変数の構文と意味が、元々 GNU Make と一致するように意図されていたためです。

使用

「Make 変数の置換の対象」としてマークされた属性は、次のように「Make」変数 FOO を参照できます。

my_attr = "prefix $(FOO) suffix"

つまり、$(FOO) に一致する部分文字列は、FOO の値に展開されます。その値が "bar" の場合、最終的な文字列は次のようになります。

my_attr = "prefix bar suffix"

FOO が、使用ターゲットに既知の変数に対応していない場合、Bazel はエラーで失敗します。

名前が文字以外の記号（@ など）の「Make」変数は、かっこなしでドル記号のみを使用して参照することもできます。次に例を示します。

my_attr = "prefix $@ suffix"

$ を文字列リテラルとして記述するには（つまり、変数の展開を防ぐには）、$$ を記述します。

事前定義された変数

事前定義された「Make」変数は、任意のターゲットで「"Make 変数"の置換の対象」としてマークされている任意の属性で参照できます。

特定のビルドオプションのセットのこれらの変数とその値のリストを表示するには、次のコマンドを実行します。

bazel info --show_make_env [build options]

出力の上部にある大文字の行を確認します。

事前定義された変数の例をご覧ください。

ツールチェーン オプション変数

  • COMPILATION_MODE: fastbuild、dbg、または opt。（詳細）

パス変数

  • BINDIR: ターゲット アーキテクチャ用に生成されたバイナリ ツリーのベース。

    クロスコンパイルをサポートするために、ホスト アーキテクチャでビルド中に実行されるプログラムに別のツリーが使用される場合があります。

    genrule 内からツールを実行する場合は、$(execpath toolname) を使用してパスを取得することをおすすめします。この場合、genrule の tools 属性に toolname を指定する必要があります。

  • GENDIR: ターゲット アーキテクチャ用に生成されたコードツリーのベース。

マシン アーキテクチャ変数

  • TARGET_CPU: ターゲット アーキテクチャの CPU（例: k8）。

事前定義された genrule 変数

以下は genrule の cmd 属性で特別に使用でき、通常、その属性を機能させるために重要です。

事前定義された genrule 変数の例をご覧ください。

  • OUTS: genrule の outs リスト。出力ファイルが 1 つしかない場合は、$@ を使用することもできます。
  • SRCS: genrule の srcs リスト（より正確には、srcs リストのラベルに対応するファイルのパス名）。ソースファイルが 1 つしかない場合は、$< を使用することもできます。
  • <: 単一ファイルの場合は SRCS。それ以外の場合は、ビルドエラーがトリガーされます。
  • @: 単一ファイルの場合は OUTS。それ以外の場合は、ビルドエラーがトリガーされます。

  • RULEDIR: ターゲットの出力ディレクトリ。つまり、genfiles ツリーまたは bin ツリーの下にターゲットを含むパッケージの名前に対応するディレクトリです。//my/pkg:my_genrule の場合、//my/pkg:my_genrule の出力がサブディレクトリにある場合でも、常に my/pkg で終わります。

  • @D: 出力ディレクトリ。outs に 1 つのエントリがある場合、そのファイルを含むディレクトリに展開されます。エントリが複数ある場合、すべての出力ファイルが同じサブディレクトリにある場合でも、genfiles ツリー内のパッケージのルート ディレクトリに展開されます。

    注: RULEDIR はセマンティクスが単純で、出力ファイルの数に関係なく同じ動作をするため、@D ではなく RULEDIR を使用してください。

    genrule が一時的な中間ファイルを生成する必要がある場合（コンパイラなどの他のツールを使用した結果など）、それらを一時ファイルに書き込み（/tmp にも書き込めますが）、終了前に削除する必要があります。@D

    特に、入力を含むディレクトリへの書き込みは避けてください。読み取り専用ファイル システムに存在する場合があります。そうでない場合でも、ソースツリーが破棄されます。

事前定義されたソースパス変数/出力パス変数

事前定義変数 execpath、execpaths、rootpath、rootpaths、location、locations は、ラベル パラメータ（$(execpath //foo:bar) など）を受け取り、そのラベルで指定されたファイルパスを置き換えます。

ソースファイルの場合、これはワークスペースのルートからの相対パスです。ルールの出力ファイルの場合、これはファイルの出力パスです（下記の出力ファイルの説明をご覧ください）。

事前定義されたパス変数の例をご覧ください。

  • execpath: Bazel がビルド アクションを実行する execroot の下のパスを示します。

    上記の例では、Bazel はワークスペースのルートにある bazel-myproject シンボリック リンクによってリンクされたディレクトリですべてのビルドアクションを実行します。ソースファイル empty.source はパス bazel-myproject/testapp/empty.source にリンクされています。そのため、実行パス（ルートの下のサブパス）は testapp/empty.source です。これは、ビルドアクションがファイルを検索するために使用できるパスです。

    出力ファイルも同様にステージングされますが、サブパス bazel-out/cpu-compilation_mode/bin（またはツールの出力の場合は bazel-out/cpu-opt-exec-hash/bin）が接頭辞として追加されます。上記の例では、//testapp:app は show_app_output の tools 属性に表示されるため、ツールです。そのため、出力ファイル app は bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app に書き込まれます。したがって、実行パスは bazel-out/cpu-opt-exec-hash/bin/testapp/app です。この追加の接頭辞により、たとえば、同じビルド内の 2 つの異なる CPU に対して同じターゲットをビルドし、結果が互いに上書きされることがなくなります。

    この変数に渡されるラベルは、1 つのファイルを表す必要があります。ソースファイルを表すラベルの場合、これは自動的に true になります。ルールを表すラベルの場合、ルールは 1 つの出力を生成する必要があります。これが false の場合や、ラベルの形式が正しくない場合、ビルドはエラーで失敗します。

  • rootpath: ビルドされたバイナリが、メイン リポジトリに対応する runfiles ディレクトリのサブディレクトリを基準として、実行時に依存関係を見つけるために使用できるパスを指定します。注: これは、 --enable_runfiles が有効な場合にのみ機能します。これは、Windows ではデフォルトで有効になっていません。クロスプラットフォーム サポートには、代わりに rlocationpath を使用してください。

    これは execpath に似ていますが、上記の構成接頭辞が削除されます。上記の例では、empty.source と app の両方が、純粋なワークスペース相対パス（testapp/empty.source と testapp/app）を使用しています。

    外部リポジトリ repo 内のファイルの rootpath は、../repo/ で始まり、その後にリポジトリ相対パスが続きます。

    これは、execpath と同じ「1 つの出力のみ」の要件があります。

  • rlocationpath: ビルドされたバイナリが runfiles ライブラリの Rlocation 関数に渡して、runfiles ディレクトリ（利用可能な場合）または runfiles マニフェストを使用してランタイムで依存関係を検索できるパス。

    これは、構成接頭辞が含まれていないという点で rootpath に似ていますが、常にリポジトリの名前で始まるという点で異なります。上記の例では、 empty.source と app は myproject/testapp/empty.source と myproject/testapp/app というパスになります。

    外部リポジトリ repo 内のファイルの rlocationpath は、repo/ で始まり、その後にリポジトリ相対パスが続きます。

    ランタイムで依存関係を見つけるには、このパスをバイナリに渡し、runfiles ライブラリを使用してファイル システム パスに解決することをおすすめします。rootpath と比較して、すべてのプラットフォームで動作し、runfiles ディレクトリが使用できない場合でも動作するという利点があります。

    これは、execpath と同じ「1 つの出力のみ」の要件があります。

  • location: 展開される属性に応じて、execpath または rootpath のいずれかの類義語。これは Starlark 以前の従来の動作であり、特定のルールに対して何をするかをよく理解している場合を除き、おすすめしません。詳しくは、#2475 をご覧ください。

execpaths、rootpaths、rlocationpaths、locations は、それぞれ execpath、rootpath、rlocationpath、location の複数形のバリエーションです。複数の出力を生成するラベルをサポートしています。この場合、各出力はスペースで区切って一覧表示されます。出力なしのルールと形式が正しくないラベルは、ビルドエラーを生成します。

参照されるラベルはすべて、使用ターゲットの srcs、出力ファイル、または deps に表示する必要があります。そうしないと、ビルドは失敗します。C++ ターゲットは、data のラベルを参照することもできます。

ラベルは正規形式である必要はありません。foo、:foo、//somepkg:foo のいずれでもかまいません。

カスタム変数

カスタム「Make」変数は、「Make 変数の置換の対象」としてマークされている任意の属性で参照できますが、これらの変数を定義する他のターゲットに依存するターゲットでのみ参照できます。

ベスト プラクティスとして、コア Bazel に焼き込む正当な理由がない限り、すべての変数をカスタムにするべきです。これにより、Bazel は、ターゲットが気にしない変数を供給するために、費用のかかる依存関係を読み込む必要がなくなります。

C++ ツールチェーン変数

以下は C++ ツールチェーン ルールで定義され、toolchains = ["@bazel_tools//tools/cpp:current_cc_toolchain"] を設定するすべてのルールで使用できます。java_binary などの一部のルールでは、ルール定義に C++ ツールチェーンが暗黙的に含まれます。これらの変数は自動的に継承されます。

組み込みの C++ ルールは、「コンパイラを実行する」よりもはるかに高度です。*SAN、ThinLTO、モジュールあり/なし、慎重に最適化されたバイナリなど、さまざまなコンパイルモードをサポートし、複数のプラットフォームでテストを高速に実行するために、組み込みルールでは、内部で生成される複数のアクションのそれぞれで、正しい入力、出力、コマンドライン フラグが設定されるようにしています。

これらの変数は、まれなケースで言語の専門家が使用するフォールバック メカニズムです。これらの機能を使用する場合は、まず Bazel デベロッパーにお問い合わせください。

  • ABI: C++ ABI バージョン。
  • AR: crosstool の「ar」コマンド。
  • C_COMPILER: C/C++ コンパイラ ID（llvm など）。

  • CC: C コンパイラ コマンドと C++ コンパイラ コマンド。

    CC_FLAGS は常に CC と組み合わせて使用することを強くおすすめします。ご自身の責任で行っていただく必要があります。

  • CC_FLAGS: C/C++ コンパイラが genrules で使用できるようにするための最小限のフラグセット。特に、CC が複数のアーキテクチャをサポートしている場合に、正しいアーキテクチャを選択するためのフラグが含まれています。
  • DUMPBIN: Microsoft Visual Studio の Microsoft COFF バイナリ ファイル ダンパー（dumpbin.exe）。
  • NM: crosstool の「nm」コマンド。
  • OBJCOPY: C/C++ コンパイラと同じスイートにある objcopy コマンド。
  • STRIP: C/C++ コンパイラと同じスイートにある strip コマンド。

Java ツールチェーン変数

以下は Java ツールチェーン ルールで定義され、toolchains = ["@rules_java//toolchains:current_java_runtime"]（またはホスト ツールチェーン同等の "@rules_java//toolchains:current_host_java_runtime"）を設定するすべてのルールで使用できます。

JDK のツールのほとんどは直接使用しないでください。組み込みの Java ルールでは、インターフェース JAR、ヘッダー インターフェース JAR、高度に最適化された JAR パッケージングとマージの実装など、アップストリーム ツールで表現できるよりもはるかに高度なアプローチで Java のコンパイルとパッケージングが行われます。

これらの変数は、まれなケースで言語の専門家が使用するフォールバック メカニズムです。これらの機能を使用する場合は、まず Bazel デベロッパーにお問い合わせください。

  • JAVA: 「java」コマンド（Java 仮想マシン）。これを回避するには、可能であれば代わりに java_binary ルールを使用します。相対パスを使用できます。java を呼び出す前にディレクトリを変更する必要がある場合は、作業ディレクトリをキャプチャしてから変更する必要があります。
  • JAVABASE: Java ユーティリティを含むベース ディレクトリ。相対パスを使用できます。「bin」サブディレクトリがあります。

Starlark で定義された変数

ルールとツールチェーンの作成者は、TemplateVariableInfo プロバイダを返すことで、完全にカスタムの変数を定義できます。toolchains 属性を介してこれらの値に依存するルールは、値を読み取ることができます。

Starlark で定義された変数の例をご覧ください。