寫入 bazelrc 設定檔

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 (位於主要 MODULE.bazel 檔案旁)。

    如果這個檔案不存在，則不會發生錯誤。

  3. home RC 檔案 (除非有 --nohome_rc)。

    路徑：

    • 在 Linux/macOS/Unix 上：$HOME/.bazelrc
    • Windows：%USERPROFILE%\.bazelrc (如有)，或 %HOME%/.bazelrc

    如果檔案不存在，系統不會顯示錯誤。

  4. 使用者指定的 RC 檔案 (如果使用 --bazelrc=file 指定)

    這個標記為選用，但也可以多次指定。

    /dev/null 表示系統會忽略所有後續的 --bazelrc，這適合用來停用使用者弧形檔案搜尋功能 (例如在發布子版本中)。

    例如：

    --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
    • 讀取 x.rc 和 y.rc。
    • z.rc 會因先前的 /dev/null 而遭到忽略。

除了這個選用設定檔外，Bazel 還會尋找全域 rc 檔案。詳情請參閱global bazelrc 專區。

.bazelrc 語法和語意

與所有 UNIX「rc」檔案一樣，.bazelrc 檔案是含有行數文法的文字檔案。系統會忽略開頭為 # (註解) 的空白行和行。每行都包含字詞序列，這些字詞會根據 Bourne 殼層的相同規則進行剖析。

匯入

開頭為 import 或 try-import 的行是特殊的：用於載入其他「rc」檔案。如要指定相對於工作區根目錄的路徑，請輸入 import %workspace%/path/to/bazelrc。

import 和 try-import 的差異在於，如果缺少 (或無法讀取) import'ed 檔案，Bazel 就會失敗，但 try-import'ed 檔案則不會。

匯入優先順序：

  • 匯入檔案中的選項優先於匯入陳述式前指定的選項。
  • 在匯入陳述式後指定的選項，會優先於匯入檔案中的選項。
  • 之後匯入的檔案選項會優先於先前匯入的檔案。

選項預設值

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

  • startup：啟動選項 (位於指令之前)，在 bazel help startup_options 中詳細說明。
  • common：應套用至支援這些選項的所有 Bazel 指令的選項。如果指令不支援以這種方式指定的選項，只要該選項對某些其他 Bazel 指令有效，系統就會忽略該選項。請注意，這項規則只適用於選項名稱：如果目前指令接受具有指定名稱的選項，但不支援指定的值，則會失敗。
  • always：適用於所有 Bazel 指令的選項。如果指令不支援以這種方式指定的選項，則會失敗。
  • command：適用於選項的 Bazel 指令，例如 build 或 query。這些選項也適用於繼承指定指令的所有指令。(例如 test 繼承自 build)。

這些行可重複使用，而第一個字詞後面的引數會合併，就像是出現在單一行中一樣。(CVS 是另一個使用「Swiss army knife」指令列介面的工具，則會找到與 .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 (更具體地說) 從 test、run、clean、mobile-install、info、print_action、config、cquery 和 aquery
    • coverage、fetch 和 vendor 繼承自 test

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

  • 由於這個優先順序規則與檔案順序不符，因此建議您在 rc 檔案中遵循優先順序：從頂端的 common 選項開始，並以檔案底部的最具體指令結束。這樣一來，選項讀取順序就會與套用順序相同，更符合直覺。

弧形檔案上指定的引數可能包含非選項的引數，例如建構目標的名稱等。這些選項與在相同檔案中指定的選項一樣，在指令列上的優先順序低於其他同類項目，且一律會置於非選項引數的明確清單之前。

--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

您可以使用 --enable_platform_specific_config 自動啟用 .bazelrc 中的平台專屬設定。舉例來說，如果主機作業系統是 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 忽略的目錄，每行一個。項目相對於工作區根目錄。

全域 bazelrc 檔案

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

  1. 位於 etc/bazel.bazelrc 的系統 rc 檔案。
  2. 位於 $workspace/tools/bazel.rc 的工作區 rc 檔案。
  3. 位於 $HOME/.bazelrc 的主頁面 rc-file

此處列出的每個 bazelrc 檔案都有對應的標記，可用於停用這些檔案 (例如 --nosystem_rc、--noworkspace_rc、--nohome_rc)。您也可以傳遞 --ignore_all_rc_files 啟動選項，讓 Bazel 忽略所有 bazelrc。