指令和選項

回報問題 查看原始碼

本頁面說明各種 Bazel 指令可用的選項,例如 bazel buildbazel runbazel test。這個網頁是「使用 Bazel 建構」中 Bazel 指令清單。

目標語法

部分指令 (例如 buildtest) 可以對目標清單執行。它們使用的語法比標籤更有彈性,詳情請參閱指定要建構的目標

選項

以下各節說明建構期間的可用選項。當 --long 用於說明指令時,線上說明訊息會提供每個選項意義、類型與預設值的摘要資訊。

大部分選項只能指定一次。如果多次指定,就會由最後一個執行個體組成。您可以在線上說明中,找到可多次指定的選項,並標示「可多次使用」。

套件位置

--package_path

這個選項會指定一組目錄,以供搜尋特定套件的 BUILD 檔案。

Bazel 會透過搜尋套件路徑來尋找套件。這是以冒號分隔的 bzel 目錄清單,每個目錄都是部分來源樹狀結構的根層級。

使用 --package_path 選項指定自訂套件路徑

  % bazel build --package_path %workspace%:/some/other/root

套件路徑元素可用三種格式指定:

  1. 如果第一個字元是 /,則路徑是絕對路徑。
  2. 如果路徑以 %workspace% 開頭,系統會將路徑採用最接近封閉式 bazel 目錄的路徑。舉例來說,如果您的工作目錄是 /home/bob/clients/bob_client/bazel/foo,則套件路徑中的 %workspace% 字串會展開為 /home/bob/clients/bob_client/bazel
  3. 其他所有設定則與工作目錄相關。這通常不是您的意思,而如果您使用 Bazel 工作區下方的目錄,可能會發生非預期的行為。舉例來說,如果您使用 package-path 元素 .,然後 cd 到 /home/bob/clients/bob_client/bazel/foo 目錄,就會從 /home/bob/clients/bob_client/bazel/foo 目錄解析套件。

如果您使用非預設套件路徑,為了方便起見,請在 Bazel 設定檔中指定該路徑。

Bazel 不需要任何套件位於目前的目錄中,因此,如果所有必要的套件可在套件路徑的其他位置找到,您可以透過空 bazel 工作區執行建構作業。

範例:從空白用戶端建構

  % mkdir -p foo/bazel
  % cd foo/bazel
  % touch WORKSPACE
  % bazel build --package_path /some/other/path //foo

--deleted_packages

這個選項會指定 Bazel 應考慮刪除的套件清單 (以半形逗號分隔),並且不會嘗試從套件路徑上的任何目錄載入。這可用於模擬套件的刪除作業,而不必實際刪除套件。這個選項可以多次傳遞,在此情況下,個別清單會串連。

錯誤檢查

這些選項可控管 Bazel 的錯誤檢查和/或警告。

--[no]check_visibility

如果將這個選項設為 False,系統會將瀏覽權限檢查降級為警告。 這個選項的預設值是 true,因此根據預設會進行瀏覽權限檢查。

--output_filter=regex

--output_filter 選項只會顯示符合規則運算式的目標的建構和編譯警告。如果目標與指定的規則運算式不符,且執行作業成功,系統就會捨棄其標準輸出內容和標準錯誤。

以下是這個選項的一些常見值:

`--output_filter='^//(first/project|second/project):'` 顯示指定套件的輸出內容。
`--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'` 不會顯示指定套件的輸出內容。
`--output_filter=` 顯示所有內容。
`--output_filter=DONT_MATCH_ANYTHING` 不顯示任何內容。

工具旗標

這些選項可控管 Bazel 將哪些選項傳送到其他工具。

--copt=cc-option

這個選項需要要傳遞至編譯器的引數。每當您為了進行預先處理、編譯和/或組合 C、C++ 或組合器程式碼而叫用引數時,系統就會將引數傳遞給編譯器。連結時並不會傳送。

這個選項可以多次使用。例如:

  % bazel build --copt="-g0" --copt="-fpic" //foo

系統將編譯 foo 程式庫,但不會編譯偵錯資料表,進而產生與位置無關的程式碼。

--host_copt=cc-option

這個選項使用引數,並傳遞至編譯器中,用於在執行設定中編譯的來源檔案。這類似於 --copt 選項,但僅適用於執行設定。

--host_conlyopt=cc-option

這個選項接受引數,並傳遞至執行設定中編譯的 C 來源檔案適用的編譯器。這類似於 --conlyopt 選項,但僅適用於執行設定。

--host_cxxopt=cc-option

這個選項採用引數,並傳遞至在執行設定中編譯的 C++ 來源檔案適用的編譯器。這類似於 --cxxopt 選項,但僅適用於執行設定。

--host_linkopt=linker-option

這個選項接受引數,並傳遞至執行設定中編譯的來源檔案連結器。這類似於 --linkopt 選項,但僅適用於執行設定。

--conlyopt=cc-option

此選項採用的引數會在編譯 C 來源檔案時傳遞至編譯器。

這與 --copt 類似,但僅適用於 C 編譯,不適用於 C++ 編譯或連結。因此,您可以使用 --conlyopt 傳遞 C 專屬選項 (例如 -Wno-pointer-sign)。

--cxxopt=cc-option

這個選項會採用引數,系統會在編譯 C++ 來源檔案時傳遞至編譯器。

這與 --copt 類似,但僅適用於 C++ 編譯,不適用於 C 編譯或連結。因此,您可以使用 --cxxopt 傳遞 C++ 特定選項 (例如 -fpermissive-fno-implicit-templates)。

例如:

  % bazel build --cxxopt="-fpermissive" --cxxopt="-Wno-error" //foo/cruddy_code

--linkopt=linker-option

這個選項使用引數,系統會在連結時傳遞至編譯器。

這與 --copt 類似,但僅適用於連結,不適用於編譯。因此,您可以使用 --linkopt 傳遞只有在連結時才有意義的編譯器選項 (例如 -lssp-Wl,--wrap,abort)。例如:

  % bazel build --copt="-fmudflap" --linkopt="-lmudflap" //foo/buggy_code

您也可以在建構規則的屬性中指定連結選項。此選項的設定一律優先。另請參閱 cc_library.linkopts

--strip (always|never|sometimes)

這個選項會使用 -Wl,--strip-debug 選項叫用連結器,藉此判斷 Bazel 是否會移除所有二進位檔和共用程式庫的偵錯資訊。--strip=always 一律移除偵錯資訊。--strip=never 一律不會移除偵錯資訊。--strip=sometimes 的預設值表示 --compilation_modefastbuild 時的條紋。

  % bazel build --strip=always //foo:bar

會編譯目標,同時移除所有已產生的二進位檔的偵錯資訊。

Bazel 的 --strip 選項與 ld 的 --strip-debug 選項對應:它只會移除偵錯資訊。如果您基於某些原因而想移除「所有」符號 (而不只是 debug 符號),則必須使用 ld 的 --strip-all 選項,將 --linkopt=-Wl,--strip-all 傳遞至 Bazel。另請注意,設定 Bazel 的 --strip 旗標會覆寫 --linkopt=-Wl,--strip-all,因此建議僅設定其中一個。

如果您只想建構單一二進位檔,且想移除所有符號,也可以傳遞 --stripopt=--strip-all,並明確建構目標的 //foo:bar.stripped 版本。如 --stripopt 一節所述,這樣做會在最終二進位檔連結後套用移除動作,而非移除所有建構的連結動作。

--stripopt=strip-option

這是在產生 *.stripped 二進位檔時傳送至 strip 指令的額外選項。預設值為 -S -p。這個選項可以多次使用。

--fdo_instrument=profile-output-dir

--fdo_instrument 選項可在執行建構的 C/C++ 二進位檔時,產生 FDO (意見回饋導向最佳化) 設定檔輸出內容。如為 GCC,提供的引數會做為 .gcda 檔案目錄樹狀結構的目錄前置字串,其中包含每個 .o 檔案的設定檔資訊。

產生設定檔資料樹狀結構後,設定檔樹狀結構應該就會壓縮,並提供給 --fdo_optimize=profile-zip Bazel 選項,以便啟用 FDO 最佳化編譯功能。

對於 LLVM 編譯器,引數也是傾印原始 LLVM 設定檔資料檔案的目錄。例如 --fdo_instrument=/path/to/rawprof/dir/

--fdo_instrument」和「--fdo_optimize」選項無法同時使用。

--fdo_optimize=profile-zip

--fdo_optimize 選項可讓您使用個別物件的檔案設定檔資訊,在編譯時執行 FDO (意見回饋導向最佳化) 最佳化。以 GCC 來說,提供的引數是 ZIP 檔案,其中包含先前產生的 .gcda 檔案樹狀結構,其中包含每個 .o 檔案的設定檔資訊。

或者,提供的引數也可以指向擴充功能 .afdo 識別的自動設定檔。

如果是 LLVM 編譯器,提供的引數應指向 llvm-profdata 工具準備且已建立索引的 LLVM 設定檔輸出檔案,且應包含 .profdata 副檔名。

--fdo_instrument」和「--fdo_optimize」選項無法同時使用。

--java_language_version=version

這個選項會指定 Java 來源的版本。例如:

  % bazel build --java_language_version=8 java/com/example/common/foo:all

可編譯,並且只允許建構與 Java 8 規格相容的建構項目。這個門檻的預設值為 8。--> 可能的值包括:8、9、10、11、14、15 和 21,並透過 default_java_toolchain 註冊自訂 Java 工具鍊以擴充。

--tool_java_language_version=version

Java 語言版本,用於建構工具在建構期間執行的工具。這個門檻的預設值為 8。

--java_runtime_version=version

這個選項會指定執行程式碼及執行測試的 JVM 版本。舉例來說:

  % bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application

從遠端存放區下載 JDK 11,然後使用該工具執行 Java 應用程式。

預設值為 local_jdk。可能的值包括:local_jdklocal_jdk_versionremotejdk_11remotejdk_17。您可以使用 local_java_repositoryremote_java_repository 存放區規則註冊自訂 JVM,藉此擴充值。

--tool_java_runtime_version=version

用來執行建構期間必要工具的 JVM 版本。預設值為 remotejdk_11

--jvmopt=jvm-option

這個選項可將選項引數傳遞至 Java VM。可以與一個大型引數搭配使用,或是與個別引數多次搭配使用。例如:

  % bazel build --jvmopt="-server -Xms256m" java/com/example/common/foo:all

會使用伺服器 VM 啟動所有 Java 二進位檔,並將 VM 的啟動堆積大小設為 256 MB。

--javacopt=javac-option

此選項可將選項引數傳遞至 javac。可以與一個大型引數搭配使用,或是與個別引數多次搭配使用。例如:

  % bazel build --javacopt="-g:source,lines" //myprojects:prog

會使用 javac 預設偵錯資訊重新建構 java_binary (而不是 bazel 預設值)。

系統會先針對 Javac 的內建預設選項和個別規則選項,將選項傳送至 javac。任何 javac 選項的最後一個規格會勝出。javac 的預設選項如下:

  -source 8 -target 8 -encoding UTF-8

--strict_java_deps (default|strict|off|warn|error)

這個選項可控制 javac 是否要檢查缺少的直接依附元件。Java 目標必須明確將所有直接使用的目標宣告為依附元件。這個標記會指示 javac 判斷用於檢查每個 Java 檔案的類型實際使用的 jar;如果這些 jar 不是目前目標的直接依附元件的輸出內容,則系統會顯示警告/錯誤。

  • off 表示檢查功能已停用。
  • warn 表示 javac 會對每個缺少的直接依附元件產生 [strict] 類型的標準 Java 警告。
  • defaultstricterror 代表 javac 都會產生錯誤 (而非警告),在發現任何缺少的直接依附元件時,會導致目前目標無法建構。這是未指定標記時的預設行為。

建構語意

這些選項會影響建構指令和/或輸出檔案內容。

--compilation_mode (fastbuild|opt|dbg) (-c)

--compilation_mode 選項 (通常縮短為 -c,尤其是 -c opt) 會使用 fastbuilddbgopt 的引數,並會影響各種 C/C++ 程式碼產生選項,例如最佳化等級和偵錯資料表的完整性。Bazel 會針對不同的編譯模式使用不同的輸出目錄,因此您可以在不同模式之間切換,而無需「每次」重新建構。

  • fastbuild 代表盡快建構:能產生最少的偵錯資訊 (-gmlt -Wl,-S),且不進行最佳化。此為預設值。注意:系統「不會」設定 -DNDEBUG
  • dbg 代表在啟用偵錯功能 (-g) 的情況下進行建構,因此您可以使用 gdb (或其他偵錯工具)。
  • opt 代表在啟用最佳化功能的情況下進行建構,同時停用 assert() 呼叫 (-O2 -DNDEBUG)。除非您一併傳遞 --copt -g,否則 opt 模式將不會產生偵錯資訊。

--cpu=cpu

這個選項會指定在建構期間編譯二進位檔的目標 CPU 架構。

--action_env=VAR=VALUE

指定所有動作執行期間可用的環境變數組合。 變數可以依名稱指定;在此情況下,值會從叫用環境取得;若是 name=value 組合,則可設定與叫用環境無關的值。

這個 --action_env 旗標可以多次指定。如果在多個 --action_env 標記中為同一個變數指派同一個變數,最新的指派作業就會勝出。

--experimental_action_listener=label

experimental_action_listener 選項會指示 Bazel 使用 label 指定的 action_listener 規則的詳細資料,將 extra_actions 插入建構圖表。

--[no]experimental_extra_action_top_level_only

如果這個選項設為 True,系統只會為頂層目標排程 --experimental_action_listener 指令列選項指定的其他動作。

--experimental_extra_action_filter=regex

experimental_extra_action_filter 選項會指示 Bazel 篩選一組目標,以便排定 extra_actions 的時程。

這個標記只能與 --experimental_action_listener 旗標搭配使用。

根據預設,所要求目標到建構的連帶關閉狀態中的所有 extra_actions 都會安排執行。--experimental_extra_action_filter 會將排程限制在 extra_actions,其中擁有者的標籤與指定規則運算式相符。

以下範例會限制 extra_actions 的排程僅適用於擁有者標籤包含「/bar/」的動作:

% bazel build --experimental_action_listener=//test:al //foo/... \
  --experimental_extra_action_filter=.*/bar/.*

--host_cpu=cpu

這個選項會指定應用於建構主機工具的 CPU 架構名稱。

--android_platforms=platform[,platform]*

用於建構 android_binary 規則遞移 deps 的平台 (尤其是 C++ 等原生依附元件)。舉例來說,如果 cc_library 出現在 android_binary 規則的遞移 deps 中,系統會針對 android_binary 規則以 --android_platforms 指定的每個平台建構一次,且包含在最終輸出內容中。

這個標記沒有預設值:必須定義及使用自訂 Android 平台。

系統會為每個使用 --android_platforms 指定的平台建立一個 .so 檔案,並封裝在 APK 中。.so 檔案的名稱前方會加上「lib」android_binary 規則的名稱。舉例來說,如果 android_binary 的名稱是「foo」,檔案則為 libfoo.so

--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...

如果有 C++ 檔案含有標籤或執行路徑,且該檔案與其中一個納入規則運算式運算式相符,且與任何排除運算式不相符,則系統會使用指定的選項來建構此檔案。標籤比對會使用標籤的標準格式 (例如 //package:label_name)。

執行路徑是工作區目錄的相對路徑,包含 C++ 檔案的基本名稱 (包括副檔名)。也包含所有與平台相關的前置字串。

如要比對產生的檔案 (例如 genrule 輸出內容),Bazel 只能使用執行路徑。在這種情況下,規則運算式不應以「//」開頭,因為兩者不符合任何執行路徑。套件名稱的使用方式如下:--per_file_copt=base/.*\.pb\.cc@-g0。這會比對名為 base 目錄下的所有 .pb.cc 檔案。

這個選項可以多次使用。

無論使用哪種編譯模式,系統都會套用選項。舉例來說,您可以使用 --compilation_mode=opt 進行編譯,並選擇性地編譯某些檔案並開啟更強的最佳化功能,或是停用最佳化功能。

注意:如果部分檔案選擇性地以偵錯符號編譯,則符號可能會在連結期間遭到移除。您可以設定 --strip=never 避免這種情況。

語法[+-]regex[,[+-]regex]...@option[,option]... 其中 regex 代表規則運算式,前面可加上 + 來識別 include 模式,而 - 則代表排除模式。option 代表傳送至 C++ 編譯器的任意選項。如果選項包含 ,,則必須加上引號,如 \,。選項也可以包含 @,因為只有第一個 @ 用來分隔規則運算式與選項。

範例--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs 會將 -O0-fprofile-arcs 選項新增至 //foo/ 中所有 .cc 檔案的 C++ 編譯器指令列中 (file.cc 除外)。

--dynamic_mode=mode

判斷 C++ 二進位檔是否會動態連結,並與建構規則上的連結靜態屬性互動。

模式:

  • auto:轉譯為依附平台模式;default 適用於 Linux,off 則適用於 cygwin。
  • default:允許瀏覽器選擇是否要動態連結。詳情請參閱「連結靜態」。
  • fully:動態連結所有目標。這樣可以加快連結時間,並縮減產生的二進位檔。
  • off:在大部分靜態模式下連結所有目標。如果將 -static 設為連結最佳化,目標會變更為完全靜態。

--fission (yes|no|[dbg][,opt][,fastbuild])

啟用 Fission,將 C++ 偵錯資訊寫入專屬的 .dwo 檔案而非 .o 檔案,否則會寫入專屬 .dwo 檔案。這樣可以大幅減少連結的輸入大小,並減少連結時間。

當設為 [dbg][,opt][,fastbuild] (例如:--fission=dbg,fastbuild) 時,只有指定的編譯模式組合會啟用 Fision。這適用於 bazelrc 設定。如果設為 yes,系統會全面啟用 Fission。如果設為 no,系統會全面停用 Fission。預設值為 no

--force_ignore_dash_static

如果設定這個旗標,系統會忽略 cc_* 規則 BUILD 檔案連結選擇的所有 -static 選項。這僅適用於 C++ 強化版本的解決方法。

--[no]force_pic

啟用後,所有 C++ 編譯都會產生與位置無關的程式碼 (「-fPIC」),連結偏好 PIC 預先建構程式庫而非非 PIC 程式庫,而連結會產生位置獨立的執行檔 (「-pie」)。這項設定預設為停用。

--android_resource_shrinking

選擇是否要針對 android_binary 規則執行資源縮減。設定 android_binary 規則的 shrink_resources 屬性預設值;詳情請參閱該規則的說明文件。預設為關閉。

--custom_malloc=malloc-library-target

如果有指定,請一律使用指定的 Malloc 實作項目,並覆寫所有 malloc="target" 屬性,包括使用預設值的目標 (不得指定任何 malloc)。

--crosstool_top=label

這個選項會指定在建構期間用於所有 C++ 編譯的 Crosstool 編譯器套件位置。Bazel 會尋找該位置是否有 CROSSTOOL 檔案,並利用該檔案自動決定 --compiler 的設定。

--host_crosstool_top=label

如未指定,Bazel 就會使用 --crosstool_top 的值在執行設定中編譯程式碼,例如在建構期間執行的工具。這個旗標的主要用途是啟用跨編譯。

--apple_crosstool_top=label

在 objc*、iOS* 和 apple* 規則的遞移 deps 中編譯 C/C++ 規則的 Cross 工具。對於這些目標,這個標記會覆寫 --crosstool_top

--compiler=version

這個選項會指定在建構期間編譯二進位檔時使用的 C/C++ 編譯器版本 (例如 gcc-4.1.0)。如要使用自訂 Crosstool 進行建構,建議您使用 CROSSTOOL 檔案,不要指定這個旗標。

--android_sdk=label

已淘汰,請勿直接指定。

這個選項會指定用於建構任何 Android 相關規則的 Android SDK/平台工具鍊和 Android 執行階段程式庫。

如果 WORKSPACE 檔案中有定義 android_sdk_repository 規則,系統將自動選取 Android SDK。

--java_toolchain=label

這個選項會指定用於編譯 Java 來源檔案的 java_toolchain 標籤。

--host_java_toolchain=label

如未指定,bazel 使用 --java_toolchain 的值在執行設定中編譯程式碼,例如用於建構期間執行的工具。這個旗標的主要用途是啟用跨編譯。

--javabase=(label)

這個選項會設定 Java 基本安裝項目的標籤,以便用於 bazel runbazel 測試,以及由 java_binaryjava_test 規則建構的 Java 二進位檔使用。JAVABASEJAVA 「Make」變數衍生自這個選項。

--host_javabase=label

這個選項會設定要在執行設定中使用的基本 Java 安裝作業標籤,例如主機建構工具包括 JavaBuilder 和 Singlejar。

這項操作不會選取用於編譯 Java 來源檔案的 Java 編譯器。您可以透過設定 --java_toolchain 選項來選取編譯器。

執行策略

這些選項會影響 Bazel 執行建構作業的方式。這些限制應該不會對版本產生的輸出檔案造成任何重大影響。通常這些影響的主要影響在於建構速度。

--spawn_strategy=strategy

這個選項可控制指令的執行位置和方式。

  • standalone 會使指令做為本機子程序執行。這個值已淘汰。請改用「local」。
  • sandboxed 會導致指令在本機機器的沙箱中執行。這需要在 srcsdatatools 屬性中,將所有輸入檔案、資料依附元件和工具列為直接依附元件。根據預設,Bazel 會在支援沙箱執行作業的系統中啟用本機沙箱機制。
  • local 會使指令做為本機子程序執行。
  • worker 會導致使用永久工作站執行指令 (如果有的話)。
  • docker 會導致指令在本機電腦的 Docker 沙箱內執行。這需要安裝 Docker。
  • remote 會讓指令從遠端執行,只有在已個別設定遠端執行程式的情況下才能使用。

--strategy mnemonic=strategy

這個選項可控制指令的執行位置和方式,以個別助測為基礎覆寫 --spawn_strategy--genrule_strategy。如要瞭解支援的策略及效果,請參閱 --spawn_strategy

--strategy_regexp=<filter,filter,...>=<strategy>

這個選項會指定應使用哪種策略,執行說明符合特定 regex_filter 的指令。如要進一步瞭解 regex_filter 比對,請參閱 --per_file_copt。如要瞭解支援的策略及效果,請參閱 --spawn_strategy

系統會使用符合說明的最後一個 regex_filter。此選項會覆寫用於指定策略的其他旗標。

  • 例如:--strategy_regexp=//foo.*\\.cc,-//foo/bar=local 表示如果動作的說明符合 //foo.*.cc,而非 //foo/bar,就會使用 local 策略執行動作。
  • 例如: --strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed 使用 sandboxed 策略執行「Compiling //foo/bar/baz」,而反轉順序則會使用 local 執行。
  • 範例:--strategy_regexp='Compiling.*/bar=local,sandboxed' 會使用 local 策略執行「Compiling //foo/bar/baz」;如失敗,則會改回使用 sandboxed

--genrule_strategy=strategy

此為 --strategy=Genrule=strategy 已淘汰的簡寫。

--jobs=n (-j)

此選項採用整數引數,指定在建構執行階段期間應同時執行的工作數量限制。

--progress_report_interval=n

Bazel 會定期針對尚未完成的工作 (例如長時間執行的測試) 輸出進度報告。這個選項會設定報表頻率,系統每 n 秒列印進度,

預設值為 0,代表累加演算法:第一份報表會在 10 秒後輸出,接著會在 30 秒後輸出,之後系統每分鐘會回報一次進度。

如果 bazel 使用 --curses 指定的遊標控制項,系統會每秒回報進度。

--local_{ram,cpu}_resources resources or resource expression

這些選項會指定 Bazel 在安排建構和測試活動以在本機執行時,應考慮的本機資源數量 (以 MB 為單位的 RAM 和 CPU 邏輯核心數量)。這些值可接受整數,或是關鍵字 (HOST_RAM 或 HOST_CPUS) 後面會選擇性加上 [-|*float] (例如 --local_cpu_resources=2--local_ram_resources=HOST_RAM*.5--local_cpu_resources=HOST_CPUS-1)。標記各自獨立,且可設定一個或兩者皆設定。根據預設,Bazel 會從本機系統的設定估算 RAM 和 CPU 核心數量。

這個選項預設為啟用,指定是否應在輸出目錄中建構測試和二進位檔的執行檔案符號連結。使用 --nobuild_runfile_links 可以驗證所有目標是否都能編譯,而不會產生建構執行檔案樹狀結構的負擔。

執行測試 (或應用程式) 時,執行階段資料依附元件會集中在同一處收集。在 Bazel 的輸出樹狀結構中,這個「執行檔案」樹狀結構通常根源為對應二進位檔或測試的同層。在測試執行期間,您可以透過 $TEST_SRCDIR/workspace/packagename/filename 格式的路徑存取執行檔案。執行檔案樹狀結構可確保測試能存取其已宣告依附的所有檔案,而非其他任何檔案。根據預設,系統會建構一組必要檔案的符號連結來實作執行檔案樹狀結構。隨著連結集增加,這項作業的成本也會大幅增加,對於某些大型建構作業而言,這麼做可能會大幅縮短整體建構時間,特別是因為每個測試 (或應用程式) 都需要專屬的執行檔案樹狀結構。

--[no]build_runfile_manifests

這個選項預設為啟用,指定是否要將 runfiles 資訊清單寫入輸出樹狀結構。停用它表示 --nobuild_runfile_links

從遠端執行測試時,可以選擇停用此功能,因為系統會從記憶體內資訊清單遠端建立執行檔案樹狀結構。

--[no]discard_analysis_cache

啟用此選項後,Bazel 會在執行作業開始前捨棄分析快取,進而釋出額外的記憶體 (約 10%) 供執行階段使用。缺點是進一步漸進式的漸進式建構速度會變慢。另請參閱記憶體節省模式

--[no]keep_going (-k)

與 GNU Make 相同,當遇到第一次錯誤時,建構的執行階段即會停止。有時候,即使發生錯誤,也建議您盡可能嘗試建構。這個選項會啟用該行為,並指定該行為後,建構作業就會嘗試建構所有先決條件成功建構的目標,但會忽略錯誤。

雖然這個選項通常會與建構的執行階段相關聯,但也會影響分析階段:如果建構指令中指定了多個目標,但成功分析只有部分目標,除非指定 --keep_going,否則建構作業就會停止並顯示錯誤,在這種情況下,建構作業將繼續進入執行階段,但只有成功分析的目標才會發生。

--[no]use_ijars

這個選項會變更 Bazel 編譯 java_library 目標的方式。Bazel 不會使用 java_library 編譯依附元件的輸出內容java_library輸出內容,而是建立一個僅包含非私人成員 (公開、受保護與預設 (套件) 存取方法和欄位) 的介面 jar,並使用介面 jar 檔案編譯相依目標。這樣一來,如果只對類別中的方法主體或私人成員進行變更,就可以避免重新編譯。

--[no]interface_shared_objects

這個選項會啟用「介面共用物件」,讓二進位檔和其他共用程式庫依附於共用物件的「介面」,而非實作物件。如果 Bazel 只會變更實作,以避免在不必要的共用程式庫上重建目標。

輸出選項

這些選項可決定要建構或測試的內容。

--[no]build

這個選項會啟動建構的執行階段;這個階段預設為開啟。如果關閉這項設定,系統會略過執行階段,只有前兩個階段會執行載入和分析作業。

不需要實際建構任何東西,這個選項就能用來驗證 BUILD 檔案及偵測輸入中的錯誤。

--[no]build_tests_only

如有指定,Bazel 只會建構在執行 *_testtest_suite 規則時未依其大小逾時標記語言等條件而未篩除的資源。如有指定,Bazel 將忽略指令列中指定的其他目標。此選項預設為停用,且 Bazel 會建構要求的所有內容,包括從測試中篩除的 *_testtest_suite 規則。這非常實用,因為執行 bazel test --build_tests_only foo/... 可能無法偵測 foo 樹狀結構中的所有建構中斷情形。

--[no]check_up_to_date

這個選項會導致 Bazel 不要執行建構作業,只是會檢查所有指定的目標是否為最新版本。如果已啟用,建構作業就會照常完成。然而,如果有任何檔案過時 (而不是建構),系統會回報錯誤,且建構失敗。此方法可能有助於確定建構作業的執行時間是否比來源編輯作業 (例如:預先提交檢查) 更近,而不會產生建構費用。

另請參閱 --check_tests_up_to_date

--[no]compile_one_dependency

編譯引數檔案的單一依附元件。這適用於 IDE 中的語法檢查來源檔案,例如重新建構依附於來源檔案的單一目標,以便在編輯/建構/測試週期中盡早偵測錯誤。這個引數會影響所有非標記引數的解譯方式:每個引數都必須是檔案目標標籤或相對於目前工作目錄的純檔案名稱,然後建立一項依附於每個來源檔案名稱的規則。如果是 C++ 和 Java 來源,建議選擇位於相同語言空間的規則。如有多個偏好相同的規則,系統會選擇在 BUILD 檔案中第一個出現的規則。明確命名的目標模式未參照來源檔案會導致錯誤。

--save_temps

--save_temps 選項會使要儲存編譯器的臨時輸出內容。包括 .s 檔案 (組合器程式碼)、.i (預先處理的 C) 和 .ii (預先處理的 C++) 檔案。這些輸出內容通常很適合用於偵錯。系統只會針對指令列中指定的目標組合產生臨時溫度。

--save_temps 旗標目前僅適用於 cc_* 規則。

為確保 Bazel 會輸出其他輸出檔案的位置,請檢查您的 --show_result n 設定是否夠高。

--build_tag_filters=tag[,tag]*

如果指定,Bazel 只會建構至少具備一個必要標記的目標 (如果已指定任何一個標記),且沒有任何排除標記。建構標記篩選器會指定為以半形逗號分隔的標記關鍵字清單,您可以選擇在前面加上「-」符號,用來表示排除的標記。必要標記也可能在前面加上「+」符號。

執行測試時,Bazel 會忽略測試目標的 --build_tag_filters,即使測試目標不符合這個篩選條件,仍會執行。為避免建構,請使用 --test_tag_filters 篩選測試目標,或明確排除測試目標。

--test_size_filters=size[,size]*

如有指定,Bazel 只會測試 (如果也指定了 --build_tests_only,則為建構) 只會測試指定大小的目標。測試大小篩選器會指定為逗號分隔的清單,包含允許的測試大小值 (小、中、大或大),可選擇在前面加上「-」符號,用來表示排除的測試大小。比如

  % bazel test --test_size_filters=small,medium //foo:all

以及

  % bazel test --test_size_filters=-large,-enormous //foo:all

只會測試 //foo 中的小型和中型測試。

根據預設,系統不會套用測試大小篩選功能。

--test_timeout_filters=timeout[,timeout]*

如有指定,Bazel 只會測試 (如果同時指定 --build_tests_only,則為建構) 只會測試設有指定逾時時間的目標。測試逾時篩選器會指定為以逗號分隔的允許的測試逾時值 (短、中率、長或永恆值),可選擇在前面加上「-」符號,用於表示排除的測試逾時。如需語法範例,請參閱 --test_size_filters

根據預設,系統不會套用測試逾時篩選功能。

--test_tag_filters=tag[,tag]*

如有指定,Bazel 只會測試 (如果同時指定 --build_tests_only,則為建構) 只會測試具有至少一個必要標記 (如果已指定任何一項) 且沒有任何排除標記的測試目標。測試標記篩選器會指定為以半形逗號分隔的標記關鍵字清單,您可以選擇在前面加上「-」符號,用來表示排除的標記。必要標記也可能在前面加上「+」符號。

比如

  % bazel test --test_tag_filters=performance,stress,-flaky //myproject:all

會測試標有 performancestress 標記,但「沒有」flaky 標記標記的目標。

根據預設,系統不會套用測試代碼篩選功能。請注意,您也可以透過這種方式篩選測試的 sizelocal 標記。

--test_lang_filters=string[,string]*

指定參照測試規則類別名稱的字串清單 (以半形逗號分隔)。如要參照規則類別 foo_test,請使用「foo」字串。Bazel 只會測試 (如果同時指定了 --build_tests_only,也會建構) 只會參照所參照規則類別的目標。如要排除這些目標,請使用「-foo」字串。比如

  % bazel test --test_lang_filters=foo,bar //baz/...

只會測試 //baz/...foo_testbar_test 例項的目標。

  % bazel test --test_lang_filters=-foo,-bar //baz/...

會測試 //baz/... 中的所有目標 (foo_testbar_test 執行個體除外)。

--test_filter=filter-expression

指定測試執行器可以用來挑選要執行的測試子集。系統會建構叫用中指定的所有目標,但視運算式而定,系統只能執行部分目標。在某些情況下,系統只會執行特定測試方法。

filter-expression 的具體解釋取決於負責執行測試的測試架構。可以是 glob、子字串或 regexp。--test_filter 是用來傳遞不同的 --test_arg 篩選器引數,但並非所有架構都支援。

詳細程度

這些選項可控管 Bazel 輸出的詳細程度,無論是終端機,還是其他記錄檔都沒問題。

--explain=logfile

此選項需要檔案名稱引數,因此 bazel build 執行階段中的依附元件檢查工具會針對每個建構步驟說明其執行原因或是否為最新版本。此說明會寫入 logfile

如果您在發生非預期的重新建構時,這個選項可協助您瞭解原因。將其新增至 .bazelrc,以便對所有後續建構執行記錄作業,並在出現未預期的執行步驟時檢查記錄。此選項可能會對效能造成些許負面影響,因此建議您在不再需要時移除此選項。

--verbose_explanations

啟用 --explain 選項時,這個選項可提高說明詳細程度。

具體來說,如果詳細說明已啟用,且輸出檔案因用於建構的指令已變更而重建,則說明檔案中的輸出內容會包含新指令的完整詳細資料 (至少適用於大多數指令)。

如果使用這個選項,產生的說明檔案長度可能會大幅增加,使用 --explain 也會對效能產生負面影響。

如果未啟用 --explain,則 --verbose_explanations 不會有任何作用。

--profile=file

這個選項會使用檔案名稱引數,導致 Bazel 將剖析資料寫入檔案。接著,您可以使用 bazel analyze-profile 指令分析或剖析資料。建構設定檔有助於瞭解 Bazel 的 build 指令花費時間在何處。

--[no]show_loading_progress

這個選項會使 Bazel 輸出封裝的進度訊息,如果停用,系統就不會顯示訊息。

--[no]show_progress

這個選項會顯示進度訊息;此功能預設為開啟。如果停用這項設定,系統會隱藏進度訊息。

--show_progress_rate_limit=n

這個選項會讓 bzel 每 n 秒最多顯示一則進度訊息,其中 n 是實數。這個選項的預設值為 0.02,這表示 bazel 會將進度訊息限制為每 0.02 秒 1 次。

--show_result=n

這個選項可控制 bazel build 指令結尾的結果資訊的列印作業。根據預設,如果指定了單一建構目標,Bazel 會顯示訊息,指出目標是否已成功將最新進展,如果有,也會列出目標建立的輸出檔案清單。如果指定多個目標,結果就不會顯示。

雖然結果資訊可能適用於單一或少數目標的建構作業,但在大型建構作業 (例如整個頂層專案樹狀結構) 中,這項資訊可能會令人不知所措,讓您分心;這個選項可讓您加以控管。--show_result 會採用整數引數,這是系統應列印完整結果資訊的目標數量上限。預設值為 1。如果超過這個門檻,系統就不會針對個別目標顯示任何結果資訊。因此,零會一律禁止結果資訊,而極大的值會導致系統持續顯示結果。

如果使用者經常在建構少量目標 (例如在編譯編輯測試週期期間) 和大量目標 (例如建立新工作區或執行迴歸測試) 之間進行替代時,可能會想選擇介於其中的值。如果是前者,結果資訊非常有用,而後者則較少。與所有選項一樣,可以透過 .bazelrc 檔案以隱含方式指定。

系統會列印這些檔案,方便您輕鬆複製檔案名稱並貼到殼層,以執行建構的執行檔。每個目標的「最新」或「失敗」訊息,可由驅動建構作業的指令碼輕鬆剖析。

--sandbox_debug

這個選項會在使用沙箱機制執行動作時,造成 Bazel 列印額外的偵錯資訊。這個選項也會保留沙箱目錄,以便檢查執行期間動作可見的檔案。

--subcommands (-s)

這個選項會讓 Bazel 的執行階段先輸出每個指令的完整指令列,再執行該指令。

  >>>>> # //examples/cpp:hello-world [action 'Linking examples/cpp/hello-world']
  (cd /home/johndoe/.cache/bazel/_bazel_johndoe/4c084335afceb392cfbe7c31afee3a9f/bazel && \
    exec env - \
    /usr/bin/gcc -o bazel-out/local-fastbuild/bin/examples/cpp/hello-world -B/usr/bin/ -Wl,-z,relro,-z,now -no-canonical-prefixes -pass-exit-codes -Wl,-S -Wl,@bazel-out/local_linux-fastbuild/bin/examples/cpp/hello-world-2.params)

如果可以,指令會以 Bourne 殼層相容的語法列印,以便您複製這些指令,然後貼到殼層指令提示中。(為保護殼層免受 cdexec 呼叫影響,我們會提供左右括號;請務必複製!)不過,部分指令會在 Bazel 內部實作,例如建立符號連結樹狀結構。系統不會顯示這類指令列內容。

系統會傳遞 --subcommands=pretty_print 以清單形式列印指令引數,而不是單行顯示。這將有助於讓冗長的指令列更清晰易讀。

另請參閱下方的 --verbose_failures

如要將子指令記錄為適合工具格式的檔案,請參閱 --execution_log_json_file--execution_log_binary_file

--verbose_failures

這個選項會使 Bazel 的執行階段列印失敗的指令的完整指令列。對失敗的建構作業進行偵錯時,這項功能非常重要。

失敗的指令會以 Bourne 殼層相容的語法列印,適合用來複製及貼上殼層提示。

工作區狀態

使用這些選項來「封裝」Bazel 建構的二進位檔:將其他資訊嵌入二進位檔,例如來源控制修訂版本或其他工作區相關資訊。您可以將此機制與支援 stamp 屬性的規則搭配使用,例如 genrulecc_binary 等。

--workspace_status_command=program

這個標記可讓您指定 Bazel 在每個建構作業之前執行的二進位檔。程式可以回報工作區狀態的相關資訊,例如目前的來源控制修訂版本。

該標記的值必須是原生程式的路徑。在 Linux/macOS 上,這可能是任何執行檔。在 Windows 上,這必須是原生二進位檔,通常是「.exe」、「.bat」或「.cmd」檔案。

程式應在標準輸出輸出零或多個鍵/值組合,每行一個項目,並在結尾為零 (否則建構失敗)。鍵名可以是任何名稱,但只能使用大寫字母和底線。鍵名後方的第一個空格可分隔鍵與值。這個值是線條的其餘部分 (包括其他空白字元)。鍵和值都無法橫跨多行。鍵不得重複。

Bazel 將金鑰分割成兩個值區:「穩定」和「易變性」。(「stable」和「可變性」這兩個名稱有點直覺易懂,所以別想得太在意)。

然後,Bazel 會將鍵/值組合寫入兩個檔案:

  • bazel-out/stable-status.txt 包含鍵名稱開頭為 STABLE_ 的所有鍵和值
  • bazel-out/volatile-status.txt 包含其餘的鍵及其值

合約內容如下:

  • 請盡量避免變更「stable」鍵的值。如果 bazel-out/stable-status.txt 的內容有所變更,Bazel 就會撤銷依附於這些動作的動作。換句話說,如果穩定的金鑰值發生變化,Bazel 就會重新執行打印的動作。因此,穩定狀態不應包含時間戳記等項目,因為這些時間戳記會變更所有時間,並會導致 Bazel 在每次建構時重新執行戳記的動作。

    Bazel 一律會輸出下列穩定的金鑰:

    • BUILD_EMBED_LABEL--embed_label的值
    • BUILD_HOST:執行 Bazel 的主機名稱
    • BUILD_USER:Bazel 執行的使用者名稱
  • 「易變性」的鍵值可能會經常變動。Bazel 預期他們會隨時變更 (例如時間戳記都會變更),並且定期更新 bazel-out/volatile-status.txt 檔案。不過,為了避免一直都重新執行戳記動作,Bazel 可能會假裝易變性檔案永遠不會變更。換句話說,如果揮發性狀態檔案是唯一內容已變更的檔案,Bazel 就不會撤銷依附於這個檔案的動作。如果動作的其他輸入內容有所改變,Bazel 就會重新執行該動作,並會看到更新後的易變狀態,但只有變動狀態改變不會使動作失效。

    Bazel 一律會輸出下列易變的金鑰:

    • BUILD_TIMESTAMP:建構時間,從 Unix Epoch 紀元時間起算 (System.currentTimeMillis() 的值除以一千)
    • FORMATTED_DATE:建構時間的格式為 yyyy MMM d HH mm ss EEE(例如 2023 年 6 月 2 日 44 日 29 星期五,世界標準時間)。

在 Linux/macOS 上,您可以傳遞 --workspace_status_command=/bin/true 以停用擷取工作區狀態,因為 true 不會執行任何動作 (使用 0 時結束),且不會列印任何輸出內容。在 Windows 上,您可以傳遞 MSYS true.exe 的路徑以達到相同效果。

如果工作區狀態指令因任何原因而失敗 (結束非零),建構作業就會失敗。

在 Linux 上使用 Git 的程式範例:

#!/bin/bash
echo "CURRENT_TIME $(date +%s)"
echo "RANDOM_HASH $(cat /proc/sys/kernel/random/uuid)"
echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"
echo "STABLE_USER_NAME $USER"

請使用 --workspace_status_command 傳遞這個程式的路徑,而穩定狀態檔案會包含 STABLE 行,且可變動狀態檔案將包含其餘行。

--[no]stamp

這個選項會與 stamp 規則屬性搭配使用,可控制是否要在二進位檔中嵌入建構資訊。

您可使用 stamp 屬性,依規則明確啟用或停用戳記。如需詳細資訊,請參閱建構百科全書。當規則設定 stamp = -1 (*_binary 規則的預設選項) 時,此選項會決定是否要啟用戳記。

無論這個選項或 stamp 屬性為何,Bazel 一律不會時間戳記為針對執行設定建構的二進位檔。在設定 stamp = 0 (*_test 規則的預設值) 的情況下,無論 --[no]stamp 為何,戳記都會停用。如果目標的依附元件未變更,指定 --stamp 並不會強制要求重新建構目標。

一般來說,建議設定 --nostamp 來提升建構效能,因為這可以降低輸入波動,並盡可能提高建構快取。

平台

使用這些選項即可控管設定建構作業運作方式的主機和目標平台,以及控管 Bazel 規則可使用的執行平台和工具鍊。

請參閱平台工具鍊的背景資訊。

--platforms=labels

平台規則標籤,用於說明目前指令的目標平台。

--host_platform=label

描述主機系統的平台規則標籤。

--extra_execution_platforms=labels

可做為執行平台來執行動作的平台。平台可以根據確切目標或目標模式指定。系統會先考量這些平台,再透過 register_execution_platforms() 在 WORKSPACE 檔案中宣告的平台。這個選項會依照優先順序接受以半形逗號分隔的平台清單。如果標記已多次傳遞,則最新的覆寫值。

--extra_toolchains=labels

在工具鍊解析期間要考量的工具鍊規則。工具鍊可以根據確切目標或目標模式指定。系統會先考量這些工具鍊,再透過 register_toolchains() 在 WORKSPACE 檔案中宣告的工具鍊。

--toolchain_resolution_debug=regex

如果工具鍊類型與規則運算式相符,請在尋找工具鍊時列印偵錯資訊。如有多個規則運算式,可以半形逗號分隔。您可以在開頭使用 - 否定規則運算式。這或許有助於 Bazel 或 Starlark 規則因缺少工具鍊而導致偵錯失敗。

其他

--flag_alias=alias_name=target_path

這個便利旗標用於將較長的 Starlark 版本設定繫結至較短的名稱。詳情請參閱「Starlark 設定」。

變更系統產生的便利符號連結的前置字串。符號連結前置字串的預設值為 bazel-,會建立符號連結 bazel-binbazel-testlogsbazel-genfiles

如果因任何原因無法建立符號連結,系統會發出警告,但建構作業仍視為成功。特別是,這可讓您在唯讀目錄中建構,或是在您沒有權限寫入的目錄中建構。建構完成後,如果符號連結指向預期位置,則顯示資訊訊息中的任何路徑只會使用符號連結相關簡短形式;換句話說,即使您無法依賴已建立的符號連結,也可以取得這些路徑的正確性。

這個選項的部分常見值:

  • 禁止建立符號連結: --symlink_prefix=/ 會導致 Bazel 不會建立或更新任何符號連結,包括 bazel-outbazel-<workspace> 符號連結。如要完全禁止建立符號連結,請使用這個選項。

  • 減少雜亂情況: --symlink_prefix=.bazel/ 會導致 Bazel 在隱藏的目錄 .bazel 中建立名為 bin (等) 的符號連結。

--platform_suffix=string

在設定簡稱中新增後置字串,用於決定輸出目錄。如果將這個選項設為不同的值,系統會將檔案移入不同的目錄。舉例來說,如果建構作業將彼此的輸出檔案使用破壞性降低,或為了比較方便而保持輸出檔案,就能提高這類建構作業的快取命中率。

--default_visibility=(private|public)

測試 Oracle 預設瀏覽權限變更的暫時標記。不適用於一般用途,但記錄為完整性而已。

--starlark_cpu_profile=_file_

此標記 (其值為檔案名稱) 會使 Bazel 收集所有 Starlark 執行緒的 CPU 使用率統計資料,並以 pprof 格式寫入設定檔。

使用這個選項有助於找出因運算過多導致載入和分析速度緩慢的 Starlark 函式。例如:

$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
$ pprof /tmp/pprof.gz
(pprof) top
Type: CPU
Time: Feb 6, 2020 at 12:06pm (PST)
Duration: 5.26s, Total samples = 3.34s (63.55%)
Showing nodes accounting for 3.34s, 100% of 3.34s total
      flat  flat%   sum%        cum   cum%
     1.86s 55.69% 55.69%      1.86s 55.69%  sort_source_files
     1.02s 30.54% 86.23%      1.02s 30.54%  expand_all_combinations
     0.44s 13.17% 99.40%      0.44s 13.17%  range
     0.02s   0.6%   100%      3.34s   100%  sorted
         0     0%   100%      1.38s 41.32%  my/project/main/BUILD
         0     0%   100%      1.96s 58.68%  my/project/library.bzl
         0     0%   100%      3.34s   100%  main

對於相同資料的不同檢視畫面,請嘗試使用 pprof 指令 svgweblist

使用 Bazel 執行版本

Bazel 在開發週期期間和發布工程師都會使用 Bazel,用於準備部署至實際工作環境的二進位檔。本節提供使用 Bazel 的發布工程師相關提示清單。

重要選項

使用 Bazel 執行發布建構作業,也會發生和其他執行建構作業的指令碼相同的問題。詳情請參閱從指令碼呼叫 Bazel。我們特別建議您採用下列選項:

這些選項也很重要:

  • --package_path
  • --symlink_prefix:如要管理多種設定的建構作業,以不同的 ID (例如「64 位元」和「32 位元」) 區分各版本可能會很方便。這個選項會區別 bazel-bin (等) 符號連結。

執行測試

如要使用 bazel 建構及執行測試,請輸入 bazel test,後面加上測試目標的名稱。

根據預設,這個指令會同時執行建構和測試活動,建構所有指定目標 (包括指令列中指定的任何非測試目標),並在建構 *_testtest_suite 目標時立即測試其必要條件,也就是說,測試執行作業會與建構作業交錯。這樣做通常可以大幅提升速度。

bazel test」的選項

--cache_test_results=(yes|no|auto) (-t)

如果將這個選項設為「auto」(預設值),則 Bazel 只會在符合下列任一情況時重新執行測試:

  • Bazel 會偵測測試或其依附元件的變更
  • 測試標示為 external
  • --runs_per_test 請求了多項測試執行
  • 測試失敗。

如果設為「否」,所有測試將無條件執行。

如果設為「是」,快取行為將與自動相同,但可能會快取測試失敗並使用 --runs_per_test 執行測試。

如果在 .bazelrc 檔案中預設啟用這個選項,使用者就能在 -t (開啟) 或 -t- (關閉) 中輕鬆覆寫特定執行作業中的預設值。

--check_tests_up_to_date

這個選項會指示 Bazel 不要執行測試,而只會檢查並回報快取的測試結果。如果有任何測試先前未建構及執行,或者其測試結果過時 (例如原始碼或建構選項已變更),則 Bazel 會回報錯誤訊息 (「測試結果並非最新」訊息),會將測試的狀態記錄為「無狀態」(如果已啟用色彩輸出),並且會傳回非零狀態代碼。

這個選項也會表示 [--check_up_to_date](#check-up-to-date) 行為。

這個選項可能適合用於預先提交檢查。

--test_verbose_timeout_warnings

如果測試的逾時時間遠超過測試的實際執行時間,這個選項會指示 Bazel 明確警告使用者。雖然測試的逾時情形應設定為不不穩定,但如果測試的逾時時間過長,可能會隱藏超出預期外的實際問題。

舉例來說,通常在一或兩分鐘內執行的測試不應有「ETERNAL」或「LONG」的逾時狀況,因為這些逾時都太過極端。

這個選項非常實用,可協助使用者決定良好的逾時值,或檢查現有的逾時值。

--[no]test_keep_going

根據預設,所有測試都會執行完畢。如果停用此標記,則任何未傳遞的測試都會取消建構。系統不會執行後續的建構步驟和測試叫用,也會取消執行中的叫用。請勿同時指定 --notest_keep_going--keep_going

--flaky_test_attempts=attempts

這個選項可指定測試因任何原因失敗時要嘗試的次數上限。一開始失敗,但最終順利執行的測試會在測試摘要中回報為 FLAKY。不過,在識別 Bazel 結束程式碼或通過的測試總數時,會被視為已傳遞。所有允許嘗試失敗的測試都會視為失敗。

根據預設 (如未指定此選項,或設為預設值),一般測試只能嘗試一次,而設定 flaky 屬性的測試規則則只可嘗試一次。您可以指定整數值來覆寫測試嘗試次數上限,Bazel 允許最多執行 10 次測試,藉此防止系統遭到濫用。

--runs_per_test=[regex@]number

這個選項可指定每次測試的執行次數。所有測試執行作業都會視為個別的測試 (將分別套用至各項測試)。

目標執行失敗時的狀態取決於 --runs_per_test_detects_flakes 標記的值:

  • 如未設定,任何失敗的執行作業都會導致整個測試失敗。
  • 如果有,而相同資料分割的兩次執行作業傳回「通過」和「失敗」,該測試就會收到不穩定的狀態 (除非有其他失敗的執行作業導致失敗)。

如果指定單一數字,所有測試將執行該數字多次。您也可以使用語法 regex@number 指定規則運算式。這會將 --runs_per_test 的效果限制為與規則運算式相符的目標 (--runs_per_test=^//pizza:.*@4 會執行 //pizza/ 4 次下的所有測試)。這個 --runs_per_test 形式可以指定一次以上。

--[no]runs_per_test_detects_flakes

如果指定此選項 (預設為未指定),Bazel 會透過 --runs_per_test 偵測不穩定的測試資料分割。如果單一資料分割的一或多項執行作業失敗,且相同的資料分割程序一或多項執行作業失敗,則目標會被視為因有標記而發生問題。如果未指定,目標會回報失敗狀態。

--test_summary=output_style

指定測試結果摘要的顯示方式。

  • 如果測試失敗,short 會輸出每個測試的結果,以及包含測試輸出內容的檔案名稱。此為預設值。
  • terse 例如 short,但更短:僅顯示未通過的測試相關資訊。
  • detailed 會輸出每個失敗的測試案例,而不是每個測試。系統會省略測試輸出檔案名稱。
  • none 不會列印測試摘要。

--test_output=output_style

指定測試輸出內容的顯示方式:

  • summary 會顯示每項測試是否通過的摘要。也會顯示失敗測試的輸出記錄檔名稱。摘要會顯示在建構作業的結尾處 (在建構期間,當測試開始、通過或失敗時,只會看到簡單的進度訊息)。此為預設行為。
  • errors 會在測試完成後,僅將失敗的測試中彙整的 stdout/stderr 輸出內容傳送到 stdout,確保同時測試的測試輸出內容不會彼此交錯。根據上述的摘要輸出,列印版本的摘要。
  • allerrors 類似,但會顯示所有測試的輸出內容,包括通過測試的輸出內容。
  • streamed 會即時串流每個測試的 stdout/stderr 輸出內容。

--java_debug

這個選項會讓 Java 測試的 Java 虛擬機器會等待符合 JDWP 規範偵錯工具的連線,再開始測試。此選項表示 --test_output=streamed

--[no]verbose_test_summary

系統會預設啟用此選項,因此測試摘要會顯示測試時間和其他額外資訊 (例如測試嘗試次數)。如果指定 --noverbose_test_summary,測試摘要只會包含測試名稱、測試狀態和快取測試指標,且會盡可能將經過格式化,不超過 80 個半形字元。

--test_tmpdir=path

為本機執行的測試指定臨時目錄。每項測試都會在這個目錄內的個別子目錄中執行。系統會在每個 bazel test 指令的開頭清除該目錄。根據預設,bazel 會將這個目錄放在 Bazel 輸出基本目錄底下。

--test_timeout=seconds--test_timeout=seconds,seconds,seconds,seconds

使用指定的秒數值做為新的逾時值,覆寫所有測試的逾時值。如果只提供一個值,該值將用於所有測試逾時類別。

或者,您也可以提供四個以半形逗號分隔的值,針對短期、中度、長效測試和永恆測試 (依此順序) 指定個別逾時。不論是何種格式,任何測試大小的測試大小都會替換為預設的逾時值 (由「編寫測試」頁面定義)。根據預設,Bazel 會從測試大小推測逾時限制 (無論是隱含或明確設定),藉此在所有測試中使用這些逾時設定。

針對明確指出逾時類別與大小不同的測試,測試會收到與大小標記默示設定該逾時的值。所以,如果測試大小為「小」且宣告「長」逾時,其有效逾時將與「大型」測試沒有明確逾時的情況相同。

--test_arg=arg

將指令列選項/旗標/引數傳遞至每個測試程序。這個選項可多次用於傳遞多個引數。例如 --test_arg=--logtostderr --test_arg=--v=3

請注意,與 bazel run 指令不同,您無法像在 bazel test -- target --logtostderr --v=3 中直接傳遞測試引數。這是因為系統會將傳送至 bazel test 的極端引數解讀為額外的測試目標。也就是說,系統會將 --logtostderr--v=3 解讀為測試目標。由於 bazel run 指令只接受一個目標,因此沒有這種模稜兩可的情況。

--test_arg 可以傳遞至 bazel run 指令,但系統會忽略,除非執行的目標是測試目標。(與其他標記一樣,如果在 -- 權杖之後於 bazel run 指令中傳遞,則不會由 Bazel 處理,而是一律轉送至已執行的目標。

--test_env=variable=_value_--test_env=variable

指定每項測試必須插入測試環境的其他變數。如未指定 value,系統會繼承用於啟動 bazel test 指令的殼層環境。

您可以使用 System.getenv("var") (Java)、getenv("var") (C 或 C++),在測試中存取環境。

--run_under=command-prefix

此指定用於指定測試執行器會在執行前插入測試指令前面的前置字串。command-prefix 會使用 Bourne 殼層權杖化規則分割為字詞,並在要執行的指令前面加上字詞清單。

如果第一個字詞是完整標籤 (開頭為 //),即可建構該字詞。接著,標籤會替換為與其他字詞一起執行的指令開頭對應的可執行位置。

注意事項:

  • 用於執行測試的 PATH 可能與環境中的 PATH 不同,因此您可能需要為 --run_under 指令 (command-prefix 中的第一個字詞) 使用「絕對路徑」
  • stdin 並未連線,因此 --run_under 無法用於互動式指令,

例:

        --run_under=/usr/bin/strace
        --run_under='/usr/bin/strace -c'
        --run_under=/usr/bin/valgrind
        --run_under='/usr/bin/valgrind --quiet --num-callers=20'

測試選項

如「輸出選取選項」一節所述,您可以根據大小逾時標記語言篩選測試。使用便利的一般名稱篩選器可將特定篩選器引數轉送至測試執行器。

bazel test的其他選項

語法和其餘選項與 bazel build 完全相同。

執行中的執行檔

bazel run 指令與 bazel build 類似,差別在於前者用於建構「並執行」單一目標。以下是典型的講座:

  % bazel run java/myapp:myapp -- --arg1 --arg2
  Welcome to Bazel
  INFO: Loading package: java/myapp
  INFO: Loading package: foo/bar
  INFO: Loading complete.  Analyzing...
  INFO: Found 1 target...
  ...
  Target //java/myapp:myapp up-to-date:
    bazel-bin/java/myapp:myapp
  INFO: Elapsed time: 0.638s, Critical Path: 0.34s

  INFO: Running command line: bazel-bin/java/myapp:myapp --arg1 --arg2
  Hello there
  $EXEC_ROOT/java/myapp/myapp
  --arg1
  --arg2

bazel run 很類似,但並非完全相同,是指直接叫用 Bazel 建構的二進位檔,其行為也因要叫用的二進位檔是否為測試而不同。

如果二進位檔並非測試,則目前的工作目錄會是二進位檔的執行檔案樹狀結構。

當二進位檔為測試時,目前的工作目錄會是 exec 根目錄,並會主動嘗試複寫環境測試。不過,該模擬並非完美無缺,且包含多個資料分割的測試無法以這種方式執行 (您可以使用 --test_sharding_strategy=disabled 指令列選項來解決這個問題)

二進位檔也可以使用下列額外環境變數:

  • BUILD_WORKSPACE_DIRECTORY:執行建構作業的工作區根。
  • BUILD_WORKING_DIRECTORY:目前執行 Bazel 的工作目錄。

舉例來說,您可以使用這些設定,以容易使用的方式解讀指令列中的檔案名稱。

bazel run」的選項

--run_under=command-prefix

這與 bazel test--run_under 選項的效果相同 (請參閱上文),但只適用於 bazel run 執行的指令,而不是用於 bazel test 執行的測試,且無法在標籤中執行。

篩選 Bazel 的記錄輸出內容

使用 bazel run 叫用二進位檔時,Bazel 會列印來自 Bazel 本身的記錄輸出內容,以及叫用的二進位檔。如要降低記錄的雜訊,可以使用 --ui_event_filters--noshow_progress 旗標隱藏 Bazel 本身的輸出內容。

例如: bazel run --ui_event_filters=-info,-stdout,-stderr --noshow_progress //java/myapp:myapp

執行測試

bazel run 也可以執行測試二進位檔,這對於在編寫測試中所述環境相當近似的環境中執行測試的效果。請注意,除了 --test_arg 以外,以這種方式執行測試時,--test_* 引數都不會有任何作用。

清除建構輸出內容

clean 指令

Bazel 的 clean 指令類似於 Make。系統會針對這個 Bazel 執行個體執行的所有建構設定刪除輸出目錄,或是刪除 Bazel 執行個體所建立的完整工作樹狀結構,並重設內部快取。如果在沒有任何指令列選項的情況下執行,系統會清除所有設定的輸出目錄。

提醒您,每個 Bazel 執行個體都與單一工作區相關聯,因此 clean 指令會從該工作區中對該 Bazel 執行個體執行的所有建構作業刪除所有輸出內容。

如要完全移除 Bazel 執行個體建立的完整工作樹狀結構,您可以指定 --expunge 選項。使用 --expunge 執行時,Clean 指令只會移除整個輸出基本樹狀結構,除了建構輸出內容之外,也會包含 Bazel 建立的所有暫存檔案。也會在清除完成後停止 Bazel 伺服器,這與 shutdown 指令相同。舉例來說,如要清除 Bazel 執行個體的所有磁碟與記憶體追蹤記錄,您可以指定:

  % bazel clean --expunge

或者,您也可以使用 --expunge_async 在背景清除。您可以放心在同一個用戶端中叫用 Bazel 指令,同時非同步清除作業會持續執行。

提供 clean 指令主要是針對不再需要的工作區取回磁碟空間。Bazel 的漸進式重新建構作業可能不完美,因此在問題發生時,可以使用 clean 來復原一致的狀態。

Bazel 的設計就是要解決這些問題,因此要優先修正這些錯誤。如果發現錯誤的漸進式版本,請提交錯誤報告,並在工具中回報錯誤,而非使用 clean

查詢依附元件圖

Bazel 包含查詢語言,用於詢問在建構期間使用的依附元件圖表相關問題。查詢語言用於兩個指令:query 和 cquery。這兩個指令的主要差異在於,查詢會在載入階段和 cquery 於分析階段後執行。這些工具對於許多軟體工程工作都有莫大幫助。

查詢語言是以圖表上的代數運算概念為基礎

Bazel 查詢參考資料。如需範例和查詢專屬指令列選項,請參閱該文件。

查詢工具接受多個指令列選項。--output 會選取輸出格式。--[no]keep_going (預設為停用) 會使查詢工具繼續在發生錯誤時繼續執行;如果發生錯誤時無法接受不完整的結果,則這個行為可能會停用。

--[no]tool_deps 選項預設為啟用,會導致非目標設定的依附元件包含在查詢運作的依附元件圖表中。

預設啟用的 --[no]implicit_deps 選項會導致隱含依附元件納入查詢作業的依附元件圖表中。隱含依附元件是指 BUILD 檔案中並未明確指定,但是由 bazel 新增的依附元件。

例如:「在 PEBL 樹狀結構中建構所有測試所需的所有 Genrule 定義位置 (在 BUILD 檔案中)。」

  bazel query --output location 'kind(genrule, deps(kind(".*_test rule", foo/bar/pebl/...)))'

查詢動作圖

aquery 指令可讓您查詢建構圖中的動作。它在分析後設定的目標圖上運作,並公開動作、構件及其關係等資訊。

這項工具接受數種指令列選項。--output 會選取輸出格式。預設的輸出格式 (text) 是使用者可理解的格式,請使用 prototextproto 做為機器可讀取的格式。值得注意的是,查詢指令會在一般 Bazel 建構作業上執行,並繼承建構期間可用的選項組合。

並提供傳統 querysiblingsbuildfilestests 可用的同一組函式。

詳情請參閱「動作圖查詢」。

其他指令和選項

help

help 指令可提供線上說明。根據預設,系統會顯示可用指令和說明主題的摘要,如使用 Bazel 進行建構。指定引數會顯示特定主題的詳細說明。大部分主題都是 Bazel 指令,例如 buildquery,但有些說明主題並沒有對應指令。

--[no]long (-l)

根據預設,bazel help [topic] 只會列印主題相關選項的摘要。如果指定 --long 選項,系統也會顯示類型、預設值和每個選項的完整說明。

shutdown

您可以使用 shutdown 指令來停止 Bazel 伺服器程序。這個指令會在 Bazel 伺服器進入閒置狀態時 (例如完成任何建構作業或其他執行中的指令後) 立即關閉。詳情請參閱用戶端/伺服器實作

Bazel 伺服器會在閒置逾時後停止,因此很少需要執行這個指令。不過,如果知道特定工作區不會再發生進一步的建構作業,那麼這個指令在指令碼中會很實用。

shutdown 接受一個需要整數引數 (以 MB 為單位) 的 --iff_heap_size_greater_than _n_ 選項。如有指定,系統會針對已使用的記憶體容量將關閉條件設為條件。這對啟動大量建構作業的指令碼來說非常實用,因為 Bazel 伺服器中的任何記憶體流失情形,都可能導致 Bazel 意外當機;執行條件式重新啟動就會先佔這種狀況。

info

info 指令會顯示與 Bazel 伺服器執行個體或特定建構設定相關聯的各種值。(可驅動建構的指令碼可能會使用這些參數)。

info 指令也允許使用單一 (選用) 引數,這是下方清單中任一金鑰的名稱。在這種情況下,bazel info key 只會列印該鍵的值。(這在編寫 Bazel 時特別方便,因為這樣就不必透過 sed -ne /key:/s/key://p 管道產生結果:

與設定無關的資料

  • release:這個 Bazel 執行個體的版本標籤,如果這不是已發布的二進位檔,則為「開發版本」。
  • workspace 是基本工作區目錄的絕對路徑。
  • install_base:目前使用者使用此 Bazel 執行個體使用的安裝目錄絕對路徑。Bazel 會在這個目錄下安裝內部需要的執行檔。

  • output_base:目前使用者和工作區組合,這個 Bazel 執行個體使用基本輸出目錄的絕對路徑。Bazel 會將所有作業都放在這個目錄下,執行建構作業輸出內容。

  • execution_root:輸出至 output_base 下執行根目錄的絕對路徑。這個目錄是所有在建構期間所執行指令可存取的檔案的根目錄,也是這些指令的工作目錄。如果工作區目錄可以寫入,系統會將名為 bazel-<workspace> 的符號連結指向這個目錄。

  • output_path:位於執行根目錄下的輸出目錄的絕對路徑,用於建構指令實際產生的所有檔案。如果工作區目錄可以寫入,系統會將名為 bazel-out 的符號連結指向此目錄。

  • server_pid:Bazel 伺服器程序的程序 ID。

  • server_log:Bazel 伺服器偵錯記錄檔的絕對路徑。這個檔案包含 Bazel 伺服器生命週期中所有指令的偵錯資訊,供 Bazel 開發人員和進階使用者使用。

  • command_log:指令記錄檔的絕對路徑,其中包含最新 Bazel 指令的交錯 stdout 和 stderr 串流。請注意,執行 bazel info 將覆寫這個檔案的內容,因為該檔案會成為最新的 Bazel 指令。不過,除非您變更 --output_base--output_user_root 選項的設定,否則指令記錄檔的位置將不會改變。

  • used-heap-sizecommitted-heap-sizemax-heap-size:回報各種 JVM 堆積大小參數。分別使用:目前使用的記憶體、系統目前保證適用於 JVM 的記憶體、可能的最大分配比例。

  • gc-countgc-time:自這個 Bazel 伺服器啟動以來的垃圾收集累計數量,以及執行這些作業所花費的時間。請注意,系統不會在每次建構時重設這些值。

  • package_path:以冒號分隔的路徑清單,會按 bazel 搜尋套件。格式與 --package_path 建構指令列引數相同。

例如:Bazel 伺服器的程序 ID。

% bazel info server_pid
1285

設定專屬資料

這些資料可能會受到傳送至 bazel info 的設定選項 (例如 --cpu--compilation_mode 等) 的影響。info 指令可接受控制依附元件分析的所有選項,因為其中某些選項會決定建構的輸出目錄位置、編譯器選擇等。

  • bazel-binbazel-testlogsbazel-genfiles:回報 bazel-* 目錄的絕對路徑,該目錄由建構作業產生的程式位於其中。這通常與成功建構後,在基本工作區目錄中建立的 bazel-* 符號連結相同,但並不一定。不過,如果工作區目錄為唯讀,則無法建立 bazel-* 符號連結。指令碼如果使用 bazel info 回報的值,而不是假設符號連結存在,會更穩健。
  • 完整的「Make」環境。如果指定了 --show_make_env 旗標,也會顯示目前設定「Make」環境中的所有變數,例如 CCGLIBC_VERSION 等。以下是使用 BUILD 檔案中 $(CC)varref("CC") 語法存取的變數。

例如:目前設定的 C++ 編譯器。 這是「Make」環境中的 $(CC) 變數,因此必須使用 --show_make_env 旗標。

  % bazel info --show_make_env -c opt COMPILATION_MODE
  opt

範例:目前設定的 bazel-bin 輸出目錄。即使因故無法建立 bazel-bin 符號連結 (例如從唯讀目錄建構),這項做法也能保證正確。

% bazel info --cpu=piii bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
% bazel info --cpu=k8 bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin

version--version

版本指令會顯示已建構 Bazel 二進位檔的版本詳細資料,包括建構 Bazel 二進位檔的變更清單和日期。這些資訊在判斷您是否擁有最新的 Bazel,或要回報錯誤時特別有用。其中一些有趣的值為:

  • changelist:這個版本的 Bazel 發布版本變更清單。
  • label:這個 Bazel 執行個體的版本標籤,如果這不是已發布的二進位檔,則為「開發版本」。回報錯誤時相當實用。

在沒有其他引數的情況下,bazel --version 會發出與 bazel version --gnu_format 相同的輸出,除非不會產生可能啟動 Bazel 伺服器或解壓縮伺服器封存的副作用。bazel --version 可以在任何地方執行,不需要工作區目錄。

mobile-install

mobile-install 指令會在行動裝置上安裝應用程式。目前僅支援搭載 ART 的 Android 裝置。

詳情請參閱 bazel 行動裝置安裝

以下是支援的選項:

--incremental

如果啟用這項設定,Bazel 就會嘗試以漸進方式安裝應用程式,也就是只有從上次建構後變更的部分。無法更新從 AndroidManifest.xml、原生程式碼或 Java 資源參照的資源 (例如 Class.getResource() 參照的資源)。如果這些項目有所變更,必須省略這個選項。與 Bazel 的精神相較,且由於 Android 平台的限制,使用者的責任知道這個指令何時足夠,以及何時需要全面安裝。

如果您使用搭載 Marshmallow 以上版本的裝置,請考慮使用 --split_apks 旗標。

--split_apks

是否要使用分割 APK,在裝置上安裝及更新應用程式。僅適用於搭載 Marshmallow 以上版本的裝置。請注意,使用 --split_apks 時不需要 --incremental 旗標。

--start_app

安裝完成後,以乾淨的狀態啟動應用程式。等同於 --start=COLD

--debug_app

等待系統附加偵錯工具,再於安裝後以乾淨狀態啟動應用程式。等同於 --start=DEBUG

--start=_start_type_

安裝完成後的應用程式應該如何啟動。支援的 _start_type_s 如下:

  • NO 不會啟動應用程式。這是預設值。
  • COLD:在安裝後從乾淨狀態啟動應用程式。
  • WARM 保留並還原漸進式安裝時的應用程式狀態。
  • DEBUG 等待偵錯工具,等到安裝完成後以乾淨狀態啟動應用程式。

--adb=path

表示要使用的 adb 二進位檔。

根據預設,系統會使用 --android_sdk 指定的 Android SDK 中的 ADB。

--adb_arg=serial

adb 的額外引數。這些位於指令列的子指令之前,通常用於指定要安裝到哪一個裝置。例如,選取要使用的 Android 裝置或模擬器:

% bazel mobile-install --adb_arg=-s --adb_arg=deadbeef

以下列身分叫用 adb

adb -s deadbeef install ...

--incremental_install_verbosity=number

「提升安裝量」的相關詳細程度,將偵錯記錄設為 1,以便列印至主控台。

dump

dump 指令會列印至 Bazel 伺服器內部狀態的傾印。這個指令主要適用於 Bazel 開發人員,因此未指定這個指令的輸出內容,而且可能會有所變動。

根據預設,指令只會輸出說明訊息,列出可能執行 Bazel 狀態特定區域的選項。如要傾印內部狀態,必須指定至少一個選項。

以下是支援的選項:

  • --action_cache 傾印動作快取內容。
  • --packages 傾印套件快取內容。
  • --skyframe 會傾印內部 Bazel 依附元件圖表的狀態。
  • --rules 會傾印每個規則和切面類別的規則摘要,包括計數和動作次數。這包含原生和 Starlark 規則。如果啟用記憶體追蹤,則也會列印規則的記憶體消耗量。
  • --skylark_memory 會將與 pprof 相容的 .gz 檔案傾印至指定路徑。您必須啟用記憶體追蹤,才能讓此功能順利運作。

記憶體追蹤

部分 dump 指令需要記憶體追蹤。如要啟用這項功能,您必須將啟動標記傳遞至 Bazel:

  • --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar
  • --host_jvm_args=-DRULE_MEMORY_TRACKER=1

java-Agent 會在 third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar 簽入 Bazel,因此請務必針對 Bazel 存放區的位置調整 $BAZEL

不要忘記針對每個指令將這些選項傳遞至 Bazel,否則伺服器會重新啟動。

示例:

    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    build --nobuild <targets>

    # Dump rules
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --rules

    # Dump Starlark heap and analyze it with pprof
    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --skylark_memory=$HOME/prof.gz
    % pprof -flame $HOME/prof.gz

analyze-profile

analyze-profile 指令會分析先前在 Bazel 叫用期間收集的 JSON 追蹤記錄設定檔

canonicalize-flags

canonicalize-flags 指令會取得 Bazel 指令的選項清單,並傳回有相同效果的選項清單。新的選項清單為標準選項。例如,具有相同效果的兩個選項清單標準化為同一份新清單。

--for_command 選項可用來選取不同的指令。目前僅支援 buildtest。指定的指令不支援的選項會導致錯誤。

舉例來說:

  % bazel canonicalize-flags -- --config=any_name --test_tag_filters="-lint"
  --config=any_name
  --test_tag_filters=-lint

啟動選項

本節說明的選項會影響 Bazel 伺服器程序使用的 Java 虛擬機器啟動作業,且會套用至該伺服器處理的所有後續指令。如果已有執行中的 Bazel 伺服器,且啟動選項不符,將重新啟動伺服器。

本節說明的所有選項都必須使用 --key=value--key value 語法指定。此外,這些選項必須在 Bazel 指令名稱「之前」顯示。使用 startup --key=value.bazelrc 檔案中列出這些內容。

--output_base=dir

這個選項需要路徑引數,且必須指定可寫入的目錄。Bazel 會使用這個位置寫入所有輸出內容。輸出基礎也是用戶端找到 Bazel 伺服器的金鑰。只要變更輸出基礎,就能變更處理指令的伺服器。

根據預設,輸出數衍生自使用者的登入名稱和工作區目錄名稱 (實際上是 MD5 摘要),因此一般值如下所示:/var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e

例如:

 OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
% bazel --output_base ${OUTPUT_BASE}1 build //foo  &  bazel --output_base ${OUTPUT_BASE}2 build //bar

在這個指令中,兩個 Bazel 指令會並行執行 (因為殼層 &amp; 運算子),每個指令都會使用不同的 Bazel 伺服器執行個體 (因為輸出基礎不同)。相對的,如果兩個指令都使用了預設輸出基礎,那麼兩個要求都會傳送至同一個伺服器,系統會依序處理這些要求:先建構 //foo,然後是 //bar 的漸進式版本。

--output_user_root=dir

指向建立輸出和安裝基礎的根目錄。目錄必須不存在或由發出呼叫的使用者所擁有。過去,這允許指向在多位使用者共用的目錄,但無法再設為上限。處理問題 #11100 後,可能會允許此做法。

如果指定 --output_base 選項,系統會覆寫使用 --output_user_root 計算輸出基礎的費用。

安裝基本位置的計算依據為 --output_user_root,加上 Bazel 嵌入二進位檔的 MD5 身分。

如果檔案系統版面配置有較好的位置,您可以使用 --output_user_root 選項,為所有 Bazel 的輸出內容 (安裝數和輸出基礎) 選擇替代基本位置。

--server_javabase=dir

指定 Bazel 本身在當中執行的 Java 虛擬機器。這個值必須是包含 JDK 或 JRE 的目錄路徑。而且不得為標籤。此選項應會顯示在任何 Bazel 指令之前,例如:

  % bazel --server_javabase=/usr/local/buildtools/java/jdk11 build //foo

這個標記不會影響 Bazel 子程序 (例如應用程式、測試、工具等) 使用的 JVM。請改用建構選項 --javabase--host_javabase

這個旗標之前名為 --host_javabase (有時稱為「左側」--host_javabase),但已重新命名,以免與建構標記 --host_javabase (有時稱為「右側」 --host_javabase) 產生混淆。

--host_jvm_args=string

指定要傳遞至 Bazel 本身的 Java 虛擬機器的啟動選項。這可用來設定堆疊大小,例如:

  % bazel --host_jvm_args="-Xss256K" build //foo

這個選項可與個別引數搭配使用多次。請注意,您通常不需要設定這個標記。您也可以傳遞以空格分隔的字串清單,每個字串都會解讀為個別 JVM 引數,但這項功能即將淘汰。

但這「不會」影響 Bazel 子程序使用的任何 JVM,包括應用程式、測試、工具等。如要將 JVM 選項傳遞給執行 Java 程式 (無論是透過 bazel run 或指令列執行),您應使用所有 java_binaryjava_test 程式支援的 --jvm_flags 引數。或者,如要進行測試,請使用 bazel test --test_arg=--jvm_flags=foo ...

--host_jvm_debug

這個選項會讓 Java 虛擬機器會等待符合 JDWP 相容偵錯工具的連線,再呼叫 Bazel 本身的主要方法。通常適合 Bazel 開發人員使用。

--autodetect_server_javabase

這個選項會使 Bazel 在啟動時自動搜尋已安裝的 JDK,如果無法取得內嵌的 JRE,則會改回已安裝的 JRE。--explicit_server_javabase 可用來挑選要搭配 Bazel 執行的明確的 JRE。

--batch

批次模式會導致 Bazel 不會使用標準用戶端/伺服器模式,而會改為針對單一指令執行 bazel Java 程序,這個程序用於處理訊號處理、工作控制和環境變數繼承方面的可預測語意,且是在 Chroot jail 中執行 Bazel。

批次模式會在相同的 output_base 內保留適當的佇列語意。也就是說,系統會依序處理多個叫用,而不會重疊。如果 Bazel 是在透過執行伺服器的用戶端上執行,則會先終止伺服器再處理指令。

在批次模式下或上述替代方案中,Bazel 的執行速度會較慢。這是因為建構檔案快取不僅會駐留在記憶體中,不會在依序的批次叫用之間保留。因此,在效能較不重要 (例如持續建構) 的情況下,批次模式通常較為合理。

--max_idle_secs=n

這個選項會指定 Bazel 伺服器程序在最後一次用戶端要求之後等待多久 (以秒為單位) 後才會離開。預設值為 10800 (3 小時)。--max_idle_secs=0 會導致 Bazel 伺服器程序無限期保留。

叫用 Bazel 的指令碼可能會使用這個選項,確保 Bazel 伺服器程序不會在使用者電腦執行時留在使用者的機器上。舉例來說,預先提交的指令碼可能會想要叫用 bazel query,確保使用者的待處理變更不會引入不必要的依附元件。但是,如果使用者尚未在該工作區中執行近期建構作業,則因為預先提交指令碼來啟動 Bazel 伺服器,只是為了在當天剩餘時間保持閒置狀態,是不必要的。透過在查詢要求中指定較小的 --max_idle_secs 值,指令碼就能確保「如果」if造成新的伺服器啟動,該伺服器會立即結束,但如果原本已在執行中的伺服器,該伺服器會繼續執行,直到它平常閒置時間為止。當然,系統會重設現有伺服器的閒置計時器。

--[no]shutdown_on_low_sys_mem

如果啟用,且 --max_idle_secs 設為正持續時間,在建構伺服器閒置一段時間後,請在系統記憶體不足時關閉伺服器。僅適用於 Linux。

除了執行與 max_idle_secs 相對應的閒置檢查之外,建構伺服器也會在伺服器閒置一段時間後開始監控可用的系統記憶體。如果可用的系統記憶體嚴重不足,伺服器將會結束。

--[no]block_for_lock

如果啟用,Bazel 就會等待其他保存伺服器鎖定的 Bazel 指令完成,再開始執行。停用後,如果 Bazel 無法立即取得鎖定並開始完成,就會發生錯誤。

開發人員可能在預先提交檢查中使用此功能,避免同一用戶端中其他 Bazel 指令造成的等待時間過長。

--io_nice_level=n

設定 0 到 7 的等級,確保 IO 排程能發揮最大效益。0 代表最高優先順序 7 代表最低預期排程器最多只能履行 4 優先順序。系統會忽略負值。

--batch_cpu_scheduling

針對 Bazel 使用 batch CPU 排程。這項政策適用於非互動式,但不希望降低其適當值的工作負載。請參閱「man 2 sched_setscheduler」。這項政策可以改善系統互動情形,但同時會降低 Bazel 處理量。

其他選項

--[no]announce_rc

控管 Bazel 是否要在啟動時從 bazelrc 檔案讀取指令選項。(無條件會宣布啟動選項)。

--color (yes|no|auto)

這個選項可決定 Bazel 是否使用顏色在畫面中醒目顯示輸出內容。

如果將這個選項設為 yes,系統就會啟用色彩輸出功能。如果將這個選項設為 auto,則只有在輸出內容傳送到終端機,並將 TERM 環境變數設為 dumbemacsxterm-mono 以外的值時,Bazel 才會使用顏色輸出。如果這個選項設為 no,無論輸出內容是否傳送至終端機,以及不論 TERM 環境變數的設定為何,顏色輸出都會停用。

--config=name

rc 檔案選取其他設定區段;針對目前的 command,如果這類區段存在,它也會從 command:name 提取選項。您可以多次指定這個值,以從多個設定區段新增標記。展開項目可參照其他定義 (例如,展開可鏈結)。

--curses (yes|no|auto)

這個選項可決定 Bazel 是否會在其畫面輸出中使用遊標控制項。這樣可以減少捲動資料的情況,並且取得更精簡、易於讀取的 Bazel 輸出串流。這可以和 --color 搭配使用。

如果將這個選項設為 yes,系統就會啟用遊標控制項。如果將這個選項設為 no,就無法使用遊標控制項。如果將這個選項設為 auto,系統會在與 --color=auto 相同的條件下啟用遊標控制項。

--[no]show_timestamps

如有指定,Bazel 產生的每則訊息都會指定顯示訊息的時間。