Bazel 接受許多選項。部分選項經常變動 (例如 --subcommands
),而其他選項在多個建構中不會相同 (例如 --package_path
)。如要避免每個建構作業 (和其他指令) 指定這些未變更的選項,您可以在名為 .bazelrc
的設定檔中指定選項。
.bazelrc
檔案在哪裡?
Bazel 會按照以下的順序,在下列位置尋找選用設定檔。系統會按照此順序解譯選項,因此較新的檔案若有衝突,後續檔案中的選項可以覆寫先前檔案中的值。所有控制其中哪些檔案已載入的選項都是啟動選項,也就是說,這些選項必須在 bazel
之後和指令之前 (build
、test
等) 發生。
系統 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%
。- Linux/macOS/Unixes:
工作區 RC 檔案 (除非
--noworkspace_rc
存在)。路徑:工作區目錄中的
.bazelrc
(位於主要WORKSPACE
檔案旁)。如果檔案不存在,並不會導致錯誤。
住家 RC 檔案 (除非有
--nohome_rc
存在)。路徑:
- Linux/macOS/Unixes:
$HOME/.bazelrc
- Windows:
%USERPROFILE%\.bazelrc
(如有),或%HOME%/.bazelrc
如果檔案不存在,並不會導致錯誤。
- Linux/macOS/Unixes:
使用者指定的 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 檔案:
- 位於
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。