指令和選項

回報問題 查看來源

本頁面說明各種 Bazel 指令 (例如 bazel build、bazel run 和 bazel test) 可用的選項。本頁面是 使用 Bazel 進行建構中 Bazel 指令清單的隨附說明。

目標語法

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

選項

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

大部分選項只能指定一次。多次指定時，最後一個例項將勝出。可多次指定的選項會在線上說明中註明「可能多次使用」文字。

套件位置

--package_path

此選項會指定要搜尋的目錄集，以尋找指定套件的 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 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)

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

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

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

Bazel 的 --strip 選項會與舊版的 --strip-debug 選項對應：它只會刪除偵錯資訊。如果出於某些原因，想要移除「所有」符號，而不只是「偵錯」符號，您必須使用舊的 --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」選項。

--[no]output_symbol_counts

啟用後，每個 C++ 執行檔二進位檔的黃金叫用連結都會透過 --print-symbol-counts 黃金選項，輸出一個「符號計數」檔案。針對每個連結器輸入內容，檔案會記錄定義的符號數量，以及二進位檔中使用的符號數量。這項資訊可用於追蹤不必要的連結依附元件。符號計數檔案會寫入二進位檔的輸出路徑，名稱為 [targetname].sc。

這個選項預設為停用。

--java_language_version=version

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

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

，且僅允許與 Java 8 規格相容的建構項目。預設值為 11。--> 可能的值包括：8、9、10、11、14 和 15，且可以透過 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 應用程式。

預設值為 localjdk。可能的值包括：localjdk、localjdk_version、remotejdk_11 和 remote_jdk17。您可以使用 local_java_repository 或 remote_java_repostory 存放區規則註冊自訂 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 內建預設選項之後和每個規則的選項之前傳送至 javac。所有 javac 選項的最後一個規格皆勝出。javac 的預設選項如下：

  -source 8 -target 8 -encoding UTF-8

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

這個選項會控制 javac 是否檢查缺少直接依附元件。Java 目標必須明確宣告所有直接使用的目標為依附元件。這個標記會指示 javac 判斷 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 架構名稱。

--fat_apk_cpu=cpu[,cpu]*

針對 android_binary 規則遞移 deps 中用於建構 C/C++ 程式庫的 CPU。其他 C/C++ 規則不會受到影響。舉例來說，如果 cc_library 出現在 android_binary 規則和 cc_binary 規則的轉換 deps 中，系統會為 android_binary 規則指定的每個 CPU 至少建構一次：一次是針對 android_binary 規則指定的每個 CPU 一次，並針對 cc_binary 規則指定的 CPU，一次建構 --cpu。cc_library--fat_apk_cpu

預設為 armeabi-v7a。

系統會針對使用 --fat_apk_cpu 指定的每個 CPU，在 APK 中建立一個 .so 檔案並封裝。.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 代表規則運算式，開頭可加上 + 以識別包含模式，加上 - 來識別排除模式。option 代表傳遞至 C++ 編譯器的任意選項。如果選項包含 ,，就必須以引號括住 \,。選項也可以包含 @，因為只有第一個 @ 是用來分隔規則運算式與選項。

範例：--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs 針對 //foo/ 內所有 .cc 檔案 (file.cc 除外)，在 C++ 編譯器的指令列中加入 -O0 和 -fprofile-arcs 選項。

--dynamic_mode=mode

決定是否以動態方式連結 C++ 二進位檔，與建構規則的連結靜態屬性互動。

模式：

  • auto：轉譯為平台獨立模式；default 適用於 Linux，off 適用於 cygwin。
  • default：允許 bazel 選擇是否要動態連結。詳情請參閱連結靜態一節。
  • fully：動態連結所有目標。這樣可以加快連結時間，並減少所產生二進位檔的大小。
  • off：連結大部分靜態模式下的所有目標。如果已在連結選擇中設定 -static，目標將變更為完全靜態。

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

啟用Fission，將 C++ 偵錯資訊寫入專屬的 .dwo 檔案，而不是 .o 檔案，否則就會發生這種情況。這會大幅減少連結的輸入大小，並縮短連結時間。

設為 [dbg][,opt][,fastbuild] (例如 --fission=dbg,fastbuild) 時，系統只會針對指定的一組編譯模式啟用資監控功能。這適用於 bazelrc 設定。如果設為 yes，則通用啟動會啟用。如果設為 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_resourcesattribute 預設值；詳情請參閱該規則的說明文件。預設為關閉。

--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++ 規則的跨工具。針對這些目標，這個標記會覆寫 --crosstool_top。

--android_crosstool_top=label

這個跨工具可用於在 android_binary 規則的遞移 deps 中編譯 C/C++ 規則。如果建構中的其他目標需要不同的跨工具，這就非常實用。預設值為使用 WORKSPACE 檔案中的 android_ndk_repository 規則產生的 Crosstool。另請參閱 --fat_apk_cpu。

--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 run、bazel test 以及由 java_binary 和 java_test 規則建構的 Java 二進位檔使用。JAVABASE 和 JAVA 「Make」變數衍生自這個選項。

--host_javabase=label

這個選項會設定要在主機設定中使用的基本 Java 安裝標籤，例如用於主機建構工具 (包括 JavaBuilder 和 Singlejar)。

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

執行策略

這些選項會影響 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_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 策略執行「編譯 //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 在將建構作業和測試活動安排在本機執行時納入考量。選用值可以是整數或關鍵字 (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 格式的路徑存取執行檔案。執行檔案樹狀結構可確保測試存取位於其宣告依附元件的所有檔案，除此之外沒有其他內容。根據預設，系統會建構一組所需檔案的符號連結來實作執行檔案樹狀結構。隨著連結集的增加，這項作業的成本也會增加，而對某些大型版本而言，這可能會大幅縮短整體建構時間，特別是因為每個個別測試 (或應用程式) 都需要自己的 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 的輸出內容來編譯相依的 java_library 目標，而會建立介面 jars 來只包含非私人成員 (公開、受保護及預設 (套件) 的存取方法和欄位) 的簽名，並使用介面 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，則建構)。測試大小篩選器是以逗號分隔的測試大小值 (小、中、大或大) 清單指定，可選擇性地在前面加上「-」符號，表示排除的測試大小。舉例來說，

  % 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=lang[,lang]*

針對使用官方 *_test 規則的語言指定逗號分隔的測試語言清單 (如需這些語言的完整清單，請參閱建構百科全書)。每種語言可以在前面加上「-」來指定排除的語言。每種語言使用的名稱都應與 *_test 規則中的語言前置字串相同，例如 cc、java 或 sh。

如有指定，Bazel 只會測試指定語言的測試目標 (如果一併指定 --build_tests_only，則不會進行建構)。

舉例來說，

  % bazel test --test_lang_filters=cc,java foo/...

只會測試 foo/... 中的 C/C++ 和 Java 測試 (分別使用 cc_test 和 java_test 規則定義)，而

  % bazel test --test_lang_filters=-sh,-java foo/...

將執行 foo/... 中的所有測試 (sh_test 和 java_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。如果超過這個門檻，系統就不會顯示個別目標的結果資訊。因此 0 會導致結果資訊一律隱藏，而值非常大會導致結果一律顯示。

如果使用者會定期在建構一小群目標 (例如編譯-編輯測試週期期間) 與大量目標群組 (例如建立新工作區或執行迴歸測試) 之間進行替代，可能就希望選擇介於上述兩個值之間的值。在先前的案例中，結果資訊非常實用，而後者則較不實用。和所有選項一樣，您可以透過 .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 殼層相容的語法顯示，以便您輕鬆地複製及貼至殼層命令提示字元。(系統會提供括號內的括號，防止您的殼層受到 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 會將金鑰分成「穩定」和「揮發性」兩種值區。(「穩定」和「揮發性」這類名稱有點違反直覺，因此您不必思考這些名稱)。

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 日 1 月 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 屬性，針對個別規則明確啟用或停用時間戳記。詳情請參閱「版本百科全書」。規則設定 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-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 預設瀏覽權限變更的臨時標記。不適合一般用途，但須以完整方式記錄。

--[no]use_action_cache

這個選項預設為啟用。如果停用，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 要求多次測試執行作業
  • 測試失敗

如果設為「no」，所有測試都會無條件執行。

如果設為「是」，快取行為將與 Auto 一樣，但可能會快取測試失敗和使用 --runs_per_test 的測試執行。

如果已在 .bazelrc 檔案中預設啟用此選項，使用者可能會發現 -t (開啟) 或 -t- (關閉) 縮寫，方便在特定執行作業上覆寫預設值。

--check_tests_up_to_date

這個選項會指示 Bazel 不要執行測試，而只會檢查及回報快取的測試結果。如有任何之前並未建構及執行的測試，或是測試結果過舊 (例如因為原始碼或建構選項已變更)，Bazel 將回報錯誤的錯誤訊息 (「測試結果不是最新」，如果已啟用顏色輸出功能，則會將測試的狀態記錄為「NO STATUS」；如果啟用顏色輸出功能為紅色)，則會傳回非零狀態代碼。

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

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

--test_verbose_timeout_warnings

如果測試的逾時時間明顯比測試的實際執行時間長，此選項會指示 Bazel 明確警告使用者。雖然應設定測試的逾時時間以避免不穩定，但如果測試的逾時時間過於過多，可能會隱藏意外裁剪的真實問題。

舉例來說，測試通常會在一或兩分鐘內執行，因此「ETERNAL」或「長版」的逾時值不大，因此不會過於寬鬆。

這個選項可協助使用者決定良好的逾時值，或健全的檢查現有逾時值。

--[no]test_keep_going

根據預設，所有測試都會執行完成。不過，如果停用此標記，系統就會在任何非通過的測試中取消建構作業。系統不會執行後續的建構步驟和測試叫用，而且會取消執行中的叫用。請勿同時指定 --notest_keep_going 和 --keep_going。

--flaky_test_attempts=attempts

這個選項會指定測試因任何原因失敗時應嘗試的次數上限。如果測試一開始失敗，但最終成功，在測試摘要中會回報為 FLAKY。不過，在找出 Bazel 結束代碼或通過的測試總數時，系統會將這些視為通過。如果測試失敗所有允許的嘗試，都會視為失敗。

根據預設 (如未指定此選項或設為預設值)，一般測試只能進行一次，以及 3 個設為 flaky 屬性的測試規則。您可以指定整數值來覆寫測試嘗試次數上限。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

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

或者，您也可以提供四個逗號分隔值，依順序指定短、中、長程和永恆測試的個別逾時。無論是哪種形式，任何測試大小的 0 或負值，都將取代特定逾時類別的預設逾時值，取代根據網頁編寫測試網頁所定義的逾時時間。根據預設，Bazel 會根據測試大小推斷出逾時限制，無論大小是間接或明確設定，都會將這些逾時用於所有測試。

如果測試明確指出其逾時類別與大小不同，測試收到的值會與大小標記以隱含方式設定的逾時值相同。因此，對宣告「長」逾時的「small」大小測試，將會有相同的有效逾時，也就是沒有明確逾時的「large」測試。

--test_arg=arg

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

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

指定每項測試必須在測試環境中插入的其他變數。如果未指定 value，則會從用來啟動 bazel test 指令的殼層環境沿用。

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

--run_under=command-prefix

這會指定要在執行前，將測試執行器插入測試指令之前的前置字串。系統會使用 Bourne 殼層代碼化規則將 command-prefix 分割為字詞，字詞清單後面會加到即將執行的指令前方。

如果第一個字詞是完整標籤 (開頭為 //)，則會建構該字詞。接著，標籤會替換成對應的可執行位置，而該位置前面會伴隨其他字詞一起執行的指令。

注意事項：

  • 用於執行測試的 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 建構的二進位檔，其行為則視要叫用的二進位檔是否為測試而定。

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

如果二進位檔是測試，目前的工作目錄會是執行根目錄，且為了複製環境測試通常會執行信念嘗試。然而，模擬並非完美無缺，使用多個資料分割的測試也無法以這種方式執行 (可以使用 --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 執行時，清理指令只會移除整個輸出基礎樹狀結構，以及 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 新增的依附元件。

範例：「在 BUILD 檔案中，顯示建構 PEBL 樹狀結構中所有測試所需的所有 GenRule 定義位置。」

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

查詢動作圖表

aquery 指令可讓您查詢建構圖中的動作。它會在進行後分析設定的目標圖上執行，並顯示關於動作、構件及其關係的資訊。

這項工具接受多種指令列選項。--output 會選取輸出格式。預設輸出格式 (text) 為人類可讀的格式，請使用 proto 或 textproto 做為機器可讀格式。值得注意的是，查詢指令會在一般 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 伺服器中的任何記憶體流失，都可能會導致該伺服器在某些情況下異常當機；執行條件式重新啟動作業會先佔此狀況。

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 行動安裝。

以下是支援的選項：

--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 指令會顯示 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

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 指令會使用 --profile 選項，分析先前在建構期間收集的資料。其中提供多個選項，讓您分析建構執行作業，或以指定格式匯出資料。

以下是支援的選項：

  • --dump 會以使用者可理解的格式顯示所有收集到的資料。但目前尚不支援其他格式。

如需格式詳細資料和使用說明，請參閱「剖析效能疑難排解」。

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 伺服器，且啟動選項不相符，伺服器就會重新啟動。

本節說明的所有選項都必須使用 --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_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 監獄中執行 razel 是必要的。

批次模式會在同一個 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 環境變數設為 dumb、emacs 或 xterm-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 就會為訊息加上時間戳記，指定訊息顯示時間。