寫入 bazelrc 設定檔

回報問題 查看原始碼

Bazel 接受許多選項。部分選項經常變動 (例如 --subcommands)，而其他選項在多個建構中不會相同 (例如 --package_path)。如要避免每個建構作業 (和其他指令) 指定這些未變更的選項，您可以在名為 .bazelrc 的設定檔中指定選項。

.bazelrc 檔案在哪裡？

Bazel 會按照以下的順序，在下列位置尋找選用設定檔。系統會按照此順序解譯選項，因此較新的檔案若有衝突，後續檔案中的選項可以覆寫先前檔案中的值。所有控制其中哪些檔案已載入的選項都是啟動選項，也就是說，這些選項必須在 bazel 之後和指令之前 (build、test 等) 發生。

  1. 系統 RC 檔案 (除非 --nosystem_rc 存在)。

    路徑：

    • Linux/macOS/Unixes：/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/Unixes：$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。
    • z.rc 會因先前的 /dev/null 而遭到忽略。

除了這個選用設定檔外，Bazel 也會尋找全域 rc 檔案。詳情請參閱全球 bazelrc 一節。

.bazelrc 語法和語意

與所有 UNIX「rc」檔案一樣，.bazelrc 檔案是含有折線圖的文字檔。系統會忽略開頭為 # (註解) 的空白行和行。每一行包含一串字詞，系統會根據與 Bourne 殼層相同的規則進行代碼化。

匯入

開頭為 import 或 try-import 的行是特殊的：使用這些程式碼載入其他「rc」檔案。如要指定與工作區根目錄相關的路徑，請寫入 import %workspace%/path/to/bazelrc。

import 和 try-import 的差異在於，如果缺少 (或無法讀取) 的 import 檔案，Bazel 就會失敗，但對於 try-import 的檔案卻沒有。

匯入優先順序：

  • 匯入檔案中的選項優先於匯入陳述式之前指定的選項。
  • 匯入陳述式後指定的選項優先順序高於匯入檔案中的選項。
  • 稍後匯入的檔案選項優先順序高於先前匯入的檔案。

選項預設值

大部分的 bazelrc 都會定義預設選項值。每一行的第一個字詞會指定套用預設值的時機：

  • startup：位於指令之前的啟動選項，如 bazel help startup_options 所述。
  • common：應套用至所有支援它們的 Bazel 指令。如果指令不支援以這種方式指定的選項，只要該選項適用於「有些」Bazel 指令仍然有效，系統就會忽略該選項。請注意，這僅適用於選項名稱：如果目前的指令接受具有指定名稱的選項，但不支援指定的值，則該選項會失敗。
  • always：適用於所有 Bazel 指令的選項。如果指令不支援以這種方式指定的選項，就會失敗。
  • command：Bazel 指令，例如適用選項的 build 或 query。這些選項也適用於繼承自特定指令的所有指令。(例如，test 會繼承 build 的設定)。

這行程式碼可以多次使用，而且第一個字詞之後的引數會合併成單行顯示。(如為 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 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
    • 下列指令繼承自 build，且比 build 更明確：test、run、clean、mobile-install、info、print_action、config、cquery 和 aquery
    • 「coverage」繼承自 test

  • 系統會按照檔案在檔案中的顯示順序，針對相同指令指定相同指令的兩行選項進行剖析。

  • 由於此優先順序規則與檔案順序不相符，因此如果您按照 rc 檔案中的順序以相同順序排列，將有助於讀取：請從檔案頂部開始 common 選項，並在檔案底部以最具體的指令結尾。如此一來，讀取選項的順序會與套用選項的順序相同，比較直覺。

在 rc 檔案行中指定的引數可能包含非選項的引數，例如建構目標名稱等。就像相同檔案中指定的選項一樣，優先順序比在指令列中的同層級低，而且一律會加在非選項引數的明確清單前面。

--config

除了設定選項預設值之外，rc 檔案也可以用來將選項分組，並提供常見分組的簡寫。只要在指令中加入 :name 後置字串即可。根據預設，系統會忽略這些選項，但系統會在指令列或 .bazelrc 檔案中以遞迴方式納入 --config=name 選項，即使在其他設定定義中也一樣。command:name 指定的選項只會針對適用的指令擴充，順序如上所述。

--config=foo 會展開為「就地」中定義的選項，因此設定中指定的選項優先順序會與 --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 ID 包括 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 忽略的目錄 (每行一個)。項目與工作區根目錄相關。

全域 bazelrc 檔案

Bazel 會按照以下順序讀取選用的 bazelrc 檔案：

  1. 位於 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。