「作成」変数は、「変数を作成」の置換の対象としてマークされた属性で使用できる、拡張可能な文字列変数の特別なクラスです。
たとえば、ユーザーが作成したビルド アクションに特定のツールチェーン パスを挿入するために使用できます。
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"
$
を文字列リテラルとして記述するには(つまり、変数の展開を防ぐには)、$$
.
Predefined variables
Predefined "Make" variables can be referenced by any attribute marked as "Subject to 'Make variable' substitution" on any target.
To see the list of these variables and their values for a given set of build options, run
bazel info --show_make_env [build options]
and look at the top output lines with capital letters.
See an example of predefined variables.
Toolchain option variables
COMPILATION_MODE
:fastbuild
,dbg
, oropt
. (more details)
Path variables
-
BINDIR
: The base of the generated binary tree for the target architecture.Note that a different tree may be used for programs that run during the build on the host architecture, to support cross-compiling.
If you want to run a tool from within a
genrule
, the recommended way to get its path is$(execpath toolname)
, where toolname must be listed in thegenrule
'stools
attribute. GENDIR
: The base of the generated code tree for the target architecture.
Machine architecture variables
-
TARGET_CPU
: The target architecture's CPU, e.g.k8
.
Predefined genrule variables
The following are specially available to genrule
's
cmd
attribute and are
generally important for making that attribute work.
See an example of predefined genrule variables.
OUTS
: Thegenrule
'souts
list. If you have only one output file, you can also use$@
.-
SRCS
: Thegenrule
'ssrcs
list (or more precisely: the path names of the files corresponding to labels in thesrcs
list). If you have only one source file, you can also use$<
. -
<
:SRCS
, if it is a single file. Else triggers a build error. -
@
:OUTS
, if it is a single file. Else triggers a build error. -
RULEDIR
: The output directory of the target, that is, the directory corresponding to the name of the package containing the target under thegenfiles
orbin
tree. For//my/pkg:my_genrule
this always ends inmy/pkg
, even if//my/pkg:my_genrule
's outputs are in subdirectories. -
@D
: The output directory. If outs has one entry, this expands to the directory containing that file. If it has multiple entries, this expands to the package's root directory in thegenfiles
tree, even if all output files are in the same subdirectory!Note: Use
RULEDIR
over@D
becauseRULEDIR
has simpler semantics and behaves the same way regardless of the number of output files.If the genrule needs to generate temporary intermediate files (perhaps as a result of using some other tool like a compiler), it should attempt to write them to
@D
(although/tmp
will also be writable) and remove them before finishing.Especially avoid writing to directories containing inputs. They may be on read-only filesystems. Even if not, doing so would trash the source tree.
Note: If the filenames corresponding to the input labels or the output
filenames contain spaces, '
, or other special characters (or your
genrule is part of a Starlark macro which downstream users may invoke on such
files), then $(SRCS)
and $(OUTS)
are not suitable
for interpolation into a command line, as they do not have the semantics that
"${@}"
would in Bash.
One workaround is to convert to a Bash array, with
mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion' $(SRC) genrule_srcs_expansion )
を記述し、その後のコマンドラインでは$(SRCS)
の代わりに"$$\{SRCS[@]}"
を使用します。より堅牢な方法として、代わりに Starlark ルールを記述することもできます。事前定義されたソースパス変数と出力パス変数
事前定義変数
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/
で始まり、その後にリポジトリ相対パスが続きます。実行時に依存関係を見つけるには、このパスをバイナリに渡し、runfile ライブラリを使用してファイル システム パスに解決することをおすすめします。
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:toolchain_type"]
を設定するすべてのルールで使用できます。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 =
["@bazel_tools//tools/jdk:current_java_runtime"]
(またはホスト ツールチェーン同等の "@bazel_tools//tools/jdk:current_host_java_runtime"
)を設定するすべてのルールで使用できます。
JDK のほとんどのツールは直接使用すべきではありません。組み込みの Java ルールでは、インターフェース JAR、ヘッダー インターフェース JAR、高度に最適化された JAR パッケージングとマージの実装など、アップストリーム ツールで表現できるものよりもはるかに高度なアプローチで Java のコンパイルとパッケージングが行われます。
これらの変数は、まれなケースで言語の専門家が使用するフォールバック メカニズムです。これらの機能を使用する場合は、まず Bazel デベロッパーにお問い合わせください。
-
JAVA
: 「java」コマンド(Java 仮想マシン)。これを回避するには、可能であれば代わりにjava_binary
ルールを使用します。相対パスを使用できます。java
を呼び出す前にディレクトリを変更する必要がある場合は、変更する前に作業ディレクトリをキャプチャする必要があります。 JAVABASE
: Java ユーティリティが格納されているベース ディレクトリ。相対パスを使用できます。「bin」サブディレクトリがあります。
Starlark で定義された変数
ルールとツールチェーンの作成者は、TemplateVariableInfo プロバイダを返すことにより、完全なカスタム変数を定義できます。toolchains
属性を介してこれらの値に依存するルールは、値を読み取ることができます。
Starlark で定義された変数の例をご覧ください。