Bazel では、多くのオプションを使用できます。オプションには、頻繁に変更されるもの(--subcommands
など)もあれば、複数のビルドで同じ状態を維持するもの(--package_path
など)もあります。このような変更されていないオプションをすべてのビルド(およびその他のコマンド)に指定しないようにするには、.bazelrc
という構成ファイルでオプションを指定します。
.bazelrc
ファイルの場所
Bazel は、以下の場所にあるオプションの構成ファイルを以下の順序で検索します。オプションはこの順序で解釈されるため、競合が発生した場合に、後続のファイルのオプションが以前のファイルの値をオーバーライドできます。これらのファイルのうちどれを読み込むかを制御するオプションはすべて起動オプションです。つまり、bazel
の後、コマンドの前(build
、test
など)に指定する必要があります。
システムの RC ファイル(
--nosystem_rc
が存在しない場合)。パス:
- Linux/macOS/Unix の場合:
/etc/bazel.bazelrc
- Windows の場合:
%ProgramData%\bazel.bazelrc
このファイルが存在しない場合でも、エラーにはなりません。
システム指定の別の場所が必要な場合は、カスタムの Bazel バイナリをビルドし、
//src/main/cpp:option_processor
のBAZEL_SYSTEM_BAZELRC_PATH
値をオーバーライドする必要があります。システム指定の場所に、Unix の${VAR_NAME}
や Windows の%VAR_NAME%
などの環境変数参照が含まれていることがあります。- Linux/macOS/Unix の場合:
ワークスペースの RC ファイル(
--noworkspace_rc
が存在しない場合)。パス: ワークスペース ディレクトリの
.bazelrc
(メインのWORKSPACE
ファイルの横)。このファイルが存在しない場合でも、エラーにはなりません。
ホーム RC ファイル(
--nohome_rc
が存在しない場合)。パス:
- Linux/macOS/Unix の場合:
$HOME/.bazelrc
- Windows の場合:
%USERPROFILE%\.bazelrc
(存在する場合)、%HOME%/.bazelrc
このファイルが存在しない場合でも、エラーにはなりません。
- Linux/macOS/Unix の場合:
ユーザー指定の RC ファイル(
--bazelrc=file
で指定されている場合)このフラグは省略可能ですが、複数回指定することもできます。
/dev/null
は、それ以降のすべての--bazelrc
が無視されることを示します。リリースビルドなどで、ユーザー RC ファイルの検索を無効にする場合に役立ちます。例:
--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
x.rc
とy.rc
が読み取られます。/dev/null
が以前のため、z.rc
は無視されます。
このオプションの構成ファイルに加えて、Bazel はグローバル rc ファイルも検索します。詳細については、global bazelrc セクションをご覧ください。
.bazelrc
の構文とセマンティクス
すべての UNIX "rc" ファイルと同様に、.bazelrc
ファイルは行ベースの文法を含むテキスト ファイルです。#
(コメント)で始まる空の行および行は無視されます。各行には単語のシーケンスが含まれ、これらの単語は Bourne シェルと同じルールに従ってトークン化されます。
インポート
import
または try-import
で始まる行は特殊です。これらを使用して他の「rc」ファイルを読み込みます。ワークスペースのルートからの相対パスを指定するには、import %workspace%/path/to/bazelrc
と記述します。
import
と try-import
の違いは、import
対象のファイルがない(または読み取れない)場合、Bazel は失敗しますが、try-import
対象のファイルでは失敗します。
インポートの優先順位:
- インポート ファイル内のオプションは、import ステートメントの前に指定されたオプションよりも優先されます。
- import ステートメントの後に指定されたオプションは、インポートされたファイル内のオプションよりも優先されます。
- 後からインポートしたファイルのオプションは、先にインポートしたファイルよりも優先されます。
オプションのデフォルト
bazelrc のほとんどの行で、デフォルトのオプション値が定義されています。各行の最初の単語には、これらのデフォルトが適用されるタイミングを指定します。
startup
: 起動オプション。コマンドの前に配置します。説明はbazel help startup_options
です。common
: すべての Bazel コマンドに適用されるオプション。command
: オプションが適用される Bazel コマンド(build
、query
など)。これらのオプションは、指定したコマンドから継承するすべてのコマンドにも適用されます。(たとえば、test
はbuild
から継承されます)。
各行を複数回使用しても、最初の単語に続く引数は、1 行に記述されているかのように組み合わせられます。(CVS は「スイス アーミー ナイフ」コマンドライン インターフェースを備えたもう 1 つのツールであり、.cvsrc
の構文のような構文です)。たとえば、以下の行です。
build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar
次のように組み合わせられます。
build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar
そのため、有効なフラグは --verbose_failures
と --test_tmpdir=/tmp/bar
です。
オプションの優先度:
- コマンドラインのオプションは、rc ファイルのオプションよりも常に優先されます。たとえば、RC ファイルに
build -c opt
と指定されているのに、コマンドライン フラグが-c dbg
の場合、コマンドライン フラグが優先されます。 rc ファイル内では、特異性によって優先順位が変わります。より具体的なコマンドの行が、具体性の低いコマンドの行よりも優先されます。
特異性は継承によって定義されます。一部のコマンドは他のコマンドからオプションを継承するため、継承されるコマンドは基本コマンドよりも限定されます。たとえば、
test
はbuild
コマンドから継承しているため、すべてのbazel build
フラグはbazel test
に対して有効であり、すべてのbuild
行はbazel test
にも適用されます(同じオプションにtest
行がない限り)。rc ファイルの内容に応じて次のように対応します。test -c dbg --test_env=PATH
build -c opt --verbose_failures
この場合、
bazel build //foo
は-c opt --verbose_failures
を使用し、bazel test //foo
は--verbose_failures -c dbg --test_env=PATH
を使用します。継承(特異性)グラフは次のとおりです。
- すべてのコマンドは
common
から継承されます。 test
、run
、clean
、mobile-install
、info
、print_action
、config
、cquery
、aquery
の各コマンドはbuild
を継承します(かつ、それより限定的です)。coverage
はtest
から継承します。
- すべてのコマンドは
同じコマンドの指定性が等しい 2 行が、ファイル内に出現する順序で解析されます。
この優先順位のルールはファイルの順序と一致しないため、rc ファイル内の優先順位に従うと読みやすくなります。つまり、先頭に
common
オプションを追加し、最も具体的なコマンドをファイルの下部に配置します。こうすると、オプションが読み取られる順序は、オプションが適用される順序と同じになるため、より直感的になります。
rc ファイルの行で指定された引数には、ビルド ターゲットの名前など、オプションではない引数を含めることができます。これらは、同じファイルで指定されるオプションと同様に、コマンドラインで兄弟ノードよりも優先度が低くなります。また、常にオプション以外の引数の明示的なリストの先頭に付加されます。
--config
rc ファイルは、オプションのデフォルトを設定するだけでなく、オプションをグループ化し、一般的なグループの省略形として使用できます。そのためには、コマンドに :name
接尾辞を追加します。これらのオプションはデフォルトで無視されますが、コマンドラインまたは .bazelrc
ファイルにオプション --config=name
が存在する場合(別の構成定義内であっても)、再帰的に組み込まれます。command:name
で指定されたオプションは、該当するコマンドに対してのみ、上記の優先順位に従って展開されます。
--config=foo
は、rc ファイルで定義されたオプションに「インプレース」展開されるため、構成に指定されたオプションの優先順位は --config=foo
オプションと同じになります。
この構文は、startup
を使用して起動オプションを設定する場合には適用されません。.bazelrc で startup:config-name --some_startup_option
を設定しても無視されます。
例
以下に、~/.bazelrc
ファイルの例を示します。
# Bob's Bazel option defaults
startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going
# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600
Bazel の動作を管理するその他のファイル
.bazelignore
他のビルドシステムを使用する関連プロジェクトなど、Bazel に無視されるワークスペース内のディレクトリを指定できます。ワークスペースのルートに .bazelignore
というファイルを配置し、Bazel に無視するディレクトリを 1 行に 1 つずつ追加します。エントリはワークスペースのルートを基準としています。
グローバル bazelrc ファイル
Bazel は、オプションの bazelrc ファイルを次の順序で読み取ります。
- etc/bazel.bazelrc
にあるシステム rc-ファイル。
- $workspace/tools/bazel.rc
にある Workspace rc-file。
- $HOME/.bazelrc
にローカライズされたホーム RC ファイル
ここに示す各 bazelrc ファイルには、これらを無効にするために使用できる対応するフラグがあります(例: --nosystem_rc
、--noworkspace_rc
、--nohome_rc
)。--ignore_all_rc_files
起動オプションを渡すことで、Bazel がすべての bazelrc を無視するようにすることもできます。