寫入 bazelrc 設定檔

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

    如果這個檔案不存在，則不需視為錯誤。

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

    路徑：

    • 在 Linux/macOS/Unixes 上：$HOME/.bazelrc
    • 在 Windows 上：%USERPROFILE%\.bazelrc (如果存在) 或 %HOME%/.bazelrc

    如果這個檔案不存在，則不需視為錯誤。

  4. 環境變數 RC 檔案 (如果路徑是透過 BAZELRC 環境變數設定)。

    環境變數可以包含多個以半形逗號分隔的路徑。

  5. 使用者指定的 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 Shell 相同的規則進行權杖化。

匯入

以 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、fetch 和 vendor 繼承自 test

  • 如果兩行指定相同指令的選項，且具備相同明確性，系統會按照選項在檔案中的顯示順序剖析選項。

  • 由於這項優先順序規則與檔案順序不符，因此建議您在 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 中，您可以使用平台專屬設定，系統會根據主機 OS 自動啟用這些設定。舉例來說，如果主機 OS 是 Linux，且執行 build 指令，系統就會自動啟用 build:linux 設定。支援的 OS 識別碼為 linux、macos、windows、freebsd 和 openbsd。

這等同於在 Linux 上使用 --config=linux、在 Windows 上使用 --config=windows 等等。您可以使用 --enable_platform_specific_config=false 停用這項功能。

請參閱 --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 忽略的目錄，每行一個目錄。項目是相對於工作區根目錄。

.bazelignore 檔案不允許使用 glob 語意。 Bazel 8 導入 REPO.bazel 檔案，可使用另一個指令 ignore_directories()。與 .bazelignore 相同，這個屬性會採用要忽略的目錄清單，但使用 glob 語意。請參閱 #24203。

全域 bazelrc 檔案

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

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

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