指令和選項

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

本頁面將介紹各種 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，則 package-path 中的字串 %workspace% 會展開為 /home/bob/clients/bob_client/bazel。
  3. 其他任何內容則會以工作目錄為基準。這通常不是您想要執行的操作，如果您從 bazel 工作區以下的目錄使用 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 MODULE.bazel
  % 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)

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

  % 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 一節所述，此方法會在連結最終二進位檔後套用剝離動作，而不是在所有建構連結動作中加入剝離作業。

--stripopt=strip-option

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

--fdo_instrument=profile-output-dir

執行建構的 C/C++ 二進位檔時，--fdo_instrument 選項可用於產生 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 規格相容的建構項目。預設值為 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，並使用該版本執行 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 的任何選項，最後指定的規格會勝出。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 警告。
  • 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]*

建構 android_binary 規則的傳遞 deps 的平台 (特別適用於 C++ 等原生依附元件)。舉例來說，如果 cc_library 出現在 android_binary 規則的傳遞 deps 中，則會針對 android_binary 規則的 --android_platforms 指定的每個平台建構一次，並納入最終輸出內容。

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

系統會為使用 --android_platforms 指定的每個平台建立一個 .so 檔案，並將該檔案封裝在 APK 中。.so 檔案名稱的前置字串為 android_binary 規則的名稱加上「lib」。舉例來說，如果 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 代表規則運算式，可在前面加上 + 來識別納入模式，或加上 - 來識別排除模式。option 代表傳遞至 C++ 編譯器的任意選項。如果選項包含 ,，則必須加上引號，例如 \,。選項也可以包含 @，因為只有第一個 @ 用於將規則運算式與選項分隔開來。

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

--dynamic_mode=mode

判斷是否要動態連結 C++ 二進位檔，並與建構規則中的 linkstatic 屬性互動。

模式：

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

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

啟用 Fission，將 C++ 偵錯資訊寫入專用 .dwo 檔案，而非 .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++ 編譯作業。Bazel 會在該位置尋找 CROSSTOOL 檔案，並使用該檔案自動判斷 --compiler 的設定。

--host_crosstool_top=label

如果未指定，Bazel 會使用 --crosstool_top 的值，在執行設定中編譯程式碼，例如在建構期間執行的工具。這個標記的主要目的是啟用交叉編譯。

--apple_crosstool_top=label

在 objc*、ios* 和 apple* 規則的傳遞 deps 中，使用 crosstool 編譯 C/C++ 規則。針對這些目標，此標記會覆寫 --crosstool_top。

--compiler=version

這個選項會指定在建構期間用於編譯二進位檔的 C/C++ 編譯器版本 (例如 gcc-4.1.0)。如果您想使用自訂交叉工具進行建構，請使用 CROSSTOOL 檔案，而非指定這個標記。

--android_sdk=label

已淘汰，請勿直接指定此值。

這個選項會指定 Android SDK/平台工具鍊和 Android 執行階段程式庫，用於建構任何 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 的 --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

這些選項會指定本機資源的數量 (以 MB 為單位的 RAM 和 CPU 邏輯核心數量)，Bazel 在排定本機建構和測試活動時，會將這些資源納入考量。這些標記可接受整數，或可選搭配 [-|*float] 的字詞 (HOST_RAM 或 HOST_CPUS) (例如 --local_cpu_resources=2、--local_ram_resources=HOST_RAM*.5、--local_cpu_resources=HOST_CPUS-1)。這些標記是獨立的，可設定一個或兩個。根據預設，Bazel 會直接從本機系統的設定，估算 RAM 容量和 CPU 核心數量。

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

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

--[no]build_runfile_manifests

這個選項預設為啟用，可指定是否應將 runfile 資訊清單寫入輸出樹狀結構。停用該值則表示 --nobuild_runfile_links。

在遠端執行測試時，可以停用此選項，因為執行檔樹狀結構會從記憶體內的資訊清單中遠端建立。

--[no]discard_analysis_cache

啟用這個選項後，Bazel 會在執行作業開始前捨棄分析快取，進而為執行階段釋出額外的記憶體 (約 10%)。缺點是，後續的增量建構作業會變慢。另請參閱省記憶體模式。

--[no]keep_going (-k)

如同 GNU Make，建構作業的執行階段會在遇到第一個錯誤時停止。有時候，即使遇到錯誤，也要盡可能嘗試建構。這個選項會啟用該行為，並在指定時嘗試建構所有前置條件已成功建構的目標，但會忽略錯誤。

雖然這個選項通常與建構作業的執行階段相關，但也會影響分析階段：如果在建構指令中指定了多個目標，但只有部分目標可順利分析，則建構作業會停止並顯示錯誤，除非指定 --keep_going，否則建構作業會繼續執行階段，但只會針對已順利分析的目標執行。

--[no]use_ijars

這個選項會變更 Bazel 編譯 java_library 目標的方式。與使用 java_library 的輸出內容編譯依附的 java_library 目標不同，Bazel 會建立介面 JAR，其中只包含非私人成員 (public、protected 和預設 (package) 存取方法和欄位) 的簽名，並使用介面 JAR 編譯依附的目標。這樣一來，如果只變更類別的方法主體或私人成員，就不會重新編譯。

--[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) 指定大小的測試目標。測試大小篩選器的格式為逗號分隔的清單，列出允許的測試大小值 (small、medium、large 或 enormous)，可選擇在前方加上「-」號，用來表示排除的測試大小。例如：

  % 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、子字串或正規表示式。--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

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

--show_result=n

這個選項會控制 bazel build 指令結尾的結果資訊輸出作業。根據預設，如果指定單一建構目標，Bazel 會列印訊息，指出目標是否已成功更新，如果是的話，則會列出目標建立的輸出檔案清單。如果指定多個目標，系統不會顯示結果資訊。

雖然結果資訊對於單一或少數目標的建構作業可能很實用，但對於大型建構作業 (例如整個頂層專案樹狀結構)，這類資訊可能會過於繁雜且令人分心；這個選項可讓您控制這類資訊。--show_result 會採用整數引數，也就是要列印完整結果資訊的目標數量上限。預設值為 1。超過這個門檻後，系統就不會顯示個別目標的結果資訊。因此，零會一律抑制結果資訊，而非常大的值會一律列印結果。

如果使用者經常在建構小群目標 (例如在編譯-編輯-測試週期中) 和大群目標 (例如建立新工作區或執行回歸測試時) 之間切換，可能會選擇介於兩者之間的值。在前者中，結果資訊非常實用，但在後者中則較不實用。與所有選項一樣，您可以透過 .bazelrc 檔案隱含指定這項資訊。

系統會列印檔案，方便您將檔案名稱複製並貼到 Shell 中，以便執行已建構的可執行檔。每個目標的「最新」或「失敗」訊息，可以輕鬆透過驅動建構作業的指令碼進行剖析。

--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 殼層相容的語法列印指令，方便您將指令複製並貼到殼層命令提示字元視窗。(括號是為了保護您的殼層免受 cd 和 exec 呼叫的影響，請務必複製這些括號！)不過，某些指令是在 Bazel 內部實作，例如建立符號連結樹狀結構。這些檔案沒有可顯示的指令列。

--subcommands=pretty_print 可能會傳遞至列印指令的引數，以清單形式呈現，而非單一行。這可能有助於讓長的指令列更易讀。

另請參閱下方的 --verbose_failures。

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

--verbose_failures

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

失敗的指令會以 Bourne 殼層相容的語法列印，適合複製並貼到殼層提示。

工作區狀態

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

--workspace_status_command=program

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

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

程式應將零或多個鍵/值組合列印到標準輸出，每行一個項目，然後以零結束 (否則建構作業會失敗)。鍵名可以是任何名稱，但只能使用大寫英文字母和底線。鍵名稱後面的第一個空格會與值分開。值是該行剩餘的部分 (包括其他空格)。鍵和值都不能跨越多行。鍵不得重複。

Bazel 會將鍵分割為兩個值區：「穩定」和「易變」。(「stable」和「volatile」這兩個名稱有點違反直覺，因此請不要太在意)。

接著，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() 除以一千的值)
    • 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 路徑，以達到相同效果。

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

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

#!/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 屬性，針對個別規則明確啟用或停用戳記。詳情請參閱 Build Encyclopedia。當規則設定 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() 在 MODULE.bazel 檔案中宣告的平台。此選項會接受以逗號分隔的平台清單，並依優先順序排列。如果標記傳遞多次，則會以最近一次的標記覆寫。

--extra_toolchains=labels

在工具鍊解析期間要考慮的工具鍊規則。工具鍊可以使用確切目標或目標模式指定。這些工具鍊會在 register_toolchains() 在 MODULE.bazel 檔案中宣告的工具鍊之前考量。

--toolchain_resolution_debug=regex

如果工具鍊類型符合規則運算式，則在尋找工具鍊時會一併輸出偵錯資訊。多個規則運算式之間可使用半形逗號分隔。您可以使用開頭的 - 來否決規則運算式。這可能有助於 Bazel 或 Starlark 規則的開發人員，因為他們可能會因缺少工具鏈而發生除錯失敗。

其他

--flag_alias=alias_name=target_path

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

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

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

這個選項的一些常見值：

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

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

--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」。特別建議您採用下列選項：

以下選項也很重要：

  • --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 就會回報錯誤訊息 (「測試結果未更新」)，並將測試狀態記錄為「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 對符合規則運算式的目標的效果 (--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，確保同時進行的測試輸出內容不會相互交錯。根據上述摘要輸出內容，在建構期間列印摘要。
  • 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 會根據測試大小 (無論是隱含或明確設定) 推斷逾時限制，並為所有測試使用這些逾時限制。

如果測試明確指出逾時類別與大小不同，則會收到與 size 標記隱含設定的逾時值相同的值。因此，如果測試大小為「small」，並宣告「long」逾時時間，則有效逾時時間會與「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 指令的殼層環境繼承 value。

您可以使用 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 會說出「hello」，並列印其 args)：

  % 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 run 與直接叫用由 Bazel 建構的二進位檔相似，但行為不同，這取決於要叫用的二進位檔是否為測試檔案。

如果二進位檔不是測試，目前的工作目錄會是二進位檔的執行檔樹狀結構。

如果二進位檔是測試，目前的工作目錄會是執行根目錄，並且會盡力複製通常用於執行環境測試的環境。不過，模擬功能並非完美無缺，且無法以這種方式執行含有多個區塊的測試 (可使用 --test_sharding_strategy=disabled 指令列選項來解決這個問題)

二進位檔也支援下列額外的環境變數：

  • BUILD_WORKSPACE_DIRECTORY：執行建構作業的工作區根目錄。
  • BUILD_WORKING_DIRECTORY：Bazel 執行所在的目前工作目錄。
  • BUILD_ID：bazel run 叫用項的建構 ID。這通常是唯一的值，除非 Bazel 是使用 --script_path 執行，且產生的指令碼已重複使用。
  • BUILD_EXECROOT：bazel run 呼叫的執行根目錄。

例如，您可以使用這些字元，以友善的方式解讀指令列上的檔案名稱。

「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) 是人類可讀格式，請使用 proto 或 textproto 來提供機器可讀格式。值得注意的是，aquery 指令會在一般 Bazel 建構作業上執行，並繼承建構期間可用的選項組合。

它支援傳統 query 可用的函式，但 siblings、buildfiles 和 tests 則不支援。

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

其他指令和選項

help

help 指令提供線上說明。根據預設，這項指令會顯示可用指令和說明主題的摘要，如「使用 Bazel 進行建構」所示。指定引數後，系統會顯示特定主題的詳細說明。大部分主題都是 Bazel 指令，例如 build 或 query，但也有一些與指令不相符的其他說明主題。

--[no]long (-l)

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

shutdown

您可以使用 shutdown 指令停止 Bazel 伺服器程序。這項指令會讓 Bazel 伺服器在閒置時立即結束 (例如，在任何建構或其他目前進行中指令完成後)。詳情請參閱「用戶端/伺服器導入」。

Bazel 伺服器會在閒置逾時後自動停止，因此很少需要使用這個指令；不過，如果您知道特定工作區不會再進行建構作業，則這個指令在指令碼中可能會很實用。

shutdown 接受一個選項 --iff_heap_size_greater_than _n_，需要整數引數 (以 MB 為單位)。如果指定此值，系統會根據已用盡的記憶體量決定是否關閉應用程式。這對於啟動大量建構作業的指令碼很有幫助，因為 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-size、committed-heap-size、max-heap-size：回報各種 JVM 堆積大小參數。分別為：目前使用的記憶體、目前保證可從系統提供給 JVM 的記憶體，以及可分配的最大記憶體。

  • gc-count、gc-time：自此 Bazel 伺服器啟動以來，垃圾收集的累積次數，以及執行垃圾收集所花費的時間。請注意，這些值不會在每次建構作業開始時重設。

  • package_path：以冒號分隔的路徑清單，Bazel 會根據此清單搜尋套件。格式與 --package_path 建構指令列引數相同。

範例：Bazel 伺服器的程序 ID。

% bazel info server_pid
1285

設定專屬資料

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

  • bazel-bin、bazel-testlogs、bazel-genfiles：回報建構作業產生的程式所在的 bazel-* 目錄絕對路徑。這通常 (但不一定) 與在成功建構後，在基礎工作區目錄中建立的 bazel-* 符號連結相同。不過，如果工作區目錄為唯讀，就無法建立 bazel-* 符號連結。使用 bazel info 回報的值，而非假設存在符號連結的腳本，會更為穩健。
  • 完整的「Make」環境。如果指定 --show_make_env 標記，目前設定的「Make」環境中所有變數 (例如 CC、GLIBC_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，或是否要回報錯誤。其中一些有趣的值包括：

  • changelist：這個版本的 Bazel 發布時的變更清單。
  • label：這個 Bazel 例項的發布標籤，如果不是已發布的二進位檔，則為「開發版本」。回報錯誤時非常實用。

bazel --version 在沒有其他引數的情況下，會產生與 bazel version --gnu_format 相同的輸出內容，但不會產生可能啟動 Bazel 伺服器或解開伺服器封存檔的副作用。bazel --version 可從任何位置執行，不需要工作區目錄。

mobile-install

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

詳情請參閱 bazel mobile-install。

支援下列選項：

--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_ 有：

  • 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 伺服器的內部狀態轉儲內容列印至 stdout。這個指令主要供 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

系統會在 third_party/allocation_instrumenter/java-allocation-instrumenter-3.3.0.jar 將 Java 代理程式檢查至 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 選項可用於選取不同的指令。目前僅支援 build 和 test。指定指令不支援的選項會導致錯誤。

舉例來說：

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

啟動選項

本節所述的選項會影響 Bazel 伺服器程序所使用的 Java 虛擬機器啟動作業，並套用至該伺服器處理的所有後續指令。如果已啟動 Bazel 伺服器，但啟動選項不相符，系統會重新啟動 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/jdk 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_binary 和 java_test 程式支援的 --jvm_flags 引數。或者，您也可以在測試中使用 bazel test --test_arg=--jvm_flags=foo ...。

--host_jvm_debug

這個選項會讓 Java 虛擬機器在呼叫 Bazel 本身的主方法前，等待 JDWP 相容偵錯工具的連線。這項功能主要供 Bazel 開發人員使用。

--autodetect_server_javabase

這個選項會讓 Bazel 在啟動時自動搜尋已安裝的 JDK，並在無法使用內嵌 JRE 時改用已安裝的 JRE。--explicit_server_javabase 可用於挑選要用來執行 Bazel 的明確 JRE。

--batch

批次模式會導致 Bazel 不使用標準用戶端/伺服器模式，而是為單一指令執行 Bazel Java 程序，這類程序可用於針對信號處理、工作控制和環境變數繼承，提供更可預測的語意，並且在 chroot 監獄中執行 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 值，指令碼就能確保如果導致新伺服器啟動，該伺服器會立即結束，但如果已啟動伺服器，該伺服器會繼續運作，直到閒置時間達到平常時間為止。當然，現有伺服器的閒置計時器也會重設。

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

設定最佳努力 I/O 排程的等級 (0 到 7)。0 為最高優先順序，7 為最低優先順序。預測排程器最多只會執行優先順序 4 的工作。系統會忽略負值。

--batch_cpu_scheduling

使用 batch CPU 排程功能為 Bazel 排程。這項政策適用於非交互式工作負載，但不想降低其優先順序值。請參閱「man 2 sched_setscheduler」。這項政策可能會提供更好的系統互動性，但會犧牲 Bazel 吞吐量。

其他選項

--[no]announce_rc

控制 Bazel 是否在啟動時宣告從 bazelrc 檔案讀取的啟動選項和指令選項。

--color (yes|no|auto)

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

如果這個選項設為 yes，系統就會啟用彩色輸出功能。如果這個選項設為 auto，Bazel 只會在輸出內容傳送至終端機，且 TERM 環境變數設為 dumb、emacs 或 xterm-mono 以外的值時，才會使用彩色輸出內容。如果這個選項設為 no，無論輸出內容是否會傳送至終端機，也不論 TERM 環境變數的設定為何，系統都會停用彩色輸出功能。

--config=name

從 rc 檔案選取其他設定區段；對於目前的 command，如果有此區段，也會從 command:name 提取選項。可多次指定，以便從多個設定區段新增標記。展開項目可以參照其他定義 (例如展開項目可以連結)。

--curses (yes|no|auto)

這個選項會決定 Bazel 是否會在螢幕輸出內容中使用游標控制項。這會減少捲動資料，並提供更精簡、易讀的 Bazel 輸出串流。這項功能與 --color 搭配使用時效果最佳。

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

--[no]show_timestamps

如果指定時間戳記，系統會在 Bazel 產生的每則訊息中加入時間戳記，指定訊息顯示的時間。