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
已讀取。- 因為先前的
/dev/null
而忽略z.rc
。
除了這個選用的設定檔外,Bazel 也會尋找全域 rc 檔案。詳情請參閱全球 bazelrc 一節。
.bazelrc
語法和語意
如同所有 UNIX 的「rc」檔案,.bazelrc
檔案是包含行號文法的文字檔案。系統會忽略開頭為 #
(註解) 的空白行和行。每一行都包含一串字詞,系統會根據 Bourne 殼層適用的規則進行符記化。
匯入
以 import
或 try-import
開頭的行是特殊的,您可以使用這些行載入其他「rc」檔案。如要指定相對於工作區根目錄的路徑,請寫入 import %workspace%/path/to/bazelrc
。
import
和 try-import
之間的差別在於,如果缺少 import
的檔案 (或無法讀取),Bazel 就會失敗,而對於 try-import
的檔案則否。
匯入優先順序:
- 匯入檔案中的選項優先於匯入陳述式之前指定的選項。
- 匯入陳述式之後指定的選項優先於匯入檔案中的選項。
- 檔案之後匯入的選項優先於稍早匯入的檔案。
選項預設值
蝴蝶餅型的大部分行都會定義預設選項值。每一行的第一個字詞會指定套用這些預設值的時機:
startup
:啟動選項,位於指令之前,如bazel help startup_options
所述。common
:適用於所有 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
(且更具體):test
、run
、clean
、mobile-install
、info
、print_action
、config
、cquery
和aquery
- 「
coverage
」沿用自test
- 每個指令繼承自
系統會以兩行指定選項,指定相同指令的不同選項,並按照在檔案中的顯示順序剖析。
由於這項優先順序規則與檔案順序不同,因此如果您遵循 rc 檔案中的優先順序,建議您優先採用
common
選項,最後將最具體的指令放在檔案底部,這樣可方便您閱讀。這樣一來,選項讀取的順序與套用順序相同,就更加直覺化。
在 rc 檔案一行中指定的引數,可能包含非選項的引數,例如建構目標的名稱等。如同相同檔案中指定的選項,這些項目在指令列上的優先順序低於其同層級,且一律會加在非選項引數的明確清單之前。
--config
除了設定選項預設值之外,rc 檔案可用於將選項分組,並提供一般分組的簡明。如要這麼做,請在指令中加入 :name
後置字串。這些選項預設為忽略,但如果出現 --config=name
選項,則包括在指令列或 .bazelrc
檔案中,遞迴地包含在其他設定定義中。command:name
指定的選項只會按照上述優先順序擴大,並涵蓋適用的指令。
--config=foo
會擴充為「位置」中定義的選項,讓設定中指定的選項的優先順序與 --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 檔案:
- 位於 etc/bazel.bazelrc
的系統 rc-file。
- 位於 $workspace/tools/bazel.rc
的工作區 rc-file。
- 主要位置為 $HOME/.bazelrc
這裡所列的每個 bazelrc 檔案都有對應的旗標,可用於停用 (例如 --nosystem_rc
、--noworkspace_rc
、--nohome_rc
)。您也可以傳遞 --ignore_all_rc_files
啟動選項,讓 Bazel 忽略所有 Bazel。