変数を作成する

問題を報告 ソースを表示 Nightly · 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"

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

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

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 the genrule's tools 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: The genrule's outs list. If you have only one output file, you can also use $@.
  • SRCS: The genrule's srcs list (or more precisely: the path names of the files corresponding to labels in the srcs 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 the genfiles or bin tree. For //my/pkg:my_genrule this always ends in my/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 the genfiles tree, even if all output files are in the same subdirectory!

    Note: Use RULEDIR over @D because RULEDIR 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/ で始まり、その後にリポジトリ相対パスが続きます。
    
    
    
      ランタイムで依存関係を見つけるには、このパスをバイナリに渡し、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: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 で定義された変数の例をご覧ください。