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 ファイルも検索します。詳しくは、グローバル 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 コマンドに適用するオプション。この方法で指定されたオプションをコマンドがサポートしていない場合、他の Bazel コマンドで有効である限り、そのオプションは無視されます。これはオプション名にのみ適用されます。現在のコマンドが、指定された名前のオプションを受け入れるが、指定された値がサポートされていない場合、失敗します。always
: すべての Bazel コマンドに適用されるオプション。この方法で指定されたオプションをサポートしていないコマンドは失敗します。command
: オプションが適用される Bazel コマンド(build
、query
など)。これらのオプションは、指定したコマンドを継承するすべてのコマンドにも適用されます。(たとえば、test
はbuild
から継承されます)。
これらの各行は複数回使用でき、最初の単語に続く引数は 1 行に記述されているかのように結合されます。(「スイス アーミー ナイフ」コマンドライン インターフェースを備えた別のツールである CVS を使用している場合は、.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 test
に対してすべてのbazel build
フラグが有効であり、同じオプションにtest
行がない限り、すべてのbuild
行がbazel 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
から継承されます。 - 次のコマンドは
build
を継承し、test
、run
、clean
、mobile-install
、info
、print_action
、config
、cquery
、aquery
よりも限定的です。 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
を設定しても無視されます。
--enable_platform_specific_config
.bazelrc
内のプラットフォーム固有の構成は、--enable_platform_specific_config
を使用して自動的に有効にできます。たとえば、ホスト OS が Linux の場合に build
コマンドを実行すると、build:linux
構成が自動的に有効になります。サポートされている OS 識別子は linux
、macos
、windows
、freebsd
、openbsd
です。このフラグを有効にすると、Linux では --config=linux
、Windows では --config=windows
などと同等です。
--enable_platform_specific_config をご覧ください。
例
以下に、~/.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 ファイルを次の順序で読み取ります。
- システム rc-file は
etc/bazel.bazelrc
にあります。 $workspace/tools/bazel.rc
にある Workspace の RC ファイル。$HOME/.bazelrc
にあるホームの RC ファイル
ここに示す各 bazelrc ファイルには対応するフラグがあり、これを使用して無効化できます(例: --nosystem_rc
、--noworkspace_rc
、--nohome_rc
)。--ignore_all_rc_files
起動オプションを渡すことで、Bazel がすべての bazelrc を無視するようにすることもできます。