指令和選項

本頁面說明各種 Bazel 指令 (例如 bazel build、bazel run 和 bazel test) 的可用選項。本頁面是「使用 Bazel 建構」一文中 Bazel 指令清單的輔助頁面。

目標語法

部分指令 (例如 build 或 test) 可對目標清單執行操作。這些標籤使用的語法比標籤更具彈性，詳情請參閱「指定要建構的目標」。

選項

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

大多數選項只能指定一次。如果多次指定，系統會採用最後一個例項。線上說明中會以「可多次使用」文字標示可多次指定的選項。

套件位置

--package_path

警告：--package_path 選項已淘汰，Bazel 偏好將主要存放區中的套件放在工作區根目錄下。

這個選項會指定要搜尋的目錄集，以找出特定套件的 BUILD 檔案。

Bazel 會搜尋套件路徑，找出套件。這是以半形冒號分隔的 bazel 目錄排序清單，每個目錄都是部分來源樹狀結構的根目錄。

如要使用 --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 工作區下方的目錄使用 Bazel，可能會發生非預期的行為。舉例來說，如果您使用套件路徑元素 .，然後 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 MODULE.bazel
  % bazel build --package_path /some/other/path //foo

--deleted_packages

這個選項會指定以半形逗號分隔的套件清單，Bazel 應將這些套件視為已刪除，且不應嘗試從套件路徑上的任何目錄載入。這可用於模擬刪除套件，但不會實際刪除。這個選項可以多次傳遞，在這種情況下，個別清單會串連在一起。

錯誤檢查

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

--[no]check_visibility

如果將這個選項設為 False，可見度檢查會降級為警告。 這個選項的預設值為 true，因此預設會進行可見度檢查。

--output_filter=regex

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

這個選項的一般值如下：

工具旗標

這些選項可控管 Bazel 會將哪些選項傳遞給其他工具。

--copt=cc-option

這個選項會採用要傳遞至編譯器的引數。 每當為 C、C++ 或組語程式碼叫用前置處理、編譯和/或組譯器時，引數都會傳遞至編譯器。連結時不會傳遞這項資訊。

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

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

會編譯 foo 程式庫，但不含偵錯資料表，並產生與位置無關的程式碼。

--host_copt=cc-option

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

--host_conlyopt=cc-option

這個選項會採用引數，並傳遞至編譯器，用於在 exec 設定中編譯的 C 來源檔案。這與 --conlyopt 選項類似，但僅適用於 exec 設定。

--host_cxxopt=cc-option

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

--host_linkopt=linker-option

這個選項會採用引數，並傳遞至連結器，用於在 exec 設定中編譯的來源檔案。這與 --linkopt 選項類似，但僅適用於 exec 設定。

--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)

這個選項會決定 Bazel 是否要透過叫用含有 -Wl,--strip-debug 選項的連結器，從所有二進位檔和共用程式庫中移除偵錯資訊。--strip=always 表示一律要移除偵錯資訊。 --strip=never 表示絕不移除偵錯資訊。 --strip=sometimes 的預設值表示，如果 --compilation_mode 為 fastbuild，則會移除。

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

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

Bazel 的 --strip 選項對應於 ld 的 --strip-debug 選項：只會移除偵錯資訊。如果基於某些原因，您想移除所有符號 (不只是偵錯符號)，則需要使用 ld 的 --strip-all 選項，方法是將 --linkopt=-Wl,--strip-all 傳遞至 Bazel。請注意，設定 Bazel 的 --strip 標記會覆寫 --linkopt=-Wl,--strip-all，因此您只能設定其中一個。

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

--stripopt=strip-option

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

--fdo_instrument=profile-output-dir

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

產生設定檔資料樹狀結構後，請將設定檔樹狀結構壓縮成 ZIP 檔案，並提供給 --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 檔案，其中包含先前產生的檔案樹狀結構，以及含有每個 .o 檔案設定檔資訊的 .gcda 檔案。

或者，提供的引數可以指向擴充功能 .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 規格相容的建構項目。預設值為 11。--> 可能的值包括：8、9、10、11、17 和 21，並可使用 default_java_toolchain 註冊自訂 Java 工具鍊來擴充。

--tool_java_language_version=version

用於建構工具的 Java 語言版本，這些工具會在建構期間執行。 預設值為 11。

--java_runtime_version=version

這個選項會指定要用來執行程式碼和測試的 JVM 版本。例如：

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

從遠端存放區下載 JDK 11，並使用該 JDK 執行 Java 應用程式。

預設值為 local_jdk。可能的值為：local_jdk、local_jdk_version、remotejdk_11、remotejdk_17 和 remotejdk_21。如要擴充值，請使用 local_java_repository 或 remote_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 預設偵錯資訊 (而非 Bazel 預設資訊) 重建 java_binary。

這個選項會傳遞至 javac，順序是在 Bazel 內建的 javac 預設選項之後，以及規則專屬選項之前。任何選項的最後一個規格都會勝出。javac 的預設選項如下：

  -source 8 -target 8 -encoding UTF-8

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

這個選項可控管 javac 是否會檢查缺少的直接依附元件。Java 目標必須明確將所有直接使用的目標宣告為依附元件。這個旗標會指示 javac 判斷實際用於檢查每個 Java 檔案的型別的罐子，並在這些罐子不是目前目標的直接依附元件輸出內容時，發出警告/錯誤。

• off 表示檢查已停用。
• warn 表示 javac 會針對每個缺少的直接依附元件，產生 [strict] 類型的標準 Java 警告。
• default、strict 和 error 都表示 javac 會產生錯誤而非警告，因此如果發現任何缺少的直接依附元件，目前的目標就會建構失敗。 如未指定標記，這也是預設行為。

建構語意

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

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

--compilation_mode 選項 (通常會縮寫為 -c，尤其是 -c opt) 會採用 fastbuild、dbg 或 opt 的引數，並影響各種 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]*

建構遞移 deps android_binary 規則的平台 (特別是 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 只能使用執行路徑。在這種情況下，由於這與任何執行路徑都不相符，因此 regexp 不應以「//」開頭。套件名稱可依下列方式使用： --per_file_copt=base/.*\.pb\.cc@-g0。這會比對名為 base 的目錄下的每個 .pb.cc 檔案。

這個選項可以多次使用。

無論使用哪種編譯模式，系統都會套用這個選項。舉例來說，您可以使用 --compilation_mode=opt 進行編譯，並選擇性地編譯部分檔案，同時啟用較強的最佳化功能，或停用最佳化功能。

注意：如果部分檔案是使用偵錯符號選擇性編譯，符號可能會在連結期間遭到移除。如要避免這種情況，請設定 --strip=never。

語法：[+-]regex[,[+-]regex]...@option[,option]... 其中 regex 代表規則運算式，可加上 + 前置字串來識別納入模式，並加上 - 前置字串來識別排除模式。option 代表傳遞至 C++ 編譯器的任意選項。如果選項包含 ,，則必須加上引號，例如 \,。選項也可以包含 @，因為只有第一個 @ 會用於分隔規則運算式和選項。

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

--dynamic_mode=mode

決定 C++ 二進位檔是否會動態連結，並與建構規則的 linkstatic 屬性互動。

模式：

• default：允許 Bazel 選擇是否要動態連結。 詳情請參閱這個連結。
• fully：動態連結所有目標。這樣可加快連結時間，並縮減產生的二進位檔大小。
• off：以大多為靜態模式連結所有目標。如果 -static 是在 linkopts 中設定，目標會變更為完全靜態。

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

啟用 Fission，將 C++ 偵錯資訊寫入專用的 .dwo 檔案，而不是 .o 檔案 (否則會寫入 .o 檔案)。這大幅縮減了連結的輸入大小，並可縮短連結時間。

如果設為 [dbg][,opt][,fastbuild] (例如： --fission=dbg,fastbuild)，系統只會為指定的編譯模式組合啟用 Fission。這對 bazelrc 設定很有用。如果設為 yes，系統就會全面啟用 Fission。如果設為 no，系統會全面停用 Fission。預設值為 no。

--force_ignore_dash_static

如果設定這個旗標，系統會忽略 cc_* 規則 BUILD 檔案 linkopts 中的所有 -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

用於編譯遞移 deps 中 C/C++ 規則的 crosstool，適用於 objc*、ios* 和 apple* 規則。對於這些目標，這個標記會覆寫 --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

無作業。僅為保持回溯相容性而保留。

--host_java_toolchain=label

無作業。僅為保持回溯相容性而保留。

--javabase=(label)

無作業。僅為保持回溯相容性而保留。

--host_javabase=label

無作業。僅為保持回溯相容性而保留。

執行策略

這些選項會影響 Bazel 執行建構作業的方式。 建構作業產生的輸出檔案不應受到重大影響。通常主要影響的是建構速度。

--spawn_strategy=strategy

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

• standalone 會導致指令以本機子程序的形式執行。這個值已遭淘汰。請改用「local」。
• sandboxed 會在本機的沙箱中執行指令。這項作業需要將所有輸入檔案、資料依附元件和工具，列為 srcs、data 和 tools 屬性中的直接依附元件。在支援沙箱執行的系統上，Bazel 預設會啟用本機沙箱機制。
• local 會導致指令以本機子程序的形式執行。
• worker 會使用持續性工作站執行指令 (如有)。
• docker 會在本機的 Docker 沙箱中執行指令。這項操作需要安裝 Docker。
• remote 會導致指令從遠端執行；只有在另外設定遠端執行器時，才能使用這項功能。

--strategy mnemonic=strategy

這個選項可控制指令的執行位置和方式，並依據助記符覆寫 --spawn_strategy (和 --genrule_strategy，助記符為 Genrule)。如要瞭解支援的策略及其影響，請參閱 --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_resources resources or resource expression

這些選項會指定 Bazel 在排定本機建構和測試活動時，可考量的本機資源量 (RAM 容量，以 MB 為單位，以及 CPU 邏輯核心數)。這些標記會採用浮點數或關鍵字 (HOST_RAM 或 HOST_CPUS)，並可選擇性地加上 [-|*float] (例如 --local_resources=cpu=2、--local_resources=memory=HOST_RAM*.5、--local_resources=cpu=HOST_CPUS-1)。這些標記彼此獨立，可設定其中一個或全部。根據預設，Bazel 會直接從本機系統的設定估算 RAM 容量和 CPU 核心數。

--[no]build_runfile_links

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

執行測試 (或應用程式) 時，系統會將執行階段資料依附元件集中在一個位置。在 Bazel 的輸出樹狀結構中，這個「執行檔」樹狀結構通常會以對應的二進位檔或測試檔的同層級為根目錄。在測試執行期間，可以使用 $TEST_SRCDIR/canonical_repo_name/packagename/filename 形式的路徑存取 Runfile。執行檔案樹狀目錄可確保測試能存取所有已宣告依附元件的檔案，且僅限於這些檔案。根據預設，執行檔樹狀結構的實作方式是建構一組必要檔案的符號連結。隨著連結集增加，這項作業的成本也會提高，對於某些大型建構作業而言，這項作業可能會大幅增加整體建構時間，特別是因為每個個別測試 (或應用程式) 都需要自己的執行檔樹狀結構。

--[no]build_runfile_manifests

這個選項預設為啟用，可指定是否應將執行檔資訊清單寫入輸出樹狀結構。停用這項功能表示 --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 的輸出內容編譯相依目標，而是會建立介面 JAR，其中只包含非私有成員的簽章 (公開、受保護和預設 (套件) 存取方法和欄位)，並使用介面 JAR 編譯相依目標。java_library這樣一來，如果只變更方法主體或類別的私有成員，就能避免重新編譯。

--[no]interface_shared_objects

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

選取輸出內容

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

--[no]build

這個選項會導致建構作業的執行階段發生；預設為開啟。關閉時，系統會略過執行階段，只會進行前兩個階段：載入和分析。

這個選項可用於驗證 BUILD 檔案，並偵測輸入內容中的錯誤，但不會實際建構任何內容。

--[no]build_tests_only

如果指定，Bazel 只會建構執行 *_test 和 test_suite 規則所需的項目，這些規則不會因大小、逾時、標記或語言而遭到篩除。如果指定，Bazel 會忽略指令列上指定的其他目標。根據預設，這個選項會停用，而 Bazel 會建構所有要求的項目，包括從測試中篩除的 *_test 和 test_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

會測試標示為 performance 或 stress 標記，但未標示為 flaky 標記的目標。

根據預設，系統不會套用測試代碼篩選器。請注意，您也可以透過這種方式，篩選測試的 size 和 local 標記。

--test_lang_filters=string[,string]*

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

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

只會測試 //baz/... 中 foo_test 或 bar_test 的執行個體目標，而

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

會測試 //baz/... 中的所有目標，但 foo_test 和 bar_test 例外。

--test_filter=filter-expression

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

filter-expression 的具體解讀方式取決於負責執行測試的測試架構。可以是 glob、子字串或 regexp。--test_filter 方便您傳遞不同的 --test_arg 篩選器引數，但並非所有架構都支援這項功能。

詳細程度

這些選項可控制 Bazel 輸出內容的詳細程度，無論是輸出至終端機或額外的記錄檔都適用。

--explain=logfile

這個選項需要檔案名稱引數，會導致 bazel build 執行階段的依附元件檢查程式，針對每個建構步驟說明執行原因或指出步驟為最新狀態。說明會寫入記錄檔。

如果遇到非預期的重建作業，這個選項有助於瞭解原因。將其新增至 .bazelrc，以便記錄所有後續建構作業，然後在執行步驟意外執行時檢查記錄。這個選項可能會導致效能略為降低，因此不需要時建議移除。

--verbose_explanations

啟用 --explain 選項後，這個選項會增加產生的說明詳細程度。

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

使用這個選項可能會大幅增加產生的說明檔案長度，並導致使用 --explain 時效能降低。

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

--profile=file

這個選項會採用檔案名稱引數，讓 Bazel 將剖析資料寫入檔案。建構剖析檔有助於瞭解 Bazel 的 build 指令將時間花費在何處。如需設定檔格式和工具詳細資料，請參閱 JSON 追蹤設定檔。

--[no]show_loading_progress

這個選項會讓 Bazel 輸出套件載入進度訊息。如果停用這項功能，系統就不會顯示訊息。

--[no]show_progress

這個選項會顯示進度訊息，預設為開啟。如果停用這項設定，系統就不會顯示進度訊息。

--show_progress_rate_limit=n

這個選項會讓 Bazel 每 n 秒顯示最多一則進度訊息，其中 n 是實數。這個選項的預設值為 0.02，也就是說，Bazel 會將進度訊息限制為每 0.02 秒一則。

--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 shell 相容的語法列印，方便複製及貼到 shell 命令提示字元。(周圍的括號用於保護殼層免於 cd 和 exec 呼叫；請務必複製這些括號！) 不過，部分指令是在 Bazel 內部實作，例如建立符號連結樹狀結構。因此不會顯示指令列。

--subcommands=pretty_print 可以傳遞至 print，將指令的引數列印為清單，而非單行。這有助於提高長指令列的可讀性。

另請參閱下方的「--verbose_failures」--verbose_failures。

如要以工具友善格式將子指令記錄到檔案中，請參閱 --execution_log_json_file 和 --execution_log_binary_file。

--verbose_failures

這個選項會讓 Bazel 的執行階段列印失敗指令的完整指令列。這對偵錯失敗的建構作業非常有用。

系統會以與 Bourne Shell 相容的語法列印失敗的指令，方便您複製並貼到 Shell 提示中。

工作區狀態

使用這些選項「蓋章」Bazel 建構的二進位檔：將額外資訊 (例如來源控制修訂版本或其他工作區相關資訊) 嵌入二進位檔。您可以在支援 stamp 屬性的規則中使用這項機制，例如 genrule、cc_binary 等。

--workspace_status_command=program

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

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

程式應將零或多個鍵/值配對輸出至標準輸出，每行一個項目，然後以零結束 (否則建構作業會失敗)。金鑰名稱可以是任何內容，但只能使用大寫字母和底線。鍵名後的第一個空格會將鍵名與值分開。這個值是該行的其餘部分 (包括額外的空白字元)。鍵和值都不得跨越多行。鍵不得重複。

Bazel 會將鍵分割成兩個 bucket：「穩定」和「不穩定」。(「穩定」和「不穩定」這兩個名稱有點違反直覺，因此不必多想。)

接著，Bazel 會將鍵/值組合寫入兩個檔案：

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

合約如下：

• 「穩定」鍵的值應盡量不要變更。如果 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() 的值除以 1000)
  • FORMATTED_DATE：建構時間，格式為 yyyy MMM d HH mm ss EEE(例如 2023 年 6 月 2 日 01:44:29 週五)，以世界標準時間表示。

在 Linux/macOS 上，您可以傳遞 --workspace_status_command=/bin/true 來停用擷取工作區狀態，因為 true 不會執行任何動作，會成功 (以零結束) 且不會列印任何輸出內容。在 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

可做為執行平台來執行動作的平台。 平台可以指定為確切目標，或指定為目標模式。系統會優先考量這些平台，再考量 MODULE.bazel 檔案中以 register_execution_platforms() 宣告的平台。這個選項接受以半形逗號分隔的平台清單，並依優先順序排列。如果多次傳遞這個標記，系統會以最近一次傳遞的標記為準。

--extra_toolchains=labels

在工具鍊解析期間要考量的工具鍊規則。工具鍊可以指定確切目標，也可以指定目標模式。系統會優先考量這些工具鍊，再考量 MODULE.bazel 檔案中以 register_toolchains() 宣告的工具鍊。

--toolchain_resolution_debug=regex

如果工具鍊類型符合規則運算式，請在尋找工具鍊時列印偵錯資訊。多個規則運算式之間以半形逗號分隔。在開頭使用 - 即可否定規則運算式。這有助於 Bazel 或 Starlark 規則的開發人員，解決因缺少工具鍊而導致的偵錯失敗問題。

其他

--flag_alias=alias_name=target_path

便利標記，用於將較長的 Starlark 建構設定繫結至較短的名稱。詳情請參閱「Starlark 設定」。

--symlink_prefix=string

變更產生的便利符號連結前置字串。符號連結前置字串的預設值為 bazel-，這會建立 bazel-bin、bazel-testlogs 和 bazel-genfiles 符號連結。

如果因故無法建立符號連結，系統會發出警告，但建構仍視為成功。特別是，這可讓您建構唯讀目錄，或您沒有寫入權限的目錄。如果符號連結指向預期位置，建構完成時在資訊訊息中列印的任何路徑，都只會使用符號連結相對的簡短形式；換句話說，即使您無法依賴所建立的符號連結，仍可依賴這些路徑的正確性。

這個選項的常見值包括：

• 禁止建立符號連結： --symlink_prefix=/ 會導致 Bazel 不建立或更新任何符號連結，包括 bazel-out 和 bazel-<workspace> 符號連結。使用這個選項可完全禁止建立符號連結。

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

--platform_suffix=string

在設定簡稱中加入後置字串，用於判斷輸出目錄。將這個選項設為不同值，可將檔案放入不同目錄，例如改善建構的快取命中率 (否則建構會互相覆寫輸出檔案)，或保留輸出檔案以供比較。

--default_visibility=(private|public)

暫時性標記，用於測試 Bazel 預設顯示設定變更。不適用於一般用途，但為了完整性而記錄。

--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 指令 svg、web 和 list。

使用 Bazel 發布

軟體工程師在開發週期中會使用 Bazel，發布工程師準備要部署至正式環境的二進位檔時也會使用 Bazel。本節列出使用 Bazel 的發布工程師適用的提示。

重要選項

使用 Bazel 進行發布建構時，會發生與其他執行建構作業的指令碼相同的問題。詳情請參閱「從指令碼呼叫 Bazel」。我們特別強烈建議使用下列選項：

• --bazelrc=/dev/null
• --nokeep_state_after_build

以下選項也很重要：

• --package_path
• --symlink_prefix： 如要管理多個設定的建構作業，建議使用不同的 ID 區分每個建構版本，例如「64 位元」和「32 位元」。這個選項會區分 bazel-bin (等) 符號連結。

執行測試

如要使用 Bazel 建構及執行測試，請輸入 bazel test，然後輸入測試目標的名稱。

根據預設，這個指令會同時執行建構和測試活動，建構所有指定目標 (包括指令列上指定的任何非測試目標)，並在建構 *_test 和 test_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 會回報錯誤訊息 (「test result is not up-to-date」)，並將測試的狀態記錄為「NO STATUS」(如果已啟用顏色輸出，則為紅色)，且會傳回非零的結束代碼。

這個選項也表示 --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 屬性，則可嘗試 3 次。您可以指定整數值，覆寫測試嘗試次數上限。為避免濫用系統，Bazel 最多允許 10 次測試。

--runs_per_test=[regex@]number

這個選項會指定每個測試的執行次數。所有測試執行作業都會視為個別測試 (每個測試都會單獨套用備援功能)。

執行失敗的目標狀態取決於 --runs_per_test_detects_flakes 旗標的值：

• 如果沒有這個屬性，任何失敗的執行作業都會導致整個測試失敗。
• 如果存在，且來自相同分片的兩次執行分別傳回 PASS 和 FAIL，則測試會收到不穩定狀態 (除非其他失敗的執行導致測試失敗)。

如果指定單一數字，所有測試都會執行該次數。或者，您也可以使用 regex@number 語法指定規則運算式。這會將 --runs_per_test 的效果限制在符合 regex 的目標 (--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 會列出所有已完成的測試，以及含有測試輸出內容的檔案名稱 (如果測試失敗)。這是預設值。
• short_uncached 類似 short，但會省略結果已快取的測試。
• terse 只會列出失敗和不穩定的測試。
• detailed 會列出所有已完成執行的測試，並列印每個個別測試案例 (通過、略過和失敗)。測試輸出檔案的名稱已省略。
• detailed_uncached 類似 detailed，但會省略結果已快取的測試。
• testcase 會在測試案例解決時列印摘要，但不會提供失敗測試案例的詳細資訊。
• none 不會列印測試摘要。

--test_output=output_style

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

• summary 顯示每項測試是否通過或失敗的摘要。也會顯示失敗測試的輸出記錄檔名。摘要會在建構完成時列印 (建構期間，測試開始、通過或失敗時，只會顯示簡單的進度訊息)。此為預設行為。
• errors 只會將失敗測試的 stdout/stderr 彙整輸出內容傳送至 stdout，確保並行測試的輸出內容不會交錯。在建構時列印摘要，如上方的摘要輸出內容所示。
• all 與 errors 類似，但會輸出所有測試的結果，包括通過的測試。
• 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 會從測試大小推斷逾時限制，並將這些逾時用於所有測試，無論大小是隱含或明確設定。

如果測試明確指出逾時類別與大小不同，則會收到與大小標記隱含設定逾時時相同的值。因此，宣告「long」逾時的「small」大小測試，與沒有明確逾時的「large」測試，有效逾時時間相同。

--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 Shell 權杖化規則分割成字詞，然後將字詞清單加到要執行的指令前面。

如果第一個字是完整標籤 (開頭為 //)，系統就會建構該標籤。然後，標籤會替換為相應的可執行檔位置，並加到命令的前面，與其他字詞一起執行。

注意事項：

• 用於執行測試的 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 類似，但用於建構及執行單一目標。以下是典型的工作階段 (//java/myapp:myapp 會打招呼並列印引數)：

  % bazel run java/myapp:myapp -- --arg1 --arg2
  INFO: Analyzed target //java/myapp:myapp (13 packages loaded, 27 targets configured).
  INFO: Found 1 target...
  Target //java/myapp:myapp up-to-date:
    bazel-bin/java/myapp/myapp
  INFO: Elapsed time: 14.290s, Critical Path: 5.54s, ...
  INFO: Build completed successfully, 4 total actions
  INFO: Running command line: bazel-bin/java/myapp/myapp <args omitted>
  Hello there
  $EXEC_ROOT/java/myapp/myapp
  --arg1
  --arg2

  % bazel clean --expunge

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

% bazel info server_pid
1285

  % bazel info --show_make_env -c opt COMPILATION_MODE
  opt

% 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

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

adb -s deadbeef install ...

    % bazel --host_jvm_args=-javaagent:$BAZEL/third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.4.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.4.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.4.jar \
    --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
    dump --skylark_memory=$HOME/prof.gz
    % pprof -flame $HOME/prof.gz

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

 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 --server_javabase=/usr/local/buildtools/java/jdk build //foo

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