bazelrc 構成ファイルを書き込む

問題を報告 ソースを表示

Bazel では多くのオプションを使用できます。オプションの中には、頻繁に変更されるもの（--subcommands など）もあれば、複数のビルドで変わらないもの（--package_path など）もあります。すべてのビルド（および他のコマンド）で変更されないオプションを指定しないようにするには、.bazelrc という構成ファイルでオプションを指定します。

.bazelrc ファイルはどこにありますか。

Bazel は、以下の場所でオプションの構成ファイルを以下の順序で検索します。オプションはこの順序で解釈されるため、競合が発生した場合、後のファイルのオプションが以前のファイルの値をオーバーライドできます。これらのファイルを読み込むタイミングを制御するオプションはすべて起動オプションです。つまり、bazel の後、コマンドの前に存在する必要があります（build、test など）。

  1. システムの 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% などの環境変数参照が含まれている場合があります。

  2. ワークスペースの RC ファイル（--noworkspace_rc が存在しない場合）。

    パス: ワークスペース ディレクトリ内の .bazelrc（メインの WORKSPACE ファイルの横）。

    このファイルが存在しない場合はエラーにはなりません。

  3. ホーム RC ファイル（--nohome_rc が存在しない場合）。

    パス:

    • Linux/macOS/Unix の場合: $HOME/.bazelrc
    • Windows の場合: %USERPROFILE%\.bazelrc（存在する場合）、または %HOME%/.bazelrc

    このファイルが存在しない場合はエラーにはなりません。

  4. ユーザー指定の 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 ファイルを次の順序で読み取ります。

  1. システム rc-file は etc/bazel.bazelrc にあります。
  2. $workspace/tools/bazel.rc にある Workspace の RC ファイル。
  3. $HOME/.bazelrc にあるホームの RC ファイル

ここに示す各 bazelrc ファイルには対応するフラグがあり、これを使用して無効化できます（例: --nosystem_rc、--noworkspace_rc、--nohome_rc）。--ignore_all_rc_files 起動オプションを渡すことで、Bazel がすべての bazelrc を無視するようにすることもできます。