指令和選項

本頁說明各種 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++ 或組合程式碼叫用引數時，就會將引數傳遞至編譯器。連結時不會傳遞這個 ID。

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

  % 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 表示絕不會移除偵錯資訊。--strip=sometimes 的預設值表示 --compilation_mode 為 fastbuild 時會移除。

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

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

Bazel 的 --strip 選項與 ld 的 --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 的 Bazel 內建預設選項之後，以及個別規則選項之前，這個選項會傳遞至 javac。Javac 任何選項的最後規格可勝出。Javac 的預設選項如下：

  -source 8 -target 8 -encoding UTF-8

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

這個選項可控制 javac 是否檢查缺少直接依附元件。Java 目標必須明確宣告所有直接使用的目標做為依附元件。這個標記會指示 javac 判斷實際用於檢查每個 Java 檔案的型別的 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 規則以 --fat_apk_cpu 指定的每個 CPU 建構一次；如果是針對 cc_binary 規則以 --cpu 指定的 CPU 建立一次，則建構至少一次。cc_library

預設為 armeabi-v7a。

系統會為使用 --fat_apk_cpu 指定的每個 CPU，建立一個 .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 會針對 //foo/ 中的所有 .cc 檔案，將 -O0 和 -fprofile-arcs 選項新增至 C++ 編譯器的指令列中 (file.cc 除外)。

--dynamic_mode=mode

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

模式：

  • auto：轉譯為平台專屬模式；default 代表 Linux，off 代表 cygwin。
  • default：允許 bzel 選擇是否以動態方式連結。詳情請參閱連結靜態。
  • fully：以動態方式連結所有目標。如此便能加快連結時間，並縮減產生的二進位檔。
  • off：以大部分靜態模式連結所有目標。如果 -static 在 linkopt 當中設定，目標將變更為完全靜態。

--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 檔案的所有 -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 中編譯 C/C++ 規則的交叉工具。針對這些目標，此標記會覆寫 --crosstool_top。

--android_crosstool_top=label

用於在 android_binary 規則遞移 deps 中編譯 C/C++ 規則的交叉工具。如果建構中的其他目標需要不同的交叉工具，這項功能就能派上用場。根據預設，系統會使用 WORKSPACE 檔案中的 android_ndk_repository 規則產生的交叉工具。另請參閱 --fat_apk_cpu。

--compiler=version

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

--android_sdk=label

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

如果 WORKSPACE 檔案中定義了 android_sdk_repository 規則，系統會自動選取 Android SDK。

--java_toolchain=label

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

--host_java_toolchain=label

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

--javabase=(label)

這個選項會設定基本 Java 安裝作業的 label，以便用於 bazel run、bazel 測試，以及由 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) 。如要瞭解支援的策略及其影響，請參閱 --spawn_strategy。

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

這個選項會指定執行指令時，應採用哪種策略來執行說明與特定 regex_filter 相符的指令。如要進一步瞭解 regex_filter 比對，請參閱 --per_file_copt。如要瞭解支援的策略及其影響，請參閱 --spawn_strategy。

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

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

--genrule_strategy=strategy

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

--jobs=n (-j)

這個選項會使用整數引數，指定在建構執行階段期間應並行執行的工作數量限制。

--progress_report_interval=n

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

預設值為 0，表示遞增演算法：第一個報表會在 10 秒後輸出，接著是 30 秒，之後每分鐘會回報該進度一次。

當 bazel 使用遊標控制項 (由 --curses 指定) 時，系統會每秒回報進度。

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

這些選項會指定 Bazel 在排定在本機執行建構和測試活動時，可考慮的本機資源量 (以 MB 為單位，以及 CPU 邏輯核心數量)。它們可使用整數或關鍵字 (HOST_RAM 或 HOST_CPUS)，後面可視需要加上 [-|*float] (例如 --local_cpu_resources=2、--local_ram_resources=HOST_RAM*.5、--local_cpu_resources=HOST_CPUS-1)。標記是獨立的，或兩者皆可設定。根據預設，Bazel 會直接透過本機系統設定估算 RAM 和 CPU 核心數。

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

執行測試 (或應用程式) 時，系統會集中收集其執行階段資料依附元件。在 Bazel 的輸出樹狀結構中，這個「執行檔案」樹狀結構通常擁有 Root 權限，也就是對應二進位檔或測試的同層。在測試執行期間，您可以使用 $TEST_SRCDIR/workspace/packagename/filename 格式的路徑存取執行檔案。執行檔案樹狀結構可確保測試可以存取其具有宣告依附元件的所有檔案，並且不允許存取其他檔案。根據預設，執行檔案樹狀結構時，會建構一組指向所需檔案的符號連結，隨著連結集的增長，這項作業的成本會日漸增加，而在某些大型建構作業中，這麼做也會大幅增加整體建構時間，尤其是由於每個測試 (或應用程式) 都需要專屬的執行檔案樹狀結構。

--[no]build_runfile_manifests

這個選項預設為啟用，會指定是否應將 runfiles 資訊清單寫入輸出樹狀結構。停用此功能意味著 --nobuild_runfile_links。

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

--[no]discard_analysis_cache

啟用這個選項後，Bazel 會在開始執行前立即捨棄分析快取，進而釋出執行階段的額外記憶體 (約 10%)。缺點是進一步漸進式建構的速度較慢。另請參閱「記憶體節省模式」。

--[no]keep_going (-k)

和 GNU Make 一樣，發生第一個錯誤時，建構的執行階段會停止。有時候，即使遇到錯誤，嘗試建構越可能很有用。這個選項會啟用該行為，指定該模式時，建構將嘗試建構每個已順利完成先決條件的目標，但會忽略錯誤。

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

--[no]use_ijars

這個選項會變更 Bazel 編譯 java_library 目標的方式。Bazel 會建立僅包含非私人成員 (公開、受保護和預設 (套件) 存取方法和欄位) 的介面 jar，而不是使用 java_library 的輸出內容來編譯相依目標。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=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

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

--show_result=n

這個選項可控制 bazel build 指令結尾的結果資訊列印方式。根據預設，如果指定單一建構目標，Bazel 會輸出訊息，指出目標是否已成功推送最新狀態，以及如果指定，還會顯示目標建立的輸出檔案清單。如果指定多個目標，則不會顯示結果資訊。

雖然結果資訊對於單一目標的建構或數個目標的建構可能很有用，但對於大型建構作業 (例如整個頂層專案樹狀結構) 而言，這項資訊可能會令人頭昏眼花並分心；這個選項可讓您控制權限。--show_result 會採用整數引數，這是應列印完整結果資訊的目標數量上限。根據預設，這個值為 1。如果高於這個門檻，系統就不會顯示個別目標的結果資訊。因此，零會導致結果資訊總是受到抑制，而非常大的值會導致系統一律列印結果。

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

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

--sandbox_debug

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

--subcommands (-s)

這個選項會讓 Bazel 的執行階段先列印每個指令的完整指令列，再執行指令。

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

在可能的情況下，指令會以 Bourne 殼層相容的語法列印，以便輕鬆複製並貼到殼層指令提示中。(提供括號來保護殼層不受 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() 的值除以一千)

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

用於測試邊框預設瀏覽權限變更的臨時旗標。不可用於一般用途，但僅用於完整檢查。

--[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 (例如「64bit」與「32bit」) 區分每個版本可能會較為方便。這個選項會區分 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](#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 結束程式碼或通過測試總數時，就會將其視為傳遞。如果測試未通過所有允許的嘗試，就會視為失敗。

根據預設 (如未指定這個選項或設為預設值)，一般測試只能嘗試一次，而 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

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

或者，您也可以提供四個以半形逗號分隔的值，分別指定短期、中、長和四元測試 (依此順序) 的個別逾時值。不論是哪一種形式，所有測試大小的零或負值將替換為撰寫測試頁面所定義的指定逾時類別預設逾時值。根據預設，Bazel 會根據測試的大小推論逾時限制，無論大小為隱含或明確設定，Bazel 會在所有測試中使用這些逾時。

明確指出逾時類別與其大小不同的測試，收到的值會與大小標記以明確設定的方式設定逾時值相同。因此，如果測試宣告「長」逾時的大小，測試將採用與「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

這可指定測試執行器要在測試指令前面插入的前置字串。command-prefix 會使用 Bourne 殼層權杖化規則分割為字詞，然後將字詞清單加在要執行的指令前面。

如果第一個字詞是完整標籤 (開頭為 //)，則會建構該字詞。然後，會將標籤替換成附加在指令前面的對應執行檔位置，這個位置會與其他字詞一起執行。

請留意以下事項：

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

示例：

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

測試選項

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

其他bazel test選項

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

執行中的執行檔

bazel run 指令與 bazel build 相似，但用於建構「並執行」單一目標。下方是一般課程：

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

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

bazel run 與 Bazel 建構的二進位檔類似，但並非完全相同，其行為會因要叫用的二進位檔是否為測試而不同。

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

如果二進位檔屬於測試性質，目前的工作目錄將是執行根目錄，且會利用善意嘗試複製執行環境測試。不過，模擬並非完美無缺，且無法執行含有多個資料分割的測試 (可使用 --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。這兩個指令的主要差異在於，查詢在載入階段之後，且 c 查詢會在分析階段結束後執行。這些工具有助於您處理許多軟體工程工作。

查詢語言以代數運算的概念為基礎

Bazel 查詢參考資料。請參閱相關文件，取得相關範例及查詢專屬指令列選項。

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

根據預設，--[no]tool_deps 選項會讓非目標設定中的依附元件納入查詢作業的依附元件圖中。

根據預設啟用 --[no]implicit_deps 選項，會使隱含的依附元件包含在查詢作業的依附元件圖表中。隱性依附元件是指 BUILD 檔案中未明確指定，但是由 bazel 新增的依附元件。

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

  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 所回報值的指令碼 (而不是假設符號連結已存在) 將更加可靠。
  • 完整的「製作」環境。如果指定 --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 就會以漸進方式安裝該應用程式，也就是說，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 開發人員使用，因此指令的輸出內容未指定，而且可能會有變動。

根據預設，指令只會輸出說明訊息，概述可能的轉儲 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 或指令列執行)，建議您使用 --jvm_flags 引數，適用於所有 java_binary 和 java_test 程式。或者，如果是測試，請使用 bazel test --test_arg=--jvm_flags=foo ...。

--host_jvm_debug

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

--autodetect_server_javabase

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

--batch

批次模式會導致 Bazel 不使用標準用戶端/伺服器模式，而是針對單一指令執行 Bazel Java 程序。此程序已用於處理信號處理、工作控制和環境變數繼承的更可預測的語意，因此必須使用 chroot jail 執行 bazel。

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

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

--max_idle_secs=n

這個選項會指定 Bazel 伺服器程序在最後一個用戶端要求後應等待多久 (以秒為單位)，直到完成為止。預設值為 10800 (3 小時)。--max_idle_secs=0 會無限期保留 Bazel 伺服器程序。

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

--[no]shutdown_on_low_sys_mem

如果啟用且 --max_idle_secs 設為正時間長度，請在建構伺服器閒置一段時間後關閉伺服器。僅適用於 Linux。

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

--[no]block_for_lock

啟用後，Bazel 會等待其他保持伺服器鎖定的 Bazel 指令執行完畢，然後才進行進度。如果停用，Bazel 無法立即取得鎖定並繼續，就會發生錯誤。

開發人員可能會在預先提交檢查中使用這個值，避免同一個用戶端中的其他 Bazel 指令導致的長時間等待時間。

--io_nice_level=n

設定介於 0 到 7 之間的層級，以盡可能提供最佳的 IO 排程。0 代表優先順序最高， 7 則是最低預期排程器最多只能接受 4 個優先順序。 系統會忽略負值。

--batch_cpu_scheduling

針對 Bazel 使用 batch CPU 排程。這項政策適用於非互動式工作負載，但不希望降低其良好值。請參閱「man 2 sched_setscheduler」相關說明。這項政策可能有助於改善系統互動，但會影響 Bazel 處理量。

其他選項

--[no]announce_rc

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

--color (yes|no|auto)

這個選項可決定 Bazel 是否要使用顏色來醒目顯示在螢幕上的輸出內容。

如果設為 yes，則會啟用顏色輸出功能。如果將此選項設為 auto，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 會在產生每則訊息時加上時間戳記，以指定訊息的顯示時間。