このページでは、bazel build
、bazel run
、bazel test
などのさまざまな Bazel コマンドで使用できるオプションについて説明します。このページは、Bazel を使用したビルドの Bazel のコマンドの一覧表です。
ターゲットの構文
build
や test
などの一部のコマンドは、ターゲットのリストで操作できます。ラベルよりも柔軟な構文を使用します。詳しくは、ビルドするターゲットの指定をご覧ください。
オプション
以降のセクションでは、ビルドで使用できるオプションについて説明します。ヘルプコマンドで --long
を使用すると、オンライン ヘルプ メッセージで、各オプションの意味、タイプ、デフォルト値に関する概要情報を確認できます。
ほとんどのオプションは 1 回だけ指定できます。複数回指定した場合は、最後のインスタンスが優先されます。複数回指定できるオプションは、オンライン ヘルプの「複数回使用できる」に記載されています。
パッケージの場所
--package_path
このオプションは、特定のパッケージの BUILD ファイルを見つけるために検索されるディレクトリのセットを指定します。
Bazel は、パッケージのパスを検索してパッケージを見つけます。これは、コロンで区切られた bazel ディレクトリの順序付きリストで、それぞれが部分的なソースツリーのルートです。
--package_path
オプションを使用してカスタム パッケージ パスを指定するには:
% bazel build --package_path %workspace%:/some/other/root
パッケージパス要素は、次の 3 つの形式で指定できます。
- 最初の文字が
/
の場合、パスは絶対パスになります。 - パスが
%workspace%
で始まる場合、パスは、それを含む最も近い bazel ディレクトリからの相対パスになります。たとえば、作業ディレクトリが/home/bob/clients/bob_client/bazel/foo
の場合、package-path の文字列%workspace%
は/home/bob/clients/bob_client/bazel
に展開されます。 - それ以外は、作業ディレクトリを基準とする相対パスになります。通常、これは意図しているわけではなく、bazel ワークスペースの下のディレクトリから Bazel を使用すると予期しない動作をする可能性もあります。たとえば、package-path 要素
.
を使用して/home/bob/clients/bob_client/bazel/foo
ディレクトリに移動すると、パッケージは/home/bob/clients/bob_client/bazel/foo
ディレクトリから解決されます。
デフォルト以外のパッケージパスを使用する場合は、便宜上 Bazel 構成ファイルでそのパスを指定します。
Bazel では、現在のディレクトリにパッケージが存在する必要はありません。したがって、必要なすべてのパッケージがパッケージパスの別の場所にあれば、空の bazel ワークスペースからビルドできます。
例: 空のクライアントからのビルド
% mkdir -p foo/bazel % cd foo/bazel % touch WORKSPACE % bazel build --package_path /some/other/path //foo
--deleted_packages
このオプションでは、Bazel によって削除済みと見なされ、パッケージパス上のディレクトリからの読み込みを試行しないパッケージのカンマ区切りのリストを指定します。これを使用すると、パッケージを実際に削除せずに削除をシミュレートできます。
確認エラー
Bazel によるエラーチェックや警告を制御します。
--[no]check_visibility
このオプションを false に設定すると、可視性チェックの結果は警告に降格されます。 このオプションのデフォルト値は true であるため、デフォルトでは可視性の確認が行われます。
--output_filter=regex
--output_filter
オプションは、正規表現に一致するターゲットに対してのみ、ビルドとコンパイルの警告を表示します。ターゲットが指定された正規表現と一致せず、実行が成功した場合、その標準出力と標準エラーは破棄されます。
このオプションの一般的な値は次のとおりです。
`--output_filter='^//(first/project|second/project):'` | 指定したパッケージの出力を表示します。 |
`--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'` | 指定したパッケージの出力を表示しません。 |
`--output_filter=` | すべてを表示します。 |
`--output_filter=DONT_MATCH_ANYTHING` | 何も表示しません。 |
ツールフラグ
これらのオプションは、Bazel が他のツールに渡すオプションを制御します。
--copt=cc-option
このオプションは、コンパイラに渡す引数を取ります。 この引数は、C、C++、アセンブラ コードの前処理、コンパイル、アセンブルのためにコンパイラが呼び出されるたびに、コンパイラに渡されます。リンク時に渡されません。
このオプションは複数回使用できます。例:
% bazel build --copt="-g0" --copt="-fpic" //foo
このコードでは、デバッグ テーブルなしで foo
ライブラリがコンパイルされ、位置に依存しないコードが生成されます。
--host_copt=cc-option
このオプションは、ホスト構成でコンパイルされるソースファイルについてコンパイラに渡される引数を取ります。これは --copt
オプションに似ていますが、ホスト構成にのみ適用されます。
--host_conlyopt=cc-option
このオプションは、ホスト構成でコンパイルされる C ソースファイルのコンパイラに渡される引数を取ります。これは --conlyopt
オプションに似ていますが、ホスト構成にのみ適用されます。
--host_cxxopt=cc-option
このオプションは、ホスト構成でコンパイルされる C++ ソースファイルのコンパイラに渡される引数を取ります。これは --cxxopt
オプションに似ていますが、ホスト構成にのみ適用されます。
--host_linkopt=linker-option
このオプションは、ホスト構成でコンパイルされるソースファイルのリンカーに渡す引数を取ります。これは --linkopt
オプションに似ていますが、ホスト構成にのみ適用されます。
--conlyopt=cc-option
このオプションは、C ソースファイルのコンパイル時にコンパイラに渡される引数を受け取ります。
これは --copt
に似ていますが、C コンパイルにのみ適用され、C++ のコンパイルまたはリンクには適用されません。そのため、--conlyopt
を使用して C 固有のオプション(-Wno-pointer-sign
など)を渡すことができます。
--cxxopt=cc-option
このオプションは、C++ ソースファイルのコンパイル時にコンパイラに渡される引数を受け取ります。
これは --copt
に似ていますが、C++ コンパイルにのみ適用され、C コンパイルまたはリンクには適用されません。そのため、--cxxopt
を使用して C++ 固有のオプション(-fpermissive
や -fno-implicit-templates
など)を渡すことができます。
例:
% bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code
--linkopt=linker-option
このオプションは、リンク時にコンパイラに渡される引数を受け取ります。
これは --copt
と似ていますが、リンクにのみ適用され、コンパイルには適用されません。そのため、--linkopt
を使用して、リンク時にのみ有効なコンパイラ オプション(-lssp
や -Wl,--wrap,abort
など)を渡すことができます。例:
% bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code
ビルドルールでは、属性にリンク オプションを指定することもできます。このオプションの設定が常に優先されます。cc_library.linkopts もご覧ください。
--strip (always|never|sometimes)
このオプションは、-Wl,--strip-debug
オプションを指定してリンカーを呼び出すことで、Bazel がすべてのバイナリと共有ライブラリからデバッグ情報を削除するかどうかを決定します。
--strip=always
は、デバッグ情報を常に削除することを意味します。
--strip=never
は、デバッグ情報を削除しないことを意味します。
--compilation_mode
が fastbuild
の場合、デフォルト値の --strip=sometimes
は除去されます。
% bazel build --strip=always //foo:bar
はターゲットをコンパイルし、生成されたすべてのバイナリからデバッグ情報を削除します。
Bazel の --strip
オプションは、ld の --strip-debug
オプションに対応しています。デバッグ情報のみを削除します。なんらかの理由で、デバッグ シンボルだけでなくすべてのシンボルを削除する必要がある場合は、ld の --strip-all
オプションを使用する必要があります。--linkopt=-Wl,--strip-all
を Bazel に渡すことで実行できます。また、Bazel の --strip
フラグを設定すると --linkopt=-Wl,--strip-all
がオーバーライドされるため、どちらか一方だけを設定してください。
単一のバイナリのみをビルドする場合に、すべてのシンボルを除去したい場合は、--stripopt=--strip-all
を渡してターゲットの //foo:bar.stripped
バージョンを明示的にビルドすることもできます。--stripopt
のセクションで説明したように、これはビルドのすべてのリンク アクションに除去を含めるのではなく、最終バイナリがリンクされた後に除去アクションを適用します。
--stripopt=strip-option
これは、*.stripped
バイナリの生成時に strip
コマンドに渡す追加のオプションです。デフォルトは -S -p
です。このオプションは複数回使用できます。
--fdo_instrument=profile-output-dir
--fdo_instrument
オプションを使用すると、ビルドされた C/C++ バイナリの実行時に、FDO(フィードバック指向最適化)プロファイル出力を生成できます。GCC の場合、指定した引数は、各 .o ファイルのプロファイル情報を含む .gcda ファイルのオブジェクトごとのファイル ディレクトリ ツリーのディレクトリ接頭辞として使用されます。
プロファイル データツリーが生成されたら、プロファイル ツリーを圧縮して --fdo_optimize=profile-zip
Bazel オプションに提供し、FDO 向けに最適化されたコンパイルを有効にします。
LLVM コンパイラの場合、引数は未加工の LLVM プロファイル データファイルがダンプされるディレクトリにもなります。例: --fdo_instrument=/path/to/rawprof/dir/
。
オプション --fdo_instrument
と --fdo_optimize
を同時に使用することはできません。
--fdo_optimize=profile-zip
--fdo_optimize
オプションを使用すると、オブジェクトごとのファイル プロファイル情報を使用して、コンパイル時に FDO(フィードバック指向最適化)の最適化を実行できます。GCC の場合、各 .o ファイルのプロファイル情報を含む、以前に生成された .gcda ファイルのファイルツリーを含む zip ファイルが提供されます。
または、指定された引数で、拡張子 .afdo によって識別される自動プロファイルを指定することもできます。
LLVM コンパイラの場合、提供される引数は、llvm-profdata ツールによって準備されたインデックス登録済みの LLVM プロファイル出力ファイルを指し、拡張子は .profdata である必要があります。
オプション --fdo_instrument
と --fdo_optimize
を同時に使用することはできません。
--[no]output_symbol_counts
有効にすると、C++ 実行バイナリのゴールドによって呼び出された各リンクが、(--print-symbol-counts
ゴールド オプションを介して)シンボル数ファイルを出力します。リンカー入力ごとに、定義されたシンボルの数とバイナリで使用されたシンボルの数が記録されます。この情報を使用して、不要なリンクの依存関係を追跡できます。シンボル カウント ファイルは、[targetname].sc
という名前でバイナリの出力パスに書き込まれます。
このオプションはデフォルトでは無効になっています。
--java_language_version=version
このオプションは、Java ソースのバージョンを指定します。例:
% bazel build --java_language_version=8 java/com/example/common/foo:all
Java 8 仕様と互換性のあるコンストラクトのみを許可します。デフォルト値は 11 です。-->
有効な値は 8、9、10、11、14、15 です。default_java_toolchain
を使用してカスタム Java ツールチェーンを登録することで拡張できます。
--tool_java_language_version=version
ビルド時に実行されるツールのビルドに使用される Java 言語バージョン。デフォルト値は 11 です。
--java_runtime_version=version
このオプションでは、コードの実行とテストの実行に使用する JVM のバージョンを指定します。次に例を示します。
% bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application
リモート リポジトリから JDK 11 をダウンロードし、それを使用して Java アプリケーションを実行します。
デフォルト値は localjdk
です。有効な値は localjdk
、localjdk_version
、remotejdk_11
、remote_jdk17
です。local_java_repository
または remote_java_repostory
リポジトリ ルールを使用してカスタム JVM を登録することで、値を拡張できます。
--tool_java_runtime_version=version
ビルドで必要なツールの実行に使用される JVM のバージョン。デフォルト値は remotejdk_11
です。
--jvmopt=jvm-option
このオプションを使用すると、オプション引数を Java VM に渡すことができます。1 つの大きな引数とともに使用することも、個々の引数と複数回使用することもできます。例:
% bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all
すべての Java バイナリの起動にサーバー VM を使用し、VM の起動ヒープサイズを 256 MB に設定します。
--javacopt=javac-option
このオプションを使用すると、オプションの引数を javac に渡すことができます。1 つの大きな引数とともに使用することも、個々の引数と複数回使用することもできます。例:
% bazel build --javacopt="-g:source,lines" //myprojects:prog
上記のコマンドは、(bazel のデフォルトではなく)javac のデフォルトのデバッグ情報を使用して java_binary を再ビルドします。
このオプションは、javac の Bazel 組み込みデフォルト オプションの後で、ルールごとのオプションの前に javac に渡されます。javac の最後のオプションの指定が優先されます。javac のデフォルト オプションは次のとおりです。
-source 8 -target 8 -encoding UTF-8
--strict_java_deps (default|strict|off|warn|error)
このオプションは、javac が直接的な依存関係の欠落をチェックするかどうかを制御します。 Java ターゲットは、直接使用するすべてのターゲットを依存関係として明示的に宣言する必要があります。このフラグは、各 Java ファイルの型チェックに実際に使用される JAR を判別するよう javac に指示します。現在のターゲットの直接的な依存関係の出力でない場合は、警告またはエラーを表示します。
off
はチェックが無効になっていることを示します。warn
は、直接依存関係がないそれぞれに対して javac が[strict]
型の標準 Java 警告を生成することを意味します。default
、strict
、error
はいずれも、javac が警告ではなくエラーを生成することを意味します。そのため、不足している直接的な依存関係が見つかると、現在のターゲットはビルドに失敗します。これは、フラグが指定されていない場合のデフォルトの動作でもあります。
セマンティクスを構築する
これらのオプションは、ビルドコマンドや出力ファイルの内容に影響します。
--compilation_mode (fastbuild|opt|dbg)
(-c)
--compilation_mode
オプション(多くの場合、-c
、特に -c opt
と短縮されます)は、fastbuild
、dbg
、または opt
の引数を取り、さまざまな C/C++ コード生成オプション(最適化レベルやデバッグ テーブルの完全性など)に影響します。Bazel はコンパイル モードごとに異なる出力ディレクトリを使用するため、毎回のフル再ビルドを行うことなくモードを切り替えることができます。
fastbuild
は、[できるだけ早くビルド] を指定します。最小限のデバッグ情報(-gmlt -Wl,-S
)を生成し、最適化は行いません。これがデフォルトです。注:-DNDEBUG
は設定されません。dbg
は、デバッグを有効にしてビルドする(-g
)ことを意味します。これにより、gdb(または別のデバッガ)を使用できます。opt
は、最適化を有効にしてassert()
呼び出しを無効にしたビルド(-O2 -DNDEBUG
)を意味します。--copt -g
も渡さない限り、opt
モードではデバッグ情報は生成されません。
--cpu=cpu
このオプションでは、ビルド中のバイナリのコンパイルに使用されるターゲット CPU アーキテクチャを指定します。
--action_env=VAR=VALUE
すべてのアクションの実行中に使用できる環境変数のセットを指定します。変数は名前で指定できます。その場合、値は呼び出し環境から取得されます。または、呼び出し環境とは無関係に値を設定する name=value
ペアで指定することもできます。
この --action_env
フラグは複数回指定できます。複数の --action_env
フラグで同じ変数に値が割り当てられている場合は、最新の割り当てが優先されます。
--experimental_action_listener=label
experimental_action_listener
オプションは、label で指定された action_listener
ルールの詳細を使用して extra_actions
をビルドグラフに挿入するように Bazel に指示します。
--[no]experimental_extra_action_top_level_only
このオプションを true に設定すると、 --experimental_action_listener
コマンドライン オプションで指定された追加のアクションは、最上位のターゲットに対してのみスケジュールされます。
--experimental_extra_action_filter=regex
experimental_extra_action_filter
オプションは、extra_actions
をスケジュールするターゲットのセットをフィルタするように Bazel に指示します。
このフラグは、--experimental_action_listener
フラグと組み合わせた場合にのみ適用できます。
デフォルトでは、ビルド対象をリクエストしたターゲットの推移的クローズに含まれるすべての extra_actions
が、実行のスケジュールを取得します。--experimental_extra_action_filter
は、スケジュールを、オーナーのラベルが指定された正規表現に一致する extra_actions
に制限します。
次の例では、extra_actions
のスケジュール設定を、オーナーのラベルに「/bar/」が含まれるアクションにのみ適用するように制限します。
% bazel build --experimental_action_listener=//test:al //foo/... \ --experimental_extra_action_filter=.*/bar/.*
--host_cpu=cpu
このオプションは、ホストツールのビルドに使用する CPU アーキテクチャの名前を指定します。
--fat_apk_cpu=cpu[,cpu]*
android_binary
ルールの推移的 deps
で C/C++ ライブラリをビルドするための CPU。他の C/C++ ルールには影響しません。たとえば、android_binary
ルールと cc_binary
ルールの推移的な deps
に cc_library
がある場合、cc_library
は少なくとも 2 回ビルドされます(android_binary
ルールで --fat_apk_cpu
で指定された CPU ごとに 1 回、cc_binary
ルールで --cpu
で指定された CPU に 1 回)。
デフォルト値は armeabi-v7a
です。
--fat_apk_cpu
で指定された CPU ごとに 1 つの .so
ファイルが作成され、APK にパッケージ化されます。.so
ファイルの名前には、android_binary
ルールの名前の先頭に「lib」が付加されています。たとえば、android_binary
の名前が「foo」の場合、ファイルは libfoo.so
です。
--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...
存在する場合、包含正規表現のいずれかに一致し、除外式のいずれにも一致しないラベルまたは実行パスを持つ C++ ファイルは、指定されたオプションでビルドされます。ラベルの照合では、ラベルの正規形式(例: //package
:label_name
)が使用されます。
実行パスは、C++ ファイルのベース名(拡張子を含む)を含むワークスペース ディレクトリへの相対パスです。また、プラットフォームに依存する接頭辞も含まれます。
生成されたファイル(genrule 出力など)と一致させるために、Bazel では実行パスのみを使用できます。この場合、実行パスと一致しない、正規表現の先頭を「//」にしないでください。パッケージ名は --per_file_copt=base/.*\.pb\.cc@-g0
のように使用できます。これは、base
というディレクトリにあるすべての .pb.cc
ファイルと一致します。
このオプションは複数回使用できます。
このオプションは、使用するコンパイル モードに関係なく適用されます。たとえば、--compilation_mode=opt
を使用してコンパイルし、より強力な最適化または最適化を無効にして一部のファイルを選択的にコンパイルできます。
注意: 一部のファイルがデバッグ シンボルで選択的にコンパイルされている場合、リンク時にシンボルが削除されることがあります。これを防ぐには、--strip=never
を設定します。
構文: [+-]regex[,[+-]regex]...@option[,option]...
。ここで、regex
は正規表現で、包含パターンを識別する場合は +
を、除外パターンを識別する場合は -
を付けます。option
は C++ コンパイラに渡される任意のオプションを表します。オプションに ,
が含まれる場合は、\,
のように引用符で囲む必要があります。正規表現をオプションと区切るために最初の @
のみが使用されるため、オプションに @
を含めることもできます。
例: --per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs
は、//foo/
内のすべての .cc
ファイル(file.cc
を除く)について、C++ コンパイラのコマンドラインに -O0
オプションと -fprofile-arcs
オプションを追加します。
--dynamic_mode=mode
ビルドルールの linkstatic 属性とやり取りして、C++ バイナリを動的にリンクするかどうかを決定します。
モード:
auto
: プラットフォーム依存モードに変換されます。Linux の場合はdefault
、cygwin の場合はoff
です。default
: bazel が動的にリンクするかどうかを選択できます。 詳細については、linkstatic をご覧ください。fully
: すべてのターゲットを動的にリンクします。これにより、リンク時間を短縮し、生成されるバイナリのサイズを削減できます。off
: すべてのターゲットをほぼ静的モードでリンクします。linkopts で-static
が設定されている場合、ターゲットは完全に静的なものに変更されます。
--fission (yes|no|[dbg][,opt][,fastbuild])
Fission を有効にします。Fission は、C++ デバッグ情報を .o ファイルではなく専用の .dwo ファイルに書き込みます。これにより、リンクの入力サイズが大幅に削減され、リンク時間を短縮できます。
[dbg][,opt][,fastbuild]
(例: --fission=dbg,fastbuild
)に設定すると、指定されたコンパイル モードセットに対してのみ、Fission が有効になります。これは bazelrc の設定に役立ちます。yes
に設定すると、Fission が普遍的に有効になります。no
に設定した場合、Fission は普遍的に無効になります。デフォルトは no
です。
--force_ignore_dash_static
このフラグが設定されている場合、cc_*
ルールの BUILD ファイルの linkopt にある -static
オプションは無視されます。これは、C++ ビルド強化の回避策としてのみ意図されています。
--[no]force_pic
有効にすると、すべての C++ コンパイルは位置非依存コード(-fPIC)を生成し、リンクは非 PIC ライブラリよりも PIC ビルド済みライブラリを優先し、リンクは位置独立実行ファイル(-pie)を生成します。デフォルトは無効になっています。
--android_resource_shrinking
android_binary ルールのリソース圧縮を実行するかどうかを選択します。android_binary ルールで s links_resources 属性のデフォルトを設定します。詳細については、そのルールのドキュメントをご覧ください。デフォルトはオフです。
--custom_malloc=malloc-library-target
指定する場合は、常に特定の malloc 実装を使用し、(malloc
を指定しないで)デフォルトを使用するターゲットを含む、すべての malloc="target"
属性をオーバーライドします。
--crosstool_top=label
このオプションでは、ビルド時のすべての C++ コンパイルに使用するクロスツール コンパイラ スイートの場所を指定します。Bazel は、この場所で CROSSTOOL ファイルを探し、それを使用して --compiler
の設定を自動的に決定します。
--host_crosstool_top=label
指定しない場合、Bazel は --crosstool_top
の値を使用して、ホスト構成内のコード(ビルド時に実行されるツールなど)をコンパイルします。このフラグの主な目的は、クロスコンパイルを有効にすることです。
--apple_crosstool_top=label
objc*、ios*、apple* ルールの推移的な deps
で C/C++ ルールをコンパイルするために使用するクロスツール。そのようなターゲットでは、このフラグによって --crosstool_top
が上書きされます。
--android_crosstool_top=label
android_binary
ルールの推移的 deps
で C/C++ ルールをコンパイルするために使用するクロスツール。これは、ビルドの他のターゲットに別のクロスツールが必要な場合に役立ちます。デフォルトでは、WORKSPACE ファイルの android_ndk_repository
ルールによって生成されたクロスツールを使用します。関連情報: --fat_apk_cpu
.
--compiler=version
このオプションでは、ビルド時にバイナリのコンパイルに使用する C/C++ コンパイラ バージョン(gcc-4.1.0
など)を指定します。カスタムのクロスツールでビルドする場合は、このフラグを指定する代わりに、CROSSTOOL ファイルを使用する必要があります。
--android_sdk=label
このオプションでは、Android 関連ルールのビルドに使用される Android SDK/プラットフォーム ツールチェーンと Android ランタイム ライブラリを指定します。
WORKSPACE ファイルで android_sdk_repository
ルールが定義されている場合は、Android SDK が自動的に選択されます。
--java_toolchain=label
このオプションでは、Java ソースファイルのコンパイルに使用する java_chain のラベルを指定します。
--host_java_toolchain=label
指定しなかった場合、bazel は --java_toolchain
の値を使用して、ホスト構成内のコード(ビルド時に実行されるツールなど)をコンパイルします。このフラグの主な目的は、クロスコンパイルを有効にすることです。
--javabase=(label)
このオプションは、ベース Java インストールのラベルを設定します。ラベルは、bazel run、bazel test、java_binary
および java_test
ルールによってビルドされた Java バイナリに使用されます。JAVABASE
と JAVA
の「Make」変数は、このオプションから派生します。
--host_javabase=label
このオプションでは、ホスト構成で使用する Java 基本インストールのラベルを設定します(たとえば、JavaBuilder や Singlejar などのホストビルド ツールの場合)。
Java ソースファイルのコンパイルに使用される Java コンパイラは選択されません。コンパイラは、--java_toolchain
オプションを設定することで選択できます。
実行戦略
これらのオプションは、Bazel によるビルドの実行方法に影響します。 ビルドによって生成された出力ファイルには大きな影響はありません。通常、主な影響はビルドの速度に影響します。
--spawn_strategy=strategy
このオプションでは、コマンドの実行場所と方法を制御します。
standalone
を指定すると、コマンドがローカル サブプロセスとして実行されます。この値は非推奨になりました。代わりにlocal
を使用してください。sandboxed
を指定すると、ローカルマシンのサンドボックス内でコマンドが実行されます。そのためには、すべての入力ファイル、データ依存関係、ツールを、srcs
、data
、tools
属性に直接依存関係としてリストする必要があります。サンドボックス化された実行をサポートするシステムでは、Bazel はデフォルトでローカル サンドボックスを有効にします。local
を指定すると、コマンドがローカル サブプロセスとして実行されます。worker
を指定すると、永続ワーカー(使用可能な場合)を使用してコマンドが実行されます。docker
を指定すると、ローカルマシンの Docker サンドボックス内でコマンドが実行されます。そのためには、Docker がインストールされている必要があります。remote
を指定すると、コマンドがリモートで実行されます。これは、リモート エグゼキュータが個別に構成されている場合にのみ使用できます。
--strategy mnemonic=strategy
このオプションは、コマンドの実行場所と方法を制御し、--spawn_strategy(および --genrule_strategy をニーモニック Genrule で)オーバーライドします。サポートされている戦略とその効果については、--spawn_strategy をご覧ください。
--strategy_regexp=<filter,filter,...>=<strategy>
このオプションでは、説明が特定の regex_filter
に一致するコマンドを実行する際に使用する戦略を指定します。regex_filter マッチングの詳細については、--per_file_copt をご覧ください。サポートされている戦略とその効果については、--spawn_strategy をご覧ください。
説明に一致する最後の regex_filter
が使用されます。このオプションは、戦略を指定する他のフラグをオーバーライドします。
- 例:
--strategy_regexp=//foo.*\\.cc,-//foo/bar=local
は、説明が //foo.*.cc に一致し、//foo/bar には一致しない場合に、local
戦略を使用してアクションを実行することを意味します。 - 例:
--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed
「//foo/bar/baz」のコンパイルはsandboxed
戦略ですが、順序を逆にするとlocal
で実行されます。 - 例:
--strategy_regexp='Compiling.*/bar=local,sandboxed'
はlocal
戦略を使用して「//foo/bar/baz のコンパイル」を実行し、失敗した場合はsandboxed
にフォールバックします。
--genrule_strategy=strategy
これは --strategy=Genrule=strategy
の非推奨の省略形です。
--jobs=n
(-j)
このオプションは整数の引数を受け取り、ビルドの実行フェーズで同時に実行するジョブ数の上限を指定します。
--progress_report_interval=n
Bazel は、まだ完了していないジョブ(長時間実行テストなど)について進行状況レポートを定期的に出力します。このオプションはレポートの頻度を設定します。進行状況は n
秒ごとに出力されます。
デフォルトは 0 で、これは増分アルゴリズムを意味します。つまり、最初のレポートは 10 秒後に出力され、その後 30 秒後に出力され、その後は進行状況が 1 分ごとに報告されます。
bazel が --curses
で指定されたカーソル コントロールを使用している場合、進行状況が 1 秒ごとに報告されます。
--local_{ram,cpu}_resources resources or resource expression
これらのオプションでは、ビルドとテストのアクティビティをローカルで実行するようにスケジュールするときに Bazel が考慮できるローカル リソースの量(MB 単位の RAM、CPU 論理コア数)を指定します。整数か、キーワード(HOST_RAM または HOST_CPUS)を受け取ります。また、オプションで [-|*
float]
(例: --local_cpu_resources=2
、--local_ram_resources=HOST_RAM*.5
、--local_cpu_resources=HOST_CPUS-1
)が続きます。フラグは独立しています。いずれかまたは両方を設定できます。デフォルトでは、Bazel はローカル システムの構成から直接 RAM 容量と CPU コア数を推定します。
--[no]build_runfile_links
このオプションはデフォルトで有効になっており、テストとバイナリの runfiles シンボリック リンクを出力ディレクトリにビルドするかどうかを指定します。--nobuild_runfile_links
を使用すると、runfile ツリーのビルドでオーバーヘッドを発生させることなく、すべてのターゲットがコンパイルされるかどうかを検証できます。
テスト(またはアプリケーション)が実行されると、実行時のデータ依存関係が 1 か所に集められます。通常、この「runfile」ツリーは、Bazel の出力ツリーで、対応するバイナリまたはテストの兄弟ノードとしてルート化されます。テスト実行中、runfile には $TEST_SRCDIR/workspace/packagename/filename
形式のパスを使用してアクセスできます。runfiles ツリーにより、テストで依存関係が宣言されているすべてのファイルにテストからアクセスできるようになります。デフォルトでは、必要なファイルへのシンボリック リンクのセットを作成することで、runfiles ツリーが実装されます。リンクのセットが大きくなると、この処理のコストも増加し、特に個々のテスト(またはアプリケーション)に独自の runfiles ツリーが必要になるため、一部の大規模なビルドでは全体のビルド時間が大幅に長くなる可能性があります。
--[no]build_runfile_manifests
このオプションはデフォルトで有効になっており、runfile マニフェストを出力ツリーに書き込むかどうかを指定します。無効にすると、--nobuild_runfile_links
が含まれます。
runfile ツリーはメモリ内マニフェストからリモートで作成されるため、リモートでテストを実行する場合は無効にできます。
--[no]discard_analysis_cache
このオプションを有効にすると、Bazel は実行直前に分析キャッシュを破棄し、実行フェーズ用に追加のメモリ(約 10%)を解放します。欠点は、それ以降の増分ビルドが遅くなることです。メモリ節約モードもご覧ください。
--[no]keep_going
(-k)
GNU Make と同様に、最初のエラーが発生するとビルドの実行フェーズが停止します。エラーが発生した場合でも、できる限りビルドしてみることが有用な場合があります。このオプションを使用すると、この動作が有効になります。指定すると、ビルドは前提条件が正常にビルドされたすべてのターゲットのビルドを試みますが、エラーを無視します。
このオプションは通常、ビルドの実行フェーズに関連付けられますが、分析フェーズにも影響します。ビルドコマンドで複数のターゲットが指定されていて、一部のターゲットしか正常に分析できない場合、--keep_going
が指定されていなければ、ビルドはエラーで停止します。その場合、ビルドは実行フェーズに進みますが、分析に成功したターゲットのみが対象となります。
--[no]use_ijars
このオプションは、Bazel による java_library
ターゲットのコンパイル方法を変更します。依存する java_library
ターゲットをコンパイルするために java_library
の出力を使用する代わりに、Bazel は非非公開メンバー(パブリック、保護、デフォルト(パッケージ)の各アクセスメソッドとフィールド)の署名のみを含むインターフェース JAR を作成し、インターフェース JAR を使用して依存ターゲットをコンパイルします。これにより、メソッド本体またはクラスのプライベート メンバーのみに対して変更が行われた場合に、再コンパイルを回避できます。
--[no]interface_shared_objects
このオプションを使用すると、インターフェース共有オブジェクトが有効になります。そのため、バイナリやその他の共有ライブラリは、共有オブジェクトの実装ではなくインターフェースに依存するようになります。実装のみを変更した場合、Bazel は、変更された共有ライブラリに不必要に依存するターゲットを再ビルドせずに済みます。
出力の選択
これらのオプションにより、ビルドまたはテストの対象が決まります。
--[no]build
このオプションを使用すると、ビルドの実行フェーズが発生します。デフォルトでオンになっています。オフにすると、実行フェーズはスキップされ、最初の 2 つのフェーズ(読み込みと分析)のみが発生します。
このオプションは、実際に何もビルドすることなく、BUILD ファイルを検証し、入力内のエラーを検出する場合に役立ちます。
--[no]build_tests_only
指定すると、Bazel はサイズ、タイムアウト、タグ、言語が原因でフィルタリングされなかった *_test
ルールと test_suite
ルールの実行に必要なものだけをビルドします。指定すると、Bazel はコマンドラインで指定された他のターゲットを無視します。
デフォルトでは、このオプションは無効になっています。Bazel は、テストから除外された *_test
ルールや test_suite
ルールなど、リクエストされたものをすべてビルドします。これは、bazel test --build_tests_only foo/...
を実行しても foo
ツリー内のすべてのビルド破損が検出されるとは限らないため、便利です。
--[no]check_up_to_date
このオプションを使用すると、Bazel はビルドを実行せず、指定されたすべてのターゲットが最新かどうかをチェックするだけです。正常に完了している場合、ビルドは通常どおり正常に完了します。ただし、ファイルがビルドされるのではなく古い場合、エラーが報告され、ビルドが失敗します。このオプションは、ビルドのコストを発生させずに、ビルドがソース編集よりも最近実行されたかどうかを判断する際に有用です(送信前チェックなど)。
--check_tests_up_to_date
もご覧ください。
--[no]compile_one_dependency
引数ファイルの単一の依存関係をコンパイルします。これは、IDE でソースファイルの構文チェックを行う場合に便利です。たとえば、編集/ビルド/テストのサイクルの中のできるだけ早くエラーを検出するために、ソースファイルに依存する単一のターゲットを再ビルドします。この引数は、フラグ以外のすべての引数の解釈方法に影響します。各引数は、ファイル ターゲット ラベル、または現在の作業ディレクトリに関連するプレーンなファイル名である必要があります。また、各ソースファイル名に依存する 1 つのルールがビルドされます。対象
C++ ソースと Java ソースの場合、同じ言語空間のルールが優先的に選択されます。同じ設定を持つ複数のルールについては、BUILD ファイルで最初に記述されているルールが選択されます。明示的に指定されたターゲット パターンがソースファイルを参照しない場合は、エラーが発生します。
--save_temps
--save_temps
オプションを指定すると、コンパイラからの一時的な出力が保存されます。これには、.s ファイル(アセンブラ コード)、.i(前処理された C)、.ii(前処理された C++)ファイルが含まれます。多くの場合、これらの出力はデバッグに役立ちます。一時は、コマンドラインで指定された一連のターゲットに対してのみ生成されます。
現在、--save_temps
フラグは cc_* ルールでのみ機能します。
Bazel が追加の出力ファイルの場所を出力するようにするには、--show_result n
の設定が十分大きいことを確認します。
--build_tag_filters=tag[,tag]*
指定すると、Bazel は 1 つ以上の必須タグ(指定されている場合)を持ち、除外されたタグを含まないターゲットのみをビルドします。ビルドタグ フィルタは、タグキーワードのカンマ区切りのリストとして指定します。必要に応じて、除外するタグを示すために「-」記号をその前に付けます。必須タグの前に「+」記号を付けておくこともできます。
テストの実行時に、Bazel はテスト ターゲットの --build_tag_filters
を無視します。このテスト ターゲットは、このフィルタと一致していなくてもビルドおよび実行されます。ビルドを回避するには、--test_tag_filters
を使用するか、ターゲットを明示的に除外して、テスト ターゲットをフィルタリングします。
--test_size_filters=size[,size]*
指定すると、Bazel は指定されたサイズのテスト ターゲットのみをテストします(--build_tests_only
も指定されている場合はビルドします)。テストサイズ フィルタは、許可されるテストサイズ値(小、中、大、大)のカンマ区切りのリストとして指定します。除外するテストサイズを示すために「-」記号を先頭に付けることもできます。たとえば
% bazel test --test_size_filters=small,medium //foo:all
このように
% bazel test --test_size_filters=-large,-enormous //foo:all
//foo 内の小規模および中規模のテストのみをテストします。
デフォルトでは、テストサイズのフィルタリングは適用されません。
--test_timeout_filters=timeout[,timeout]*
指定すると、Bazel は指定されたタイムアウト時間のテスト ターゲットのみをテスト(--build_tests_only
も指定されている場合はビルド)します。テスト タイムアウト フィルタは、許可されるテスト タイムアウト値のカンマ区切りリスト(short、moderate、long、eternal)として指定します。テスト タイムアウトの除外を示す「-」記号をその前に付けることもできます。構文の例については、--test_size_filters をご覧ください。
デフォルトでは、テスト タイムアウト フィルタリングは適用されません。
--test_tag_filters=tag[,tag]*
指定すると、Bazel は 1 つ以上の必須タグ(指定されている場合)を持ち、除外されたタグを含まないテスト ターゲットのみをテスト(--build_tests_only
も指定されている場合はビルド)します。テストタグフィルタは、タグキーワードのカンマ区切りのリストとして指定します。必要に応じて、除外するタグを示すために「-」記号をその前に付けます。必須タグの前に「+」記号を付けておくこともできます。
たとえば
% bazel test --test_tag_filters=performance,stress,-flaky //myproject:all
performance
タグまたは stress
タグのいずれかがタグ付けされているものの、flaky
タグがタグ付けされていないターゲットをテストします。
デフォルトでは、テストタグのフィルタリングは適用されません。この方法でテストの size
タグと local
タグでフィルタリングすることもできます。
--test_lang_filters=lang[,lang]*
公式の *_test
ルールがある言語のテスト言語のカンマ区切りリストを指定します(これらの完全なリストについては、ビルド百科事典をご覧ください)。必要に応じて各言語の前に「-」を付けることで、除外する言語を指定できます。各言語に使用する名前は、*_test
ルールの言語接頭辞と同じにする必要があります(例: cc
、java
、sh
)。
指定すると、Bazel は指定された言語のテスト ターゲットのみをテスト(--build_tests_only
も指定されている場合はビルド)します。
たとえば
% bazel test --test_lang_filters=cc,java foo/...
foo/...
で C/C++ テストと Java テスト(それぞれ cc_test
ルールと java_test
ルールを使用して定義)のみをテストしますが、
% bazel test --test_lang_filters=-sh,-java foo/...
sh_test
テストと java_test
テストを除くすべてのテストを foo/...
で実行します。
デフォルトでは、テスト言語によるフィルタリングは適用されません。
--test_filter=filter-expression
実行するテストのサブセットをテストランナーが選択するために使用するフィルタを指定します。呼び出しで指定されたすべてのターゲットがビルドされますが、式によっては、一部のターゲットしか実行されないことがあります。場合によっては、特定のテストメソッドのみが実行されることもあります。
filter-expression の特定の解釈は、テストを実行するテスト フレームワークによって異なります。glob、部分文字列、regexp を使用できます。--test_filter
は、さまざまな --test_arg
フィルタ引数を渡す場合に便利ですが、すべてのフレームワークでサポートされているわけではありません。
読み上げの詳細設定
これらのオプションでは、ターミナルまたは追加のログファイルに対して Bazel の出力の詳細度を制御します。
--explain=logfile
このオプションにはファイル名の引数が必要です。このオプションでは、bazel build
の実行フェーズの依存関係チェッカーにより、ビルドステップごとに、実行される理由または最新の状態であることが示されます。説明は logfile に書き込まれます。
予期しない再ビルドが発生した場合、このオプションは理由を知るのに役立ちます。これを .bazelrc
に追加して、後続のすべてのビルドでロギングが行われるようにします。その後、実行ステップが予期せず実行された場合にログを調べます。このオプションを使用すると、パフォーマンスが低下する可能性があるため、不要になった場合は削除することをおすすめします。
--verbose_explanations
このオプションにより、--explain オプションが有効なときに生成される説明の詳細度が上がります。
特に、詳細説明が有効になっている場合、ビルドに使用されるコマンドが変更されたために出力ファイルが再作成されると、説明ファイルの出力には新しいコマンドの詳細が含まれます(少なくともほとんどのコマンドの場合)。
このオプションを使用すると、生成される説明ファイルの長さが大幅に増加し、--explain
を使用した場合のパフォーマンスが低下する可能性があります。
--explain
が有効になっていない場合、--verbose_explanations
は無視されます。
--profile=file
このオプションはファイル名の引数を受け取り、Bazel はプロファイリング データをファイルに書き込みます。データは、bazel analyze-profile
コマンドを使用して分析または解析できます。ビルド プロファイルは、Bazel の build
コマンドが時間を費やしている場所を把握するのに役立ちます。
--[no]show_loading_progress
このオプションを使用すると、Bazel はパッケージ読み込みの進行状況メッセージを出力します。無効になっている場合、メッセージは表示されません。
--[no]show_progress
このオプションを指定すると、進行状況のメッセージが表示されます。デフォルトではオンになっています。無効にすると、進行状況に関するメッセージが非表示になります。
--show_progress_rate_limit=n
このオプションを使用すると、bazel は n
秒ごとに最大 1 つの進行状況メッセージを表示します(n は実数)。このオプションのデフォルト値は 0.02 です。つまり、bazel は進行状況メッセージを 0.02 秒ごとに 1 つに制限します。
--show_result=n
このオプションは、bazel build
コマンドの最後に結果情報を出力するかどうかを制御します。デフォルトでは、単一のビルド ターゲットが指定されている場合、Bazel はターゲットが正常に更新されたかどうかを示すメッセージと、ターゲットが作成した出力ファイルのリストを出力します。複数のターゲットを指定した場合、結果情報は表示されません。
結果情報は、単一のターゲットまたは少数のターゲットのビルドでは有用な場合がありますが、大規模なビルド(トップレベル プロジェクト ツリー全体など)では、この情報が負担が大きく気を散らす可能性があるため、このオプションを使用すると、制御が可能になります。--show_result
は整数の引数を取ります。これは完全な結果情報を出力するターゲットの最大数です。デフォルト値は 1 です。このしきい値を超えると、個々のターゲットの結果情報は表示されません。ゼロを指定すると結果情報が常に抑制され、値が非常に大きいと結果が常に出力されます。
ユーザーが小さなターゲット グループの作成(たとえば、compile-edit-test サイクルの間)と大規模なターゲット グループの作成(新しいワークスペースの確立時や回帰テストの実行時など)を定期的に切り替える場合、ユーザーはその中間の値を選択できます。前者の場合、結果情報は非常に有益ですが、後者の場合はそれほど有用ではありません。すべてのオプションと同様に、これは .bazelrc
ファイルを介して暗黙的に指定できます。
ファイルは出力されるので、ファイル名をコピーしてシェルに簡単に貼り付け、ビルドされた実行可能ファイルを実行できます。各ターゲットの「最新」または「失敗」メッセージは、ビルドを推進するスクリプトによって簡単に解析できます。
--sandbox_debug
このオプションを指定すると、アクション実行にサンドボックス化を使用するときに、Bazel が追加のデバッグ情報を出力します。また、サンドボックス ディレクトリも保持されるため、実行中に操作で表示されるファイルを確認できます。
--subcommands
(-s
)
このオプションを指定すると、Bazel の実行フェーズで、各コマンドが実行される前にコマンドライン全体を出力します。
>>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world'] (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \ exec env - \ /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)
可能な場合は、コマンドは Bourne シェルと互換性のある構文で出力されるため、簡単にコピーしてシェルのコマンド プロンプトに貼り付けることができます。(括弧は、シェルを cd
と exec
の呼び出しから保護するために用意されています。必ずコピーしてください)。
ただし、シンボリック リンク ツリーの作成など、一部のコマンドは Bazel に内部的に実装されています。これらについては、表示するコマンドラインはありません。
--subcommands=pretty_print
を渡すと、コマンドの引数が 1 行ではなくリストとして出力されます。これは、長いコマンドラインを読みやすくするのに役立ちます。
以下の --verbose_failures もご覧ください。
ツールに適した形式でサブコマンドをファイルにロギングするには、--execution_log_json_file と --execution_log_binary_file をご覧ください。
--verbose_failures
このオプションを指定すると、Bazel の実行フェーズで、失敗したコマンドの完全なコマンドラインが出力されます。これは、失敗したビルドのデバッグを行ううえで非常に役立ちます。
失敗したコマンドは Bourne シェルと互換性のある構文で出力されます。これは、シェル プロンプトにコピー&ペーストするのに適しています。
ワークスペースのステータス
Bazel でビルドされたバイナリに「スタンプ」するには、これらのオプションを使用します。ソース管理のリビジョンやその他のワークスペース関連情報など、追加情報をバイナリに埋め込みます。このメカニズムは、genrule
、cc_binary
など、stamp
属性をサポートするルールで使用できます。
--workspace_status_command=program
このフラグを使用すると、各ビルドの前に Bazel が実行するバイナリを指定できます。プログラムは、現在のソース管理のリビジョンなど、ワークスペースのステータスに関する情報をレポートできます。
フラグの値には、ネイティブ プログラムへのパスを指定する必要があります。Linux/macOS では、これは任意の実行可能ファイルの可能性があります。Windows の場合、これはネイティブ バイナリ(通常は .exe、.bat、または .cmd ファイル)である必要があります。
プログラムは 0 個以上の Key-Value ペアを標準出力に出力します(1 行に 1 エントリ)。その後、ゼロで終了します(そうでない場合、ビルドは失敗します)。キー名は何にでもかまいませんが、使用できるのは大文字とアンダースコアのみです。キー名の後ろの最初のスペースは、キー名と値を区切ります。値は、行の残りの部分(追加の空白を含む)です。キーも値も複数行にまたがってはなりません。鍵を複製しないでください。
Bazel は、キーを「stable」と「volatile」の 2 つのバケットに分割します。(「stable」と「volatile」という名前は直感的にわかりにくいため、あまり考えないでください)。
Bazel は、Key-Value ペアを次の 2 つのファイルに書き込みます。
bazel-out/stable-status.txt
には、キーの名前がSTABLE_
で始まるすべてのキーと値が含まれます。bazel-out/volatile-status.txt
には、残りのキーとその値が含まれます。
契約内容:
「安定した」キーの値は、可能な限りほとんど変更しないようにしてください。
bazel-out/stable-status.txt
の内容が変更されると、Bazel はそれらに依存するアクションを無効にします。つまり、安定したキーの値が変更されると、Bazel はスタンプ付きのアクションを再実行します。したがって、安定ステータスにはタイムスタンプなどが含まれないようにしてください。タイムスタンプなどはこれらの時刻が常に変更され、ビルドごとに Bazel がスタンプ付きのアクションを再実行するためです。Bazel は、常に次の安定したキーを出力します。
BUILD_EMBED_LABEL
:--embed_label
の値BUILD_HOST
: Bazel が実行されているホストマシンの名前BUILD_USER
: Bazel を実行しているユーザーの名前
「volatile」キーの値は頻繁に変更される可能性があります。Bazel は、タイムスタンプのように常に変更されることを想定し、
bazel-out/volatile-status.txt
ファイルを正式に更新します。ただし、スタンプ付きのアクションが毎回再実行されないように、Bazel では揮発性ファイルが変更されないと仮定しています。つまり、揮発性ステータス ファイルだけが内容が変更されたファイルである場合、Bazel はそれに依存するアクションを無効にしません。アクションの他の入力が変更された場合、Bazel はそのアクションを再実行し、更新された volatile ステータスを確認します。ただし、volatile ステータスが変更されただけではアクションは無効になりません。Bazel は、常に次の揮発性キーを出力します。
BUILD_TIMESTAMP
: ビルドの時刻(Unix エポックからの経過秒数)(System.currentTimeMillis()
の値を 1,000 分の 1 単位)。
Linux/macOS では、--workspace_status_command=/bin/true
を渡してワークスペースのステータスの取得を無効にできます。これは、true
は何も実行せず(ゼロで終了します)、出力がないためです。Windows では、MSYS の true.exe
のパスを渡して同じ効果が得られます。
なんらかの理由で workspace status コマンドが失敗する(ゼロ以外で終了)場合、ビルドは失敗します。
Git を使用した Linux のプログラムの例:
#!/bin/bash echo "CURRENT_TIME $(date +%s)" echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)" echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)" echo "STABLE_USER_NAME $USER"
このプログラムのパスを --workspace_status_command
で渡すと、安定版ステータス ファイルに STABLE 行が含まれ、volatile ステータス ファイルには残りの行が含まれます。
--[no]stamp
このオプションは、stamp
ルール属性と組み合わせて使用し、ビルド情報をバイナリに埋め込むかどうかを制御します。
スタンプは、stamp
属性を使用してルールごとに明示的に有効または無効にできます。詳しくは、ビルド百科事典をご覧ください。ルールで stamp = -1
(*_binary
ルールのデフォルト)が設定されると、このオプションによってスタンプを有効にするかどうかが決まります。
このオプションや stamp
属性に関係なく、Bazel はホスト構成用にビルドされたバイナリをスタンプしません。stamp =
0
(*_test
ルールのデフォルト)を設定するルールでは、--[no]stamp
に関係なく、スタンプが無効になります。--stamp
を指定しても、ターゲットの依存関係が変更されていない場合、ターゲットは強制的に再ビルドされません。
--nostamp
を設定すると、入力の変動性が軽減され、ビルド キャッシュが最大化されるため、通常はビルド パフォーマンスを向上させることができます。
プラットフォーム
これらのオプションを使用して、ビルドの動作を構成するホスト プラットフォームとターゲット プラットフォームを制御し、Bazel ルールで使用できる実行プラットフォームとツールチェーンを制御します。
--platforms=labels
現在のコマンドのターゲット プラットフォームを記述するプラットフォーム ルールのラベル。
--host_platform=label
ホストシステムを記述するプラットフォーム ルールのラベル。
--extra_execution_platforms=labels
アクションを実行するための実行プラットフォームとして利用可能なプラットフォーム。プラットフォームは、正確なターゲットで、またはターゲット パターンとして指定できます。これらのプラットフォームは、register_execution_platforms() によって WORKSPACE ファイルで宣言されたプラットフォームより先に検討されます。
--extra_toolchains=labels
ツールチェーンの解決時に考慮されるツールチェーン ルールツールチェーンは正確なターゲットで指定することも、ターゲット パターンとして指定することもできます。これらのツールチェーンは、register_toolchains() によって WORKSPACE ファイルで宣言されたツールチェーンよりも前に考慮されます。
--toolchain_resolution_debug=regex
ツールチェーン タイプが正規表現と一致する場合に、ツールチェーンの検索時にデバッグ情報を出力します。複数の正規表現を使用する場合は、カンマで区切ります。正規表現の先頭に -
を使用すると、正規表現を否定できます。これは、Bazel または Starlark ルールのデベロッパーが、ツールチェーンの欠落によるエラーをデバッグする際に役立つ場合があります。
その他
--flag_alias=alias_name=target_path
長い Starlark ビルド設定を短い名前にバインドするために使用される便利なフラグ。詳細については、Starlark 構成をご覧ください。
--symlink_prefix=string
生成された便利なシンボリック リンクのプレフィックスを変更します。シンボリック リンク プレフィックスのデフォルト値は bazel-
です。これにより、シンボリック リンク bazel-bin
、bazel-testlogs
、bazel-genfiles
が作成されます。
なんらかの理由でシンボリック リンクを作成できない場合、警告は発行されますが、ビルドは成功したとみなされます。具体的には、読み取り専用のディレクトリや、書き込み権限のないディレクトリでビルドできます。ビルドの完了時に情報メッセージに出力されるパスは、シンボリック リンクが目的の場所を指している場合のみ、シンボリック リンク相対短縮形式を使用します。つまり、作成されるシンボリック リンクに依存できない場合でも、それらのパスの正確性を信頼できます。
このオプションの一般的な値は次のとおりです。
シンボリック リンクの作成を抑制する:
--symlink_prefix=/
を指定すると、Bazel はシンボリック リンク(bazel-out
、bazel-<workspace>
など)を作成または更新しなくなります。このオプションを使用すると、シンボリック リンクの作成を完全に抑制できます。見やすくする:
--symlink_prefix=.bazel/
を指定すると、Bazel によって非表示のディレクトリ.bazel
内にbin
というシンボリック リンクが作成されます。
--platform_suffix=string
構成の略称に接尾辞を追加します。これは、出力ディレクトリの決定に使用されます。このオプションに異なる値を設定すると、ファイルが別のディレクトリに配置されます。たとえば、互いの出力ファイルを大量に上書きしてしまうビルドのキャッシュ ヒット率を改善したり、比較のために出力ファイルを保持したりできます。
--default_visibility=(private|public)
bazel のデフォルトの公開設定の変更をテストするための一時的なフラグ。一般的な使用は意図していませんが、完全性のために文書化しています。
--[no]use_action_cache
このオプションはデフォルトで有効になっています。無効にすると、Bazel はローカル アクション キャッシュを使用しません。 ローカル アクション キャッシュを無効にすると、クリーンビルドのメモリとディスク容量は節約されますが、増分ビルドは遅くなります。
--starlark_cpu_profile=_file_
このフラグ(値はファイル名)を使用すると、Bazel はすべての Starlark スレッドによる CPU 使用率に関する統計情報を収集し、プロファイルを pprof 形式で名前付きファイルに書き込みます。
このオプションを使用すると、過剰な計算が原因で読み込みと分析が遅くなる Starlark 関数を特定できます。例:
$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/... $ pprof /tmp/pprof.gz (pprof) top Type: CPU Time: Feb 6, 2020 at 12:06pm (PST) Duration: 5.26s, Total samples = 3.34s (63.55%) Showing nodes accounting for 3.34s, 100% of 3.34s total flat flat% sum% cum cum% 1.86s 55.69% 55.69% 1.86s 55.69% sort_source_files 1.02s 30.54% 86.23% 1.02s 30.54% expand_all_combinations 0.44s 13.17% 99.40% 0.44s 13.17% range 0.02s 0.6% 100% 3.34s 100% sorted 0 0% 100% 1.38s 41.32% my/project/main/BUILD 0 0% 100% 1.96s 58.68% my/project/library.bzl 0 0% 100% 3.34s 100% main
同じデータを別のビューに表示するには、pprof
コマンド svg
、web
、list
を試してください。
リリースでの Bazel の使用
Bazel は、開発サイクルのソフトウェア エンジニアと、本番環境にデプロイするバイナリを準備するリリース エンジニアの両方で使用されます。このセクションでは、Bazel を使用するリリース エンジニア向けのヒントを紹介します。
重要なオプション
リリースビルドに Bazel を使用すると、ビルドを実行する他のスクリプトと同じ問題が発生します。詳細については、スクリプトから Bazel を呼び出すをご覧ください。特に、次のオプションを強くおすすめします。
これらのオプションも重要です。
--package_path
--symlink_prefix
: 複数の構成のビルドを管理する場合は、「64 ビット」と「32 ビット」など、各ビルドを個別の識別子で区別すると便利です。このオプションは、bazel-bin
などのシンボリック リンクを区別します。
テストの実行
bazel を使用してテストをビルドして実行するには、bazel test
の後にテスト ターゲットの名前を入力します。
デフォルトでは、このコマンドはビルドとテスト アクティビティを同時に実行します。つまり、指定されたすべてのターゲット(コマンドラインで指定された非テスト ターゲットを含む)をビルドし、前提条件がビルドされるとすぐに *_test
ターゲットと test_suite
ターゲットをテストします。つまり、テスト実行はビルドとインターリーブされます。そうすると、通常は速度が大幅に向上します。
「bazel test
」のオプション
--cache_test_results=(yes|no|auto)
(-t
)
このオプションを「auto」(デフォルト)に設定した場合、Bazel は次のいずれかの条件に該当する場合にのみテストを再実行します。
- Bazel はテストまたはその依存関係の変更を検出します
- テストは
external
とマークされます。 --runs_per_test
で複数のテスト実行がリクエストされました- 記録されます。
「no」の場合、すべてのテストが無条件に実行されます。
「はい」の場合、キャッシュの動作は auto と同じです。ただし、テストの失敗と、--runs_per_test
でのテスト実行がキャッシュに保存される点が異なります。
.bazelrc
ファイルでこのオプションをデフォルトで有効にしている場合は、-t
(オン)または -t-
(オフ)という略称が、特定の実行でデフォルトをオーバーライドする場合に便利です。
--check_tests_up_to_date
このオプションは、テストを実行しないように Bazel に指示し、キャッシュに保存されたテスト結果を確認して報告するだけです。以前にビルドおよび実行されていないテストや、テスト結果が古いテストがある場合(ソースコードやビルド オプションが変更されたなど)、Bazel はエラー メッセージ(「テスト結果は最新ではありません」)を報告し、テストのステータスを「NO STATUS」(色出力が有効な場合は赤色)として記録し、ゼロ以外のコードを返します。
このオプションは、[--check_up_to_date](#check-up-to-date)
の動作も暗黙的に示唆します。
このオプションは、送信前のチェックに役立ちます。
--test_verbose_timeout_warnings
このオプションは、テストのタイムアウトがテストの実際の実行時間より大幅に長い場合にユーザーに明示的に警告するよう Bazel に指示します。テストのタイムアウトは不安定にならないように設定する必要がありますが、非常に過剰なタイムアウトを設定しておくと、予期せず発生する実際の問題を非表示にできます。
たとえば、通常は 1 ~ 2 分で実行されるテストの場合、長すぎるため、ETERNAL や LONG のタイムアウトを設定しないでください。
このオプションは、適切なタイムアウト値の決定や既存のタイムアウト値のサニティ チェックを行う際に役立ちます。
--[no]test_keep_going
デフォルトでは、すべてのテストが完了まで実行されます。ただし、このフラグが無効になっている場合、合格しなかったテストでビルドは中止されます。後続のビルドステップとテスト呼び出しは実行されず、処理中の呼び出しはキャンセルされます。--notest_keep_going
と --keep_going
の両方を指定しないでください。
--flaky_test_attempts=attempts
このオプションは、なんらかの理由でテストが失敗した場合に試行できる最大回数を指定します。最初は不合格となったテストが、最終的には成功したテストは、テストサマリーに FLAKY
として報告されます。ただし、Bazel 終了コードまたは合格したテストの合計数を特定する場合は、合格とみなされます。許可されたすべての試行が失敗するテストは、不合格と見なされます。
デフォルト(このオプションが指定されていないかデフォルトに設定されている場合)では、定期的なテストは 1 回だけ試行され、flaky
属性が設定されたテストルールでは 3 回しか試行されません。整数値を指定して、テストの試行回数の上限をオーバーライドできます。Bazel では、システムの不正使用を防ぐため、最大 10 回までテストを試行できます。
--runs_per_test=[regex@]number
このオプションでは、各テストを実行する回数を指定します。すべてのテスト実行は別々のテストとして扱われます(フォールバック機能はそれぞれに独立して適用されます)。
実行に失敗したターゲットのステータスは、--runs_per_test_detects_flakes
フラグの値によって異なります。
- 存在しない場合、実行が失敗すると、テスト全体が失敗します。
- 同じシャードから 2 つの実行があり、PASS と FAIL が返された場合、テストのステータスは不安定になります(他の実行の失敗によって失敗した場合を除く)。
単一の数値を指定すると、すべてのテストがその回数だけ実行されます。また、構文 regex@number を使用して正規表現を指定することもできます。これにより、正規表現に一致するターゲットに対する --runs_per_test
の効果が制限されます(--runs_per_test=^//pizza:.*@4
は、//pizza/
の下のすべてのテストを 4 回実行します)。この形式の --runs_per_test
は複数回指定できます。
--[no]runs_per_test_detects_flakes
このオプションを指定すると(デフォルトでは指定されません)、Bazel は --runs_per_test
を介して不安定なテストシャードを検出します。1 つのシャードに対する 1 つ以上の実行が失敗し、同じシャードパスに対して 1 つ以上の実行が失敗した場合、ターゲットはフラグで不安定とみなされます。指定しない場合、ターゲットは失敗ステータスを報告します。
--test_summary=output_style
テスト結果の概要の表示方法を指定します。
short
は、各テストの結果と、テストが失敗した場合はテストの出力を含むファイルの名前を出力します。これがデフォルト値です。terse
はshort
に似ていますが、さらに短くします。合格しなかったテストに関する情報のみを出力します。detailed
は、各テストだけでなく、失敗した個々のテストケースを出力します。テスト出力ファイルの名前は省略されています。none
はテストサマリーを出力しません。
--test_output=output_style
テスト出力の表示方法を指定します。
summary
には、各テストの合否の概要が表示されます。失敗したテストの出力ログファイル名も表示されます。概要はビルドの最後に出力されます(ビルド中は、テストの開始、合格、失敗を示す単純な進行状況メッセージだけが表示されます)。これがデフォルト設定です。errors
は、テスト完了直後にのみ、失敗したテストの stdout/stderr 出力を結合して stdout に送信し、同時テストからのテスト出力が相互にインターリーブされないようにします。上記のサマリー出力のとおりに、ビルド時にサマリーを出力します。all
はerrors
に似ていますが、合格したテストを含むすべてのテストの出力を出力します。streamed
は、各テストの stdout/stderr 出力をリアルタイムでストリーミングします。
--java_debug
このオプションを選択すると、Java テストの Java 仮想マシンは、JDWP 準拠のデバッガからの接続を待ってからテストを開始します。このオプションは、--test_output=streamed
を意味します。
--[no]verbose_test_summary
このオプションはデフォルトで有効になっています。これにより、テスト時間とその他の追加情報(テスト試行など)がテストサマリーに出力されます。--noverbose_test_summary
を指定すると、テストサマリーにはテスト名、テスト ステータス、キャッシュされたテスト インジケーターのみが含まれ、可能な限り 80 文字以内に収まるようにフォーマットされます。
--test_tmpdir=path
ローカルで実行するテストの一時ディレクトリを指定します。各テストは、このディレクトリ内の個別のサブディレクトリで実行されます。ディレクトリは、各 bazel test
コマンドの開始時にクリーンアップされます。デフォルトでは、bazel はこのディレクトリを Bazel 出力ベース ディレクトリに配置します。
--test_timeout=seconds
または --test_timeout=seconds,seconds,seconds,seconds
指定された秒数を新しいタイムアウト値として使用して、すべてのテストのタイムアウト値をオーバーライドします。値を 1 つだけ指定した場合は、その値がすべてのテスト タイムアウト カテゴリで使用されます。
または、4 つのカンマ区切り値を指定して、短期、中程度のテスト、長期テスト、永続的なテストのタイムアウトを(この順序で)個別に指定することもできます。いずれの形式でも、テストの作成のページで定義されているタイムアウト カテゴリのデフォルトのタイムアウトが、いずれかのテストサイズに対するゼロまたは負の値に置き換えられます。デフォルトでは、Bazel はすべてのテストでこれらのタイムアウトを使用します。サイズが暗黙的か明示的に設定されていても、テストのサイズからタイムアウト上限を推測します。
タイムアウト カテゴリをサイズとは異なるものとして明示的に記述したテストでは、そのタイムアウトがサイズタグによって暗黙的に設定されたのと同じ値を受け取ります。そのため、「長い」タイムアウトを宣言するサイズ「small」のテストの実効タイムアウトは、明示的なタイムアウトのない「大規模」テストと同じ有効タイムアウトになります。
--test_arg=arg
各テストプロセスにコマンドライン オプション/フラグ/引数を渡します。このオプションを複数回使用して、複数の引数を渡すことができます。次に例を示します。
--test_arg=--logtostderr --test_arg=--v=3
--test_env=variable=_value_
または --test_env=variable
各テストのテスト環境に挿入する必要がある追加の変数を指定します。value が指定されていない場合は、bazel test
コマンドの開始に使用されるシェル環境から継承されます。
テスト内から環境にアクセスするには、System.getenv("var")
(Java)、getenv("var")
(C または C++)、
--run_under=command-prefix
これは、テストランナーが実行前にテストコマンドの前に挿入する接頭辞を指定します。command-prefix は、Bourne シェルのトークン化ルールを使用して単語に分割され、実行されるコマンドの前に単語リストが追加されます。
最初の単語が完全修飾ラベル(//
で始まる)の場合はビルドされます。その後、ラベルは対応する実行可能場所に置き換えられ、他の単語とともに実行されるコマンドの先頭に付加されます。
以下の点にご注意ください。
- テストの実行に使用する PATH は、環境の PATH と異なる場合があるため、
--run_under
コマンドに絶対パス(command-prefix の最初の単語)を使用する必要があります。 stdin
は接続されていないため、--run_under
は対話型コマンドには使用できません。
例:
--run_under=/usr/bin/strace --run_under='/usr/bin/strace -c' --run_under=/usr/bin/valgrind --run_under='/usr/bin/valgrind --quiet --num-callers=20'
選択をテスト
出力選択オプションで説明されているように、サイズ、タイムアウト、タグ、または言語でテストをフィルタできます。利便性の高い一般名フィルタを使用して、特定のフィルタ引数をテストランナーに転送できます。
bazel test
のその他のオプション
構文と残りのオプションは bazel build
とまったく同じです。
実行可能ファイルの実行
bazel run
コマンドは、単一のターゲットをビルドして実行するために使用する点を除いて、bazel build
と似ています。一般的なセッションは次のとおりです。
% bazel run java/myapp:myapp -- --arg1 --arg2 Welcome to Bazel INFO: Loading package: java/myapp INFO: Loading package: foo/bar INFO: Loading complete. Analyzing... INFO: Found 1 target... ... Target //java/myapp:myapp up-to-date: bazel-bin/java/myapp:myapp INFO: Elapsed time: 0.638s, Critical Path: 0.34s INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2 Hello there $EXEC_ROOT/java/myapp/myapp --arg1 --arg2
bazel run
は、Bazel によってビルドされたバイナリを直接呼び出すのと類似していますが、同一ではなく、呼び出すバイナリがテストかどうかによって動作が異なります。
バイナリがテストでない場合、現在の作業ディレクトリはバイナリの runfiles ツリーになります。
バイナリがテストの場合、現在の作業ディレクトリが実行ルートになり、テストが通常実行される環境を誠意を持って再現します。ただし、エミュレーションは完全ではないため、複数のシャードを持つテストはこの方法で実行できません(--test_sharding_strategy=disabled
コマンドライン オプションを使用すると、この問題を回避できます)。
バイナリでは、次の追加の環境変数も使用できます。
BUILD_WORKSPACE_DIRECTORY
: ビルドが実行されたワークスペースのルート。BUILD_WORKING_DIRECTORY
: Bazel が実行された現在の作業ディレクトリ。
たとえば、コマンドライン上のファイル名をユーザー フレンドリーな方法で解釈できます。
「bazel run
」のオプション
--run_under=command-prefix
これは bazel test
の --run_under
オプション(上記を参照)と同じですが、bazel test
によって実行されるテストではなく、bazel
run
によって実行されるコマンドに適用されるため、ラベルの下で実行できない点が異なります。
Bazel からのロギング出力のフィルタリング
bazel run
を使用してバイナリを呼び出すと、Bazel 自体と呼び出し中のバイナリからのロギング出力が出力されます。ログのノイズを減らすには、--ui_event_filters
フラグと --noshow_progress
フラグを使用して、Bazel からの出力を抑制します。
次に例を示します。bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp
テストの実行
bazel run
はテストバイナリを実行することもできます。これにより、テストの作成で説明されている環境とほぼ同じ環境でテストを実行できます。この方法でテストを実行する場合、--test_arg
を除き、--test_*
引数は効果がありません。
ビルド出力のクリーニング
clean
コマンド
Bazel には、Make と同様の clean
コマンドがあります。
この Bazel インスタンスによって実行されたすべてのビルド構成の出力ディレクトリ、またはこの Bazel インスタンスによって作成された作業ツリー全体の出力ディレクトリが削除され、内部キャッシュがリセットされます。コマンドライン オプションを指定せずに実行すると、すべての構成の出力ディレクトリがクリーンアップされます。
各 Bazel インスタンスは 1 つのワークスペースに関連付けられているため、clean
コマンドは、そのワークスペース内の Bazel インスタンスに対して行ったすべてのビルドからすべての出力を削除します。
Bazel インスタンスによって作成された作業ツリー全体を完全に削除するには、--expunge
オプションを指定します。--expunge
を使用してクリーンコマンドを実行すると、出力ベースツリー全体が削除されます。このベースツリーには、ビルド出力に加えて、Bazel によって作成されたすべての一時ファイルが含まれます。また、クリーン後に Bazel サーバーを停止します(shutdown
コマンドと同等です)。たとえば、Bazel インスタンスのすべてのディスクとメモリのトレースをクリーンアップするには、次のように指定できます。
% bazel clean --expunge
または、--expunge_async
を使用してバックグラウンドで消去することもできます。非同期消去の処理を続行している間は、同じクライアントで Bazel コマンドを安全に呼び出してください。
clean
コマンドは主に、不要になったワークスペースのディスク容量を再利用するためのものです。Bazel の増分再ビルドは完全ではないため、問題が発生したときに clean
を使用して一貫した状態を復元できます。
Bazel の設計では、これらの問題は修正可能であり、バグは修正の優先度が高いと考えられています。誤った増分ビルドを見つけた場合は、clean
ではなく、バグレポートを提出して、ツールからバグを報告してください。
依存関係グラフをクエリする
Bazel には、ビルド中に使用される依存関係グラフについて質問するためのクエリ言語が含まれています。クエリ言語は、query と cquery の 2 つのコマンドで使用されます。2 つのコマンドの主な違いは、クエリは読み込みフェーズの後に実行され、cquery は分析フェーズの後に実行されることです。これらのツールは、多くのソフトウェア エンジニアリング タスクで非常に役立ちます。
クエリ言語はグラフに対する代数演算の考え方に基づいています 詳細については
Bazel クエリ リファレンス。 参考用、例、クエリ固有のコマンドライン オプションについては、このドキュメントを参照してください。
クエリツールには、コマンドライン オプションがいくつか用意されています。--output
: 出力形式を選択します。--[no]keep_going
(デフォルトで無効)を指定すると、エラー発生時にクエリツールが処理を続行します。エラーの発生で不完全な結果が許容されない場合は、この動作が無効になることがあります。
--[no]tool_deps
オプション(デフォルトで有効)を使用すると、クエリが実行される依存関係グラフにターゲット以外の構成の依存関係が含められます。
--[no]implicit_deps
オプション(デフォルトで有効)を使用すると、クエリが実行される依存関係グラフに暗黙的な依存関係が含まれます。暗黙的な依存関係とは、BUILD ファイルで明示的に指定されていないものの、bazel によって追加された依存関係のことです。
例: 「PEBL ツリー内のすべてのテストをビルドするために必要なすべての genrules の定義(BUILD ファイル内)の場所を示します。」
bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'
アクション グラフに対するクエリの実行
aquery
コマンドを使用すると、ビルドグラフ内でアクションをクエリできます。分析後に構成されたターゲット グラフを操作し、アクション、アーティファクト、それらの関係に関する情報を公開します。
このツールでは、いくつかのコマンドライン オプションを使用できます。--output
: 出力形式を選択します。デフォルトの出力形式(text
)は人が読める形式です。機械で判読できる形式には proto
または textproto
を使用します。特に、aquery コマンドは通常の Bazel ビルド上で実行され、ビルド中に使用できる一連のオプションを継承します。
従来の query
でも使用できるものと同じ関数セットをサポートしていますが、siblings
、buildfiles
、tests
です。
詳細については、アクショングラフ クエリをご覧ください。
その他のコマンドとオプション
help
help
コマンドは、オンライン ヘルプを表示します。デフォルトでは、Bazel を使用したビルドに示すように、使用可能なコマンドとヘルプトピックの概要が表示されます。
引数を指定すると、特定のトピックに関する詳細なヘルプが表示されます。ほとんどのトピックは build
や query
などの Bazel コマンドですが、コマンドに対応していないヘルプトピックもあります。
--[no]long
(-l
)
デフォルトでは、bazel help [topic]
はトピックに関連するオプションの概要のみを出力します。--long
オプションを指定すると、各オプションのタイプ、デフォルト値、詳細な説明も出力されます。
shutdown
Bazel サーバー プロセスは、shutdown
コマンドを使用して停止できます。このコマンドを実行すると、Bazel サーバーがアイドル状態になるとすぐに(たとえば、進行中のビルドやコマンドが完了した後)すぐに終了します。詳しくは、クライアント/サーバーの実装をご覧ください。
Bazel サーバーはアイドル タイムアウト後に自ら停止するため、このコマンドが必要になることはほとんどありません。ただし、特定のワークスペースでそれ以上ビルドが行われないことがわかっている場合は、スクリプトで役立ちます。
shutdown
は --iff_heap_size_greater_than _n_
という 1 つのオプションを受け入れます。このオプションには整数の引数(MB 単位)が必要です。指定すると、すでに消費されているメモリの量によってシャットダウンが条件になります。Bazel サーバーでメモリリークが発生すると誤ってクラッシュする可能性があるため、大量のビルドを開始するスクリプトに便利です。条件付き再起動を実行すると、この状態がプリエンプトされます。
info
info
コマンドは、Bazel サーバー インスタンスまたは特定のビルド構成に関連付けられているさまざまな値を出力します。(ビルドを推進するスクリプトで使用される場合があります)。
info
コマンドでは、単一の(省略可能な)引数も指定できます。これは、以下のリストにあるいずれかのキーの名前です。この場合、bazel info key
はその 1 つのキーの値のみを出力します。(この方法は、Bazel をスクリプトで記述する場合に特に便利です。これにより、sed -ne /key:/s/key://p
を介して結果をパイプで渡す必要がなくなります。
構成に依存しないデータ
release
: この Bazel インスタンスのリリースラベル。リリース バイナリでない場合は「development version」。workspace
は、ベース ワークスペース ディレクトリへの絶対パスです。install_base
: 現在のユーザーのこの Bazel インスタンスで使用されているインストール ディレクトリの絶対パス。Bazel は、内部で必要な実行可能ファイルをこのディレクトリにインストールします。output_base
: 現在のユーザーとワークスペースの組み合わせに対して、この Bazel インスタンスで使用されるベース出力ディレクトリの絶対パス。Bazel は、すべてのスクラッチとビルド出力をこのディレクトリに配置します。execution_root
: output_base の実行ルート ディレクトリへの絶対パス。このディレクトリは、ビルド時に実行されるコマンドからアクセス可能なすべてのファイルのルートで、それらのコマンドの作業ディレクトリでもあります。ワークスペース ディレクトリが書き込み可能な場合、このディレクトリを指すbazel-<workspace>
という名前のシンボリック リンクがそこに配置されます。output_path
: ビルドコマンドの結果として実際に生成されたすべてのファイルに使用される実行ルートの下にある出力ディレクトリへの絶対パス。ワークスペース ディレクトリが書き込み可能な場合、このディレクトリを指すbazel-out
という名前のシンボリック リンクが配置されます。server_pid
: Bazel サーバー プロセスのプロセス ID。server_log
: Bazel サーバーのデバッグ ログファイルへの絶対パス。このファイルには、Bazel サーバーの存続期間におけるすべてのコマンドのデバッグ情報が含まれており、Bazel デベロッパーとパワーユーザーが人間で使用することを前提としています。command_log
: コマンド ログファイルの絶対パス。これには、最新の Bazel コマンドのインターリーブされた stdout ストリームと stderr ストリームが含まれます。bazel info
を実行すると、このファイルの内容が上書きされ、これが最新の Bazel コマンドになるので注意してください。ただし、コマンド ログファイルの場所は、--output_base
または--output_user_root
オプションの設定を変更しない限り変更されません。used-heap-size
、committed-heap-size
、max-heap-size
: さまざまな JVM ヒープサイズ パラメータをレポートします。それぞれ、現在使用されているメモリ、システムから JVM が使用できることが現在保証されているメモリ、可能な最大割り当てです。gc-count
、gc-time
: この Bazel サーバーの起動以降のガベージ コレクションの累積数と実行にかかった時間。これらの値は、すべてのビルドの開始時にリセットされるわけではありません。package_path
: bazel でパッケージを検索するパスをコロンで区切ったリスト。形式は、ビルド コマンドライン引数--package_path
と同じです。
例: Bazel サーバーのプロセス ID。
% bazel info server_pid 1285
構成固有のデータ
これらのデータは、bazel info
に渡される構成オプション(--cpu
、--compilation_mode
など)の影響を受ける場合があります。info
コマンドは、依存関係の分析を制御するすべてのオプションを受け入れます。これらのオプションの一部によって、ビルドの出力ディレクトリの場所やコンパイラの選択などが決まるからです。
bazel-bin
、bazel-testlogs
、bazel-genfiles
: ビルドによって生成されたプログラムが配置されているbazel-*
ディレクトリへの絶対パスを報告します。これは、常にではありませんが、ビルドが成功した後にベース ワークスペース ディレクトリに作成されるbazel-*
シンボリック リンクと同じです。ただし、ワークスペース ディレクトリが読み取り専用の場合は、bazel-*
シンボリック リンクは作成できません。シンボリック リンクの存在を前提としない、bazel info
によって報告された値を使用するスクリプトは、より堅牢になります。- 「Make」環境全体。
--show_make_env
フラグを指定すると、現在の構成の「Make」環境内のすべての変数(CC
、GLIBC_VERSION
など)も表示されます。これらは、BUILD ファイル内で$(CC)
またはvarref("CC")
構文を使用してアクセスされる変数です。
例: 現在の構成の C++ コンパイラ。
これは「Make」環境の $(CC)
変数であるため、--show_make_env
フラグが必要です。
% bazel info --show_make_env -c opt COMPILATION_MODE opt
例: 現在の構成の bazel-bin
出力ディレクトリ。なんらかの理由で bazel-bin
シンボリック リンクを作成できない場合(読み取り専用のディレクトリからビルドしている場合など)でも、これで正しいことが保証されます。
% bazel info --cpu=piii bazel-bin /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin % bazel info --cpu=k8 bazel-bin /var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin
version
、--version
version コマンドは、ビルドされた Bazel バイナリのバージョンの詳細(ビルドされた変更リストや日付など)を出力します。これらは、最新の Bazel を使用しているかどうかの判断や、バグの報告を行う場合に特に役立ちます。興味深い値は次のとおりです。
changelist
: このバージョンの Bazel がリリースされた変更リスト。label
: この Bazel インスタンスのリリースラベル。リリース バイナリでない場合は「development version」。バグを報告する際に非常に役立つ
bazel --version
は、他の引数がない場合、bazel version --gnu_format
と同じ出力を出力しますが、Bazel サーバーの起動やサーバー アーカイブの解凍などの副作用が発生することはありません。bazel --version
はどこからでも実行できます。ワークスペース ディレクトリは必要ありません。
mobile-install
mobile-install
コマンドは、モバイル デバイスにアプリをインストールします。現時点では、ART を実行している Android デバイスのみがサポートされています。
詳しくは、bazel のモバイル インストールをご覧ください。
次のオプションがサポートされています。
--incremental
設定した場合、Bazel はアプリを段階的にインストールしようとします。つまり、前回のビルド以降に変更された部分だけを試みます。AndroidManifest.xml
から参照されるリソース、ネイティブ コード、Java リソース(Class.getResource()
によって参照されるリソースなど)は更新できません。これらが変更される場合は、このオプションを省略する必要があります。Bazel の精神に反し、Android プラットフォームの制限があるため、このコマンドで十分かどうか、フルインストールが必要なタイミングを判断することは、ユーザーの責任となります。
Marshmallow 以降を搭載したデバイスを使用している場合は、--split_apks
フラグを検討してください。
--split_apks
分割 apk を使用してデバイス上でアプリのインストールと更新を行うかどうかを指定します。Marshmallow 以降を搭載したデバイスでのみ動作します。なお、--split_apks
を使用する場合、--incremental
フラグは必要ありません。
--start_app
インストール後にアプリをクリーンな状態で起動します。--start=COLD
と同じです。
--debug_app
デバッガがアタッチされるのを待ってから、インストール後にクリーンな状態でアプリを起動します。--start=DEBUG
と同じです。
--start=_start_type_
インストール後にアプリを起動する方法。サポートされている _start_type_s:
NO
アプリは起動しません。これがデフォルトです。COLD
: インストール後、アプリをクリーンな状態から起動します。WARM
: 増分インストール時にアプリケーションの状態を保持および復元します。DEBUG
デバッガを待ってから、インストール後にクリーンな状態でアプリを起動します。
--adb=path
使用する adb
バイナリを示します。
デフォルトでは、--android_sdk
で指定された Android SDK の adb を使用します。
--adb_arg=serial
adb
の追加の引数。これらはコマンドラインのサブコマンドの前に配置され、通常はインストール先のデバイスを指定するために使用されます。
たとえば、使用する Android デバイスまたはエミュレータを選択するには、次のようにします。
% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef
次のように adb
を呼び出します。
adb -s deadbeef install ...
--incremental_install_verbosity=number
増分インストールの詳細情報。1 に設定すると、デバッグ ロギングがコンソールに出力されます。
dump
dump
コマンドは、Bazel サーバーの内部状態のダンプを stdout に出力します。このコマンドは、主に Bazel デベロッパーによる使用を想定しているため、このコマンドの出力は指定されていません。また、変更される可能性があります。
デフォルトでは、コマンドは Bazel の状態の特定の領域をダンプするオプションについて概説するヘルプ メッセージを出力します。内部状態をダンプするには、少なくとも 1 つのオプションを指定する必要があります。
次のオプションがサポートされています。
--action_cache
は、アクション キャッシュのコンテンツをダンプします。--packages
はパッケージ キャッシュのコンテンツをダンプします。--skyframe
は、内部の Bazel 依存関係グラフの状態をダンプします。--rules
は、各ルールとアスペクト クラスのルールの概要(カウントやアクションの数など)をダンプします。これには、ネイティブ ルールと Starlark ルールの両方が含まれます。メモリ トラッキングが有効になっている場合は、ルールのメモリ消費量も出力されます。--skylark_memory
は、pprof 互換の .gz ファイルを指定されたパスにダンプします。そのためには、メモリ トラッキングを有効にする必要があります。
メモリのトラッキング
一部の dump
コマンドはメモリ トラッキングを必要とします。これを有効にするには、起動フラグを Bazel に渡す必要があります。
--host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar
--host_jvm_args=-DRULE_MEMORY_TRACKER=1
java-agent は third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar
で Bazel にチェックインされるため、Bazel リポジトリを保持する場所に応じて $BAZEL
を調整してください。
コマンドごとにこれらのオプションを Bazel に必ず渡してください。そうしないと、サーバーが再起動します。
例:
% bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ build --nobuild <targets> # Dump rules % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ dump --rules # Dump Starlark heap and analyze it with pprof % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \ --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \ dump --skylark_memory=$HOME/prof.gz % pprof -flame $HOME/prof.gz
analyze-profile
analyze-profile
コマンドは、--profile
オプションを使用して、ビルド中に以前に収集されたデータを分析します。ビルド実行の分析を実行するオプションや、指定した形式でデータをエクスポートするためのオプションがいくつか用意されています。
次のオプションがサポートされています。
--dump
は、収集されたすべてのデータを人が判読できる形式で表示します。ただし、他の形式はまだサポートされていません。
形式の詳細と使用方法については、プロファイリングによるパフォーマンスのトラブルシューティングをご覧ください。
canonicalize-flags
canonicalize-flags
コマンド。Bazel コマンドのオプションのリストを受け取り、同じ効果を持つオプションのリストを返します。オプションの新しいリストは正規です。たとえば、効果が同じである 2 つのオプションのリストは同じ新しいリストに正規化されます。
--for_command
オプションを使用すると、さまざまなコマンドから選択できます。現時点では、build
と test
のみがサポートされています。指定したコマンドでサポートされていないオプションは、エラーが発生します。
例は次のとおりです。
% bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint" --config=any_name --test_tag_filters=-lint
起動オプション
このセクションで説明するオプションは、Bazel サーバー プロセスで使用される Java 仮想マシンの起動に影響し、そのサーバーで処理されるすべての後続のコマンドに適用されます。すでに実行中の Bazel サーバーが存在し、起動オプションが一致しない場合、そのサーバーが再起動されます。
このセクションで説明するオプションはすべて、--key=value
構文または --key value
構文で指定する必要があります。また、これらのオプションは、Bazel コマンドの名前の前に配置する必要があります。startup --key=value
を使用して、これらを .bazelrc
ファイルにリストします。
--output_base=dir
このオプションにはパス引数が必要です。この引数には、書き込み可能なディレクトリを指定する必要があります。Bazel は、この場所を使用してすべての出力を書き込みます。出力ベースは、クライアントが Bazel サーバーを見つけるために使用されるキーでもあります。出力ベースを変更することで、コマンドを処理するサーバーを変更できます。
デフォルトでは、出力ベースはユーザーのログイン名とワークスペース ディレクトリの名前(実際には MD5 ダイジェスト)から取得されます。したがって、一般的な値は /var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e
のようになります。
例:
OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base % bazel --output_base ${OUTPUT_BASE}1 build //foo & bazel --output_base ${OUTPUT_BASE}2 build //bar
このコマンドでは、2 つの Bazel コマンドが同時に実行されます(シェルの &
演算子のため)。それぞれが異なる Bazel サーバー インスタンスを使用しています(出力ベースが異なるため)。一方、デフォルトの出力ベースが両方のコマンドで使用されていた場合、両方のリクエストが同じサーバーに送信され、順番に処理されます。つまり、最初に //foo
をビルドしてから、//bar
の増分ビルドを行います。
--output_user_root=dir
出力ベースとインストール ベースが作成されるルート ディレクトリを指します。このディレクトリは存在しないか、呼び出し元のユーザーが所有するものである必要があります。これまでは、さまざまなユーザー間で共有されるディレクトリを指すことが可能でしたが、現在は使用できなくなりました。これは、問題 #11100 に対処した後に許可される可能性があります。
--output_base
オプションを指定すると、--output_user_root
を使用して出力ベースの計算にオーバーライドされます。
インストール ベースの場所は、--output_user_root
と、Bazel 埋め込みバイナリの MD5 ID に基づいて計算されます。
ファイル システム レイアウトに適切な場所がある場合は、--output_user_root
オプションを使用して、Bazel のすべての出力(インストール ベースと出力ベース)に代替ベースの場所を選択できます。
--server_javabase=dir
Bazel 自体が実行される Java 仮想マシンを指定します。値には、JDK または JRE を含むディレクトリへのパスを指定する必要があります。ラベルは使用できません。 このオプションは、Bazel コマンドよりも前に配置する必要があります。次に例を示します。
% bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo
このフラグは、アプリケーション、テスト、ツールなどの Bazel サブプロセスで使用される JVM には影響を与えません。代わりに、ビルド オプションの --javabase または --host_javabase を使用してください。
このフラグは以前、--host_javabase
(「左側」の --host_javabase
と呼ばれることもあります)という名前でしたが、ビルドフラグ --host_javabase(「右側」の --host_javabase
と呼ばれることもあります)との混同を避けるため、名前が変更されました。
--host_jvm_args=string
Bazel 自体が実行される Java 仮想マシンに渡す起動オプションを指定します。これを使用してスタックサイズを設定できます。次に例を示します。
% bazel --host_jvm_args="-Xss256K" build //foo
このオプションは、個別の引数で複数回使用できます。このフラグの設定が必要になることはほとんどありません。スペース区切りの文字列リストを渡すこともできます。各文字列は個別の JVM 引数として解釈されますが、この機能はまもなく非推奨になります。
これは、Bazel のサブプロセスで使用される JVM(アプリケーション、テスト、ツールなど)に影響しないということです。bazel
run
またはコマンドラインのどちらで実行可能な Java プログラムに JVM オプションを渡すかには、すべての java_binary
プログラムと java_test
プログラムがサポートする --jvm_flags
引数を使用する必要があります。代わりに、テスト用に bazel test --test_arg=--jvm_flags=foo ...
を使用します。
--host_jvm_debug
このオプションを使用すると、Java 仮想マシンは JDWP 準拠のデバッガからの接続を待機してから、Bazel 自体のメインメソッドを呼び出します。これは、主に Bazel デベロッパーによる使用を対象としています。
--autodetect_server_javabase
このオプションを使用すると、Bazel は起動時にインストールされている JDK を自動的に検索し、埋め込み JRE を使用できない場合はインストールされている JRE にフォールバックします。--explicit_server_javabase
を使用すると、Bazel を実行する明示的な JRE を選択できます。
--batch
バッチモードでは、Bazel は標準のクライアント/サーバーモードを使用せず、1 つのコマンドに対して bazel Java プロセスを実行します。これは、シグナル処理、ジョブ制御、環境変数の継承に関して予測可能なセマンティクスに使用されており、chroot jail で bazel を実行するために必要です。
バッチモードでは、同じ output_base 内で適切なキューイング セマンティクスが保持されます。つまり、同時呼び出しは重複することなく順番に処理されます。サーバーを実行しているクライアントでバッチモードの Bazel が実行されている場合、コマンドを処理する前にまずサーバーを強制終了します。
Bazel は、バッチモードまたは上記の別の方法を使用すると、実行速度が遅くなります。 ビルドファイル キャッシュはメモリ常駐であるため、順次バッチ呼び出し間では保持されません。そのため、連続ビルドなど、パフォーマンスがそれほど重要でない場合は、バッチモードを使用するほうが理にかなっています。
--max_idle_secs=n
このオプションでは、最後のクライアント リクエストから終了までに Bazel サーバー プロセスが待機する時間を秒単位で指定します。デフォルト値は 10,800(3 時間)です。--max_idle_secs=0
を指定すると、Bazel サーバー プロセスが無期限に保持されます。
このオプションは、Bazel を呼び出すスクリプトで使用され、他の方法では実行されない状況で Bazel サーバー プロセスをユーザーのマシンに残さないようにします。
たとえば、presubmit スクリプトで bazel query
を呼び出し、ユーザーの保留中の変更によって不要な依存関係が発生しないようにできます。ただし、ユーザーがそのワークスペースで最近ビルドを行っていない場合、その日の残りの期間アイドル状態にしておくためだけに、presubmit スクリプトが Bazel サーバーを起動することは望ましくありません。クエリ リクエストで --max_idle_secs
の小さな値を指定することで、スクリプトにより、新しいサーバーが起動ifした場合、そのサーバーはすぐに終了します。ただし、すでにサーバーが実行されている場合は、通常の時間アイドル状態になるまで稼働を継続します。既存のサーバーのアイドル タイマーはリセットされます。
--[no]shutdown_on_low_sys_mem
有効にすると、--max_idle_secs
が正の期間に設定され、ビルドサーバーがしばらくアイドル状態であった後、システムのメモリが不足しているときにサーバーをシャットダウンします。Linux のみ。
max_idle_secs に対応するアイドル チェックを実行するだけでなく、サーバーがしばらくアイドル状態になると、ビルドサーバーは利用可能なシステムメモリのモニタリングを開始します。使用可能なシステムメモリが極端に少なくなると、サーバーは終了します。
--[no]block_for_lock
有効にすると、Bazel は、サーバーロックを保持する他の Bazel コマンドが完了するまで待ってから先に進みます。無効にすると、すぐにロックを取得して処理できないと、Bazel はエラーで終了します。
デベロッパーは、presubmit チェックでこれを使用して、同じクライアント内の別の Bazel コマンドによる長い待機を回避することができます。
--io_nice_level=n
ベスト エフォートの IO スケジューリングのレベルを 0 ~ 7 に設定します。0 の優先度が最も高く、7 の優先度が最も低くなります。予測スケジューラは、優先度 4 までしか尊重できません。 負の値は無視されます。
--batch_cpu_scheduling
Bazel 用に batch
CPU スケジューリングを使用します。このポリシーは、非対話型だが、適切な値を下げたくないワークロードに役立ちます。「man 2 sched_setscheduler」をご覧ください。このポリシーでは、Bazel のスループットを犠牲にしてシステムのインタラクティビティを改善できます。
その他のオプション
--[no]announce_rc
起動時に bazelrc ファイルから読み取ったコマンド オプションを Bazel が通知するかどうかを制御します。(起動オプションは無条件に通知されます)。
--color (yes|no|auto)
このオプションにより、Bazel で画面上の出力を色でハイライト表示するかどうかを指定できます。
このオプションを yes
に設定した場合、色出力が有効になります。
このオプションを auto
に設定すると、出力がターミナルに送信され、TERM 環境変数が dumb
、emacs
、xterm-mono
以外の値に設定されている場合にのみ、Bazel はカラー出力を使用します。このオプションを no
に設定すると、出力がターミナルに送信されるかどうかや、TERM 環境変数の設定に関係なく、色出力が無効になります。
--config=name
rc ファイルから追加の構成セクションを選択します。現在の command
については、このようなセクションが存在する場合は command:name
からオプションも取得します。複数回指定して、複数の構成セクションからフラグを追加できます。展開は他の定義を参照できます(たとえば、展開を連結できます)。
--curses (yes|no|auto)
このオプションにより、Bazel が画面出力でカーソル コントロールを使用するかどうかが決まります。その結果、スクロール データが少なくなり、Bazel からの出力ストリームがコンパクトになり、読みやすくなります。これは --color
で適切に機能します。
このオプションを yes
に設定すると、カーソル コントロールが有効になります。
このオプションを no
に設定した場合、カーソル コントロールは無効になります。
このオプションを auto
に設定すると、--color=auto
と同じ条件でカーソル コントロールの使用が有効になります。
--[no]show_timestamps
指定すると、メッセージが表示された時刻を指定して、Bazel によって生成された各メッセージにタイムスタンプが追加されます。