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
檔案旁)。如果這個檔案不存在,則不會發生錯誤。
主遠端控制檔案 (除非
--nohome_rc
存在)。路徑:
- Linux/macOS/Unixes:
$HOME/.bazelrc
- Windows:
%USERPROFILE%\.bazelrc
(如有),或%HOME%/.bazelrc
如果這個檔案不存在,則不會發生錯誤。
- Linux/macOS/Unixes:
使用者指定的 RC 檔案 (如果使用
--bazelrc=file
指定)這個標記為選用項目,但也可以多次指定。
/dev/null
表示系統會忽略所有後續的--bazelrc
,這適合用來停用使用者弧形檔案搜尋功能 (例如在發布子版本中)。例如:
--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
的差異在於,Bazel 會在缺少 import
的檔案遺失 (或無法讀取) 時失敗,但如果 try-import
的檔案發生失敗,則 Bazel 不會執行。
匯入優先順序:
- 已匯入檔案中的選項優先於匯入陳述式之前的指定選項。
- 匯入陳述式之後指定的選項優先於匯入檔案中的選項。
- 之後匯入的檔案選項會優先於先前匯入的檔案。
預設值
bazelrc 的大部分行都會定義預設選項值。每行的第一個字詞會指出這些預設值的套用時機:
startup
:啟動選項 (位於指令之前),在bazel help startup_options
中詳細說明。common
:應套用至支援這些選項的所有 Bazel 指令的選項。如果指令不支援以這種方式指定的選項,只要該選項適用於 some 其他 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
,且除非同一個選項有test
行,否則所有build
行也都會套用至bazel test
。如果弧形檔案顯示: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
- 所有指令都繼承自
針對相同指令指定選項的兩行,系統會按照它們在檔案中的順序剖析。
由於這項優先順序規則與檔案順序不相符,因此在 rc 檔案中採用的優先順序順序時,將有助於讀取:從頂端的
common
選項開始,並在檔案底部以最具體的指令結尾。這樣一來,選項讀取順序就會與套用順序相同,更符合直覺。
弧形檔案上指定的引數可能包含非選項的引數,例如建構目標的名稱等。這些選項跟在相同檔案中指定的選項一樣,在指令列中的同層級優先順序較低,且一律會加在非選項引數的明確清單前面。
--config
除了設定選項預設值之外,rc 檔案也可用來將選項分組,並提供常見分組的簡要說明。方法是在指令中加入 :name
後置字串。根據預設,系統會忽略這些選項,但會在 --config=name
選項 (無論是在指令列或 .bazelrc
檔案上以遞迴方式出現) 時納入這些選項,即使是在其他設定定義中也一樣。系統只會按照上述優先順序為適用指令展開 command:name
指定的選項。
--config=foo
會展開為 rc 檔案中定義的選項,因此您為設定指定的選項優先順序與 --config=foo
選項相同。
這項語法不會延伸至使用 startup
設定啟動選項的權限。在 .bazelrc 中設定 startup:config-name --some_startup_option
將遭到忽略。
範例
以下是 ~/.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 檔案:
- 系統 rc-file,位於 etc/bazel.bazelrc
。- 位於 $workspace/tools/bazel.rc
的工作區架構檔案。- 本機架構檔案,本機檔案,位置:$HOME/.bazelrc
這裡列出的每個 bazelrc 檔案都有對應的標記 (例如 --nosystem_rc
、--noworkspace_rc
、--nohome_rc
)。您也可以傳送 --ignore_all_rc_files
啟動選項,讓 Bazel 忽略所有 bazelrc。