指令和選項

回報問題 查看來源 夜間 7.3 7.2 7.1 7.0 6.5

本頁面說明各種 Bazel 指令都能使用的選項 例如 bazel buildbazel runbazel test本頁面是「使用 Bazel 進行建構」一文中 Bazel 指令清單的輔助內容。

目標語法

有些指令 (例如 buildtest) 可針對目標清單執行操作。它們使用的語法比標籤更具彈性,詳情請參閱「指定要建構的目標」一文。

選項

以下各節將說明建構期間可用的選項。在說明指令中使用 --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 選項,但僅適用於 exec 設定

--conlyopt=cc-option

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

這與 --copt 類似,但只適用於 C 編譯, 而非 C++ 編譯或連結這樣您就能傳遞 C 特定選項 (例如 -Wno-pointer-sign) 使用 --conlyopt

--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_modefastbuild--strip=sometimes 的預設值表示要移除。

  % 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

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

--fdo_instrument=profile-output-dir

--fdo_instrument 選項可讓您產生 FDO (根據意見回饋最佳化) 設定檔輸出結果 所建構的 C/C++ 二進位檔。對於 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,提供的引數是包含先前產生的 .gcda 檔案檔案樹狀結構的 ZIP 檔案,其中包含每個 .o 檔案的設定檔資訊。

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

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

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

--java_language_version=version

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

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

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

--tool_java_language_version=version

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

--java_runtime_version=version

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

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

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

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

--tool_java_runtime_version=version

用於執行建構期間所需工具的 JVM 版本。預設值為 remotejdk_11

--jvmopt=jvm-option

這個選項可讓選項引數傳遞至 Java VM。可用於 呼叫單一大型引數,或對個別引數多次呼叫。例如:

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

會使用伺服器 VM 啟動所有 Java 二進位檔 VM 的啟動堆積大小至 256 MB

--javacopt=javac-option

這個選項可讓選項引數傳遞至 javac。您可以將其與一個大型引數一起使用,也可以與個別引數多次使用。例如:

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

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

在 Bazel 內建的預設選項之後,該選項才會傳送至 javac javac 和個別規則選項前面。最後一個規格 任何 javac 勝出選項都會勝出。javac 的預設選項如下:

  -source 8 -target 8 -encoding UTF-8

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

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

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

建構語意

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

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

--compilation_mode 選項 (通常會縮短為 -c, 特別是 -c opt) 會使用 fastbuilddbg 的引數 或 opt,影響各種 C/C++ 程式碼產生作業 例如最佳化層級 偵錯資料表Bazel 為每個項目使用不同的輸出目錄 因此您可以在沒有特定模式的情況下切換不同模式 不必「每次」完成完整重新建構。

  • fastbuild 表示盡可能快速建構: 會產生最少的偵錯資訊 (-gmlt -Wl,-S),且不會最佳化。此為預設值。注意:系統不會設定 -DNDEBUG
  • dbg 表示建構時已啟用偵錯功能 (-g),因此您可以使用 gdb (或其他偵錯工具)。
  • opt 是指版本已啟用最佳化功能,且 停用 assert() 通話功能 (-O2 -DNDEBUG)。 在opt模式下不會產生偵錯資訊 除非您同時傳遞 --copt -g

--cpu=cpu

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

--action_env=VAR=VALUE

指定執行所有動作時可用的一組環境變數。 您可以指定變數名稱;在此情況下,值取自 叫用環境或 name=value 組合,用來設定獨立於 叫用環境。

這個 --action_env 旗標可多次指定。如果值指派給相同的 變數跨多個 --action_env 旗標,最新作業將獲勝。

--experimental_action_listener=label

experimental_action_listener 選項會指示 Bazel 使用 由 label 指定的 action_listener 規則詳情到 將 extra_actions 插入建構圖表。

--[no]experimental_extra_action_top_level_only

如果此選項設為 true, --experimental_action_listener 指令 系統只會為頂層目標排定委刊項選項。

--experimental_extra_action_filter=regex

experimental_extra_action_filter 選項會指示 Bazel 執行 篩選一組要排定extra_actions的目標。

這個標記僅適用於 --experimental_action_listener 標記。

系統預設會extra_actions在 預先排定執行目標的時程。 --experimental_extra_action_filter 會將排程限制在 extra_actions,其擁有者的標籤符合指定的規則運算式。

以下範例會將 extra_actions 的排程限制為只套用至擁有者標籤包含 '/bar/' 的動作:

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

--host_cpu=cpu

這個選項會指定應採用何種 CPU 架構名稱 來建立託管工具

--android_platforms=platform[,platform]*

要建構轉換deps的平台 android_binary 規則 (尤其是 C++ 等原生依附元件)。適用對象 舉例來說,如果 cc_library 出現在deps android_binary 規則,系統會為使用 android_binary 規則的 --android_platforms,並納入最終的 輸出內容

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

系統會為每個指定平台建立一個 .so 檔案,並封裝在 APK 中 --android_platforms.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 選項新增至指令 //foo/ 中所有 .cc 檔案的 C++ 編譯器行 (file.cc 除外)。

--dynamic_mode=mode

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

模式:

  • default:允許 bazel 選擇是否要動態連結。 詳情請參閱靜態連結 可能不準確或不適當
  • fully:動態連結所有目標。這會加快 ,並縮減產生的二進位檔大小。
  • off:連結以下項目中的所有目標: 「幾乎是靜態的」模式。 如果已在連結選擇中設定 -static,目標將變更為完全靜態。

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

啟用 Fission、 這個程式會將 C++ 偵錯資訊寫入專屬的 .dwo 檔案 (而不是 .o 檔案), 否則就會跳出去可大幅減少連結的輸入大小,並縮短連結時間。

設為 [dbg][,opt][,fastbuild] 時 (例如: --fission=dbg,fastbuild),網路已啟用 指定的編譯模式這適合用於 bazelrc 可以管理叢集設定,像是節點 資源調度、安全性和其他預先設定項目如果設為 yes,系統就會全面啟用 Fission。如果設為 no,則會全面停用 Fission。預設值為 no

--force_ignore_dash_static

如果設定此標記,則任何 -static 選項的連結選擇 系統會忽略 cc_* 規則 BUILD 檔案。這項功能僅供 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

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

--host_crosstool_top=label

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

--apple_crosstool_top=label

這個跨工具可用於編譯 C/C++ 規則的遞移性 deps objc*、ios* 和 apple* 規則。針對這些目標,此標記會覆寫 --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 會使指令在本機電腦的沙箱中執行。這需要將所有輸入檔案、資料依附性和工具列為直接 srcsdatatools 屬性的依附元件。 在支援沙箱執行作業的系統上,Bazel 預設會啟用本機沙箱機制。
  • local 會觸發指令做為本機子程序執行。
  • worker 會使指令使用永久工作站 (如有) 執行。
  • docker 會使指令在本機電腦的 Docker 沙箱中執行。必須安裝 Docker。
  • remote 會導致指令從遠端執行;這項功能僅在已個別設定遠端執行程式時可用。

--strategy mnemonic=strategy

這個選項會控制指令執行的位置和方式,並覆寫 --spawn_strategy (和 --genrule_strategy 搭配 mnemonic Genrule)如要瞭解支援的策略及其影響,請參閱 --spawn_strategy

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

這個選項會指定應使用哪種策略執行描述與特定 regex_filter 相符的指令。詳情請見 --per_file_copt regex_filter 比對。詳情請見 支援的 --spawn_strategy 策略和影響

系統會使用與說明相符的最後一個 regex_filter。這個選項會覆寫 以及指定策略的其他標記

  • 範例:--strategy_regexp=//foo.*\\.cc,-//foo/bar=local 是指使用 local 策略 (如果說明符合 //foo.*.cc 而非 //foo/bar)。
  • 範例:--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 的 輸出樹狀結構這種樹通常源自於 對應的二進位檔或測試 在測試執行期間,如要存取執行檔案,可以使用 $TEST_SRCDIR/canonical_repo_name/packagename/filename。 執行檔案樹狀結構可確保測試可存取所有檔案 只需宣告一個依附性變更者: 根據預設,執行檔案樹狀結構會藉由建構一組 的符號連結。隨著連結組合的增加,這項作業的成本也會增加,而對於某些大型版本,這可能會大幅影響整體建構時間,特別是因為每個個別測試 (或應用程式) 都需要自己的執行檔樹狀結構。

--[no]build_runfile_manifests

這個選項預設為啟用,可指定執行檔案資訊清單。 都應該寫入輸出樹狀結構 停用此設定意味著 --nobuild_runfile_links

之所以在遠端執行測試時可以停用,這是因為執行檔案樹狀結構 透過記憶體內資訊清單遠端建立。

--[no]discard_analysis_cache

啟用這個選項後,Bazel 就會捨棄分析快取 因而釋出其他記憶體 (約 10%)。執行階段。 缺點是,後續的漸進式建構速度會較慢。另請參閱省記憶體模式

--[no]keep_going (-k)

如同 GNU Make,建構的執行階段會在首次建構 時發生錯誤。有時您可以嘗試建構 即使發生錯誤,也會盡量多保留一點。這個選項可啟用 該行為經過指定後,建構作業會嘗試 建構成功的必要條件 會忽略錯誤。

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

--[no]use_ijars

這個選項會改變 java_library 指定目標的方式 而是由 Bazel 編譯而成而不是使用輸入的 java_library:適用於編譯的依附元件 java_library 目標,Bazel 會建立介面 jar 只包含非私人成員 (公開 保護和預設 (套件) 存取方法和欄位) 並使用 介面 jar 來編譯相依目標這樣一來,如果只變更類別的方法主體或私人成員,就不會重新編譯。

--[no]interface_shared_objects

這個選項會啟用「介面共用物件」,進而將二進位檔與 其他共用程式庫仍取決於共用物件的介面。 而非實作本身當 Bazel 只會變更實作項目 可避免重新建立依賴於已變更的共用資料庫 無謂。

輸出選項

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

--[no]build

這個選項會啟動建構的執行階段。是 預設為啟用。關閉後,系統會略過執行階段,只執行前兩個階段:載入和分析。

這個選項可用於驗證 BUILD 檔案,並偵測輸入內容中的錯誤,而無須實際建構任何內容。

--[no]build_tests_only

如果指定了這個選項,Bazel 只會建構執行 *_testtest_suite 規則所需的必要項目,這些規則不會因大小逾時標記語言而遭到篩除。如果指定,Bazel 就會忽略命令列中指定的其他目標。根據預設,這個選項會停用,Bazel 會建構所有要求的項目,包括從測試中篩除的 *_testtest_suite 規則。這很實用 「bazel test --build_tests_only foo/...」可能無法偵測到所有版本 foo 樹狀結構發生故障情形。

--[no]check_up_to_date

這個選項會導致 Bazel 不會執行建構作業,而只會檢查所有指定目標是否為最新版本。如果是的話 成功完成。不過,如果任何檔案過時,系統會回報錯誤,並導致建構作業失敗,而非建構檔案。這個選項可能有助於判斷是否已執行建構作業,且比來源編輯作業更近期 (例如提交前檢查),而不會產生建構作業費用。

另請參閱 --check_tests_up_to_date

--[no]compile_one_dependency

編譯引數檔案的單一依附元件。這對於使用者 透過 IDE 檢查來源檔案的語法,例如重新建構單一 並依來源檔案及早偵測錯誤 可在編輯/建構/測試週期內達成這個引數會影響 非旗標引數會解譯:每個引數都必須是 或是與目前作業相關的純文字檔案名稱 目錄,建立了一個根據每個來源檔案名稱的規則。適用對象 C++ 和 Java 我們會優先選擇位於相同語言空間的規則。適用對象 如果有多項規則擁有相同偏好設定,那麼優先度最高的規則 選取 BUILD 檔案。明確命名的目標模式,不會 參照來源檔案會導致錯誤。

--save_temps

--save_temps 選項會儲存編譯器的暫時輸出內容。包括 .s 檔案 (組合器程式碼)、.i (預先處理的 C) 和 .ii (預先處理的 C++) 檔案。這些輸出內容通常對偵錯很有幫助。只有溫度 為指令列指定的一組目標產生產生的代碼。

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

為確保 Bazel 會列印其他輸出檔案的位置,請確認 --show_result n 設定值是否足夠高。

--build_tag_filters=tag[,tag]*

如有指定,Bazel 只會建構至少含有一個必要標記的目標 (如有指定) 且沒有任何排除的標記。建構標記篩選器會以半形逗號分隔的標記關鍵字清單指定,並可選擇在前方加上「-」符號,用於表示排除的標記。必要標記也可以 開頭有「+」] 號。

執行測試時,Bazel 會忽略測試目標的 --build_tag_filters。 即使不符合這個篩選條件 系統也會建構並執行如要避免建構這些項目,請使用 --test_tag_filters 篩選測試目標,或明確排除這些項目。

--test_size_filters=size[,size]*

如有指定,Bazel 會測試 (或執行於 --build_tests_only 時建構) ) 只會測試具有指定大小的測試目標。測試尺寸篩選器 是以逗號分隔的清單,列出允許的測試大小值 (小、 中、大或龐大),在開頭加上「-」這個符號代表 排除的測試大小。例如:

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

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

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

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

--test_timeout_filters=timeout[,timeout]*

如果指定,Bazel 只會測試 (或建構,如果也指定 --build_tests_only) 具有指定逾時時間的測試目標。測試逾時篩選器 是以逗號分隔的清單,列出允許的測試逾時值 (短 中度、長版或永恆性)) 開頭,可視需要在前方加上「-」這個符號代表 排除的測試逾時。請參閱 --test_size_filters 例如語法範例

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

--test_tag_filters=tag[,tag]*

如有指定,Bazel 會測試 (或執行於 --build_tests_only 時建構) 時) 只會包含至少一個必要代碼的測試目標 (如有指定) 且沒有任何排除的標記。測試代碼 篩選器是以以逗號分隔的標記關鍵字清單指定, 前面加上「-」符號,用來表示排除的標記。必要標記也可以 開頭有「+」] 號。

例如:

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

將會測試標記為 performancestress 標記,但「沒有」使用 flaky 標記。

根據預設,系統不會套用測試標記篩選器。請注意,您也可以篩選 測試的 sizelocal 標記 。

--test_lang_filters=string[,string]*

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

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

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

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

將測試 //baz/... 中的所有目標,除了 foo_testbar_test 例項。

--test_filter=filter-expression

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

filter-expression 的具體解讀方式,取決於負責執行測試的測試架構。可以是 glob、子字串或正規表示式。--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 檔案。

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

可能需要傳遞 --subcommands=pretty_print才能列印 將指令的引數視為清單,而非單行。這可能會 可讓較長的指令列更易於閱讀

另請參閱下方的 --verbose_failures

如需以適用於工具的格式記錄檔案子指令,請參閱 --execution_log_json_file--execution_log_binary_file.

--verbose_failures

這個選項會讓 Bazel 的執行階段針對失敗的指令,顯示完整的指令列。這對於偵錯 以及失敗的建構作業

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

工作區狀態

使用這些選項來「附加」Bazel 建構的二進位檔:將其他資訊嵌入 例如原始碼控管修訂版本或其他工作區相關資訊。別擔心!您可以使用 此機制設有支援 stamp 屬性的規則,例如 genrulecc_binary,以及執行其他操作。

--workspace_status_command=program

您可以使用這個旗標指定 Bazel 在每次建構前執行的二進位檔。這項計畫可以檢舉 工作區狀態的相關資訊,例如目前的原始碼控管修訂版本。

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

程式應將零或多個鍵/值組合列印為標準輸出,每行一個項目, 然後以 0 結束 (否則建構失敗)。鍵名可以是任何名稱,但 請使用大寫字母和底線。鍵名稱後方的第一個空格與 值。值為該行剩餘的部分 (包括其他空格)。無論金鑰或 值可能會橫跨好幾行。金鑰不得重複。

Bazel 會將鍵分割成兩個值區:「穩定」和「易變」。(名稱包括「stable」和 「揮發性」有點違反直覺,所以請不要太仔細思考)。

接著,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 規則的預設值) 時,這個選項會決定是否啟用沖壓功能。

Bazel 絕對不會處理針對執行設定建構的二進位檔。 無論這個選項或 stamp 屬性為何。對於設定 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-binbazel-testlogsbazel-genfiles

如果因任何原因無法建立符號連結,系統會發出警告,但仍視為建構成功。我們要用 這可讓您在唯讀目錄中建立容器 寫入權限在建構結束時,資訊訊息中列印的任何路徑,如果連結符號指向預期位置,就只會使用連結符號相對的簡短形式;換句話說,即使您無法依賴已建立的連結符號,仍可信賴這些路徑的正確性。

這個選項的部分常見值:

  • 抑制符號連結建立:--symlink_prefix=/ 會導致 Bazel 不會建立或更新任何符號連結,包括 bazel-outbazel-<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 指令 svgweblist

使用 Bazel 進行發布

在開發期間,軟體工程師都會使用 Bazel 以及由發布工程師準備用於部署的二進位檔 Google 提供端對端開發平台 可將實驗階段的機器學習模型轉換至正式版環境本節提供發布提示清單 可協助工程師使用 Bazel

重要選項

使用 Bazel 進行發布建構作業時,也會出現與其他指令碼相同的問題 執行建構作業詳情請參閱「從指令碼呼叫 Bazel」。特別建議您採用下列選項:

以下選項也很重要:

  • --package_path
  • --symlink_prefix: 針對多項設定管理建構作業 方便您區分每個版本 搭配專屬 ID,例如「64bit」對比「32 位元」。這個選項可區分 bazel-bin (等) 符號連結。

執行測試

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

根據預設,這個指令會同時執行建構和測試 活動,建立所有指定的目標 (包括任何非測試 並測試 立即*_testtest_suite目標 因此測試執行 與建築物交錯顯示這麼做通常會產生 也有助於我們瞭解

bazel test」的選項

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

如果這個選項設為「auto」(預設),而 Bazel 只會在 符合下列條件者:

  • Bazel 偵測測試或其依附元件的變更
  • 測試會標示為 external
  • 透過 --runs_per_test 要求多次測試執行作業
  • 測試失敗

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

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

如果使用者在 .bazelrc 檔案中預設啟用這個選項,可以使用 -t (開啟) 或 -t- (關閉) 的縮寫,方便在特定執行作業時覆寫預設值。

--check_tests_up_to_date

這個選項會指示 Bazel 不要執行測試,而只是檢查及回報 以及快取測試結果如果有任何測試未先建構及執行,或測試結果過時 (例如,因為原始程式碼或建構選項已變更),Bazel 就會回報錯誤訊息 (「測試結果未更新」),並將測試狀態記錄為「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, 同步測試中的測試結果不會彼此交錯。 根據上方的摘要輸出內容,顯示建構作業的摘要。
  • allerrors 類似,但會為所有測試 (包括通過的測試) 輸出結果。
  • streamed 會串流每項測試的 stdout/stderr 輸出內容,位於 即時。

--java_debug

這個選項會使 Java 測試的 Java 虛擬機器等待來自 開始測試之前,先執行符合 JDWP 規定的偵錯工具。這個選項會暗示 --test_output=streamed

--[no]verbose_test_summary

根據預設,這個選項會啟用,導致測試時間和其他額外資訊 (例如測試次數) 會列印到測試摘要中。如果指定 --noverbose_test_summary,測試摘要只會包含測試名稱、測試狀態和快取測試指標,並盡可能以 80 個字元內的格式顯示。

--test_tmpdir=path

指定本機執行測試的暫存目錄。每項測試 在此目錄中的個別子目錄中執行。系統會在執行每個 bazel test 指令時清除目錄。根據預設,bazel 會將這個目錄放在 Bazel 輸出基礎目錄下方。

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

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

或者,您也可以提供四個以半形逗號分隔的值,指定 個別的逾時時間、中度、長效測試和永恆等測試 順序)。 無論是哪一種表單,任何測試大小的零或負值都會替換為指定逾時類別的預設逾時時間,這項設定由「編寫測試」頁面定義。根據預設,Bazel 預設會在所有測試中使用這些逾時 根據測試的大小推斷出逾時上限;無論 默示或明確設定

如果測試明確指出逾時類別與大小不同,則會收到與 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'

測試選項

如「輸出選項選項」底下所述。 您可以依「大小」篩選測試 timeout標記,或 語言。便利性 一般名稱篩選器 為測試執行器篩選引數

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 建立的二進位檔及其行為,則視應用程式是否 叫用即可使用的二進位檔

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

二進位檔進行測試時,目前的工作目錄是 exec 根目錄 本信善意是為了複製環境測試 執行然而,模擬並非完美無缺,而且測試具有多個 無法以這種方式執行 ( 可使用「--test_sharding_strategy=disabled」指令列選項 解決這個問題)

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

  • BUILD_WORKSPACE_DIRECTORY:執行建構作業的工作區根目錄。
  • BUILD_WORKING_DIRECTORY:目前的工作目錄,其中 Bazel 的執行位置為

這些字串可用於 例如,在指令列中的 使用起來更方便

bazel run」的選項

--run_under=command-prefix

這與 --run_under 選項 bazel test (請參閱上方)、 但僅適用於 bazel run 執行的指令,而非 bazel test 執行的測試 而且無法在標籤下執行

從 Bazel 篩選記錄輸出

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

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

執行測試

bazel run 也可執行測試二進位檔,這類二進位檔 執行測試,相當接近 撰寫測試。請注意, 以這種方式執行測試時,--test_* 引數會生效,但 --test_arg

清理建構輸出內容

clean 指令

Bazel 使用 clean 指令,類似於 Make。 系統會刪除所有已執行建構設定的輸出目錄 或由此 Bazel 執行個體建立的整個工作樹狀結構 執行 Bazel 執行個體,並重設內部快取。如果執行時未包含 指令列選項,然後是所有設定的輸出目錄 進行清理作業

提醒您,每個 Bazel 執行個體都與單一工作區相關聯,因此 clean 指令會刪除您已完成的所有版本中的所有輸出內容 該 Bazel 執行個體與該 Bazel 執行個體搭配使用

完全移除 Bazel 建立的整個工作樹狀結構 例如,您可以指定 --expunge 選項時間 使用 --expunge 執行,清理指令 移除除了建構作業以外的整個輸出基礎樹狀結構 輸出會包含 Bazel 建立的所有暫存檔案。此外, 清理完成後,會停止 Bazel 伺服器,這等同於 shutdown 指令。舉例來說 清除 Bazel 執行個體的所有磁碟和記憶體追蹤記錄 請詳細說明:

  % bazel clean --expunge

或者,您可以使用 --expunge_async。在非同步清除程序持續執行的情況下,在相同用戶端中叫用 Bazel 指令是安全的。

clean 指令主要用於釋出不再需要的工作區磁碟空間。Bazel 的漸進式重新建構作業可能不會 完美無缺,因此 clean 可用於恢復一致的 狀態。

Bazel 的設計可讓這些問題獲得修正,且這些錯誤是優先修正的項目。如果您發現不正確的增量版本,請提交錯誤報告,並在工具中回報錯誤,而非使用 clean

查詢依附元件圖表

Bazel 包含查詢語言,可用於詢問建構期間使用的相依關係圖。系統會使用查詢語言 這兩個指令:query 和 cquery。這兩個指令的主要差異在於查詢會在載入階段後執行,而 cquery 會在分析階段後執行。這些工具對於許多軟體工程工作而言,都是不可或缺的輔助工具。

查詢語言的基礎概念是圖表的代數運算,相關資訊詳見

Bazel 查詢參考資料。 請參閱該文件,瞭解相關範例和查詢專屬的指令列選項。

查詢工具接受多個指令列 如果有需要 SQL 指令的分析工作負載 則 BigQuery 可能是最佳選擇--output 會選取輸出格式。 --[no]keep_going (預設為停用) 會讓查詢工具在發生錯誤時繼續進行;如果發生錯誤時無法接受不完整的結果,則可能會停用這項行為。

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

預設啟用的 --[no]implicit_deps 選項會在查詢運作的依附元件圖表中納入隱含依附元件。一個 隱含依附元件是指 BUILD 檔案中未明確指定的依附元件 而是 bazel 加上的

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

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

查詢動作圖表

aquery 指令可讓您查詢建構圖中的動作。它會針對已設定後分析的目標圖表運作,並提供有關動作、構件及其關係的資訊。

這項工具接受多個指令列選項。--output 會選取輸出格式。預設輸出格式 (text) 是人類可讀的格式,prototextproto 適用於 機器可讀取的格式 值得注意的是,aquery 指令會在一般 Bazel 建構作業上執行,並繼承建構期間可用的選項組合。

它支援傳統 query 可用的函式,但 siblingsbuildfilestests 則不支援。

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

其他指令和選項

help

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

--[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:指令記錄檔的絕對路徑。 這包含最新資料的交錯式 stdout 和 stderr 串流 Bazel 指令請注意,執行 bazel info 會覆寫這個檔案的內容,因為這會成為最新的 Bazel 指令。不過,除非您變更 --output_base--output_user_root 選項的設定,否則指令記錄檔的位置不會變更。

  • used-heap-sizecommitted-heap-sizemax-heap-size:回報各種 JVM 堆積大小參數。分別為:目前使用的記憶體、目前保證可從系統提供給 JVM 的記憶體,以及可分配的最大記憶體。

  • gc-countgc-time:自此 Bazel 伺服器啟動以來,垃圾收集的累積次數,以及執行垃圾收集所花費的時間。請注意,這些值不會在每次啟動時重設 建構應用程式

  • package_path:以冒號分隔的路徑清單,符合 已透過 bazel 搜尋包裹。格式與 --package_path 建構指令列引數。

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

% bazel info server_pid
1285

設定專屬資料

這些資料可能會受到傳遞的設定選項影響 給bazel info,為期 例如 --cpu--compilation_mode 依此類推。info 指令接受所有指令 控管依附元件的選項 因為這些部分會決定 建構作業的輸出目錄、編譯器選項等

  • bazel-binbazel-testlogsbazel-genfiles:回報 由開發人員手動為程式產生的 bazel-* 目錄 每個版本都有所在位置儘管如此 基本工作區目錄中建立的 bazel-* 符號連結, 成功建構應用程式不過,如果工作區目錄為唯讀,就無法建立 bazel-* 符號連結。使用 bazel info 回報的值,而非假設存在符號連結的腳本,會更為穩健。
  • 完整的「Make」環境。如果指定 --show_make_env 標記,系統也會顯示目前設定「Make」環境中的所有變數 (例如 CCGLIBC_VERSION 等)。以下是使用 $(CC) 存取的變數 或 BUILD 檔案中的 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 以上版本的裝置。請注意, --incremental 標記 而不需要使用 --split_apks

--start_app

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

--debug_app

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

--start=_start_type_

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

  • NO 未啟動應用程式。此為預設值。
  • COLD 在安裝後從清除狀態啟動應用程式。
  • WARM 針對增量安裝作業保留及還原應用程式狀態。
  • DEBUG 在安裝完成後,等待偵錯工具,再以乾淨狀態啟動應用程式。

--adb=path

指出要使用的 adb 二進位檔。

預設情況下,會使用 --android_sdk 指定的 Android SDK 中的 ADB。

--adb_arg=serial

adb 的額外引數。這些位於變數中的子指令前方 通常用於指定要安裝至哪個裝置。 舉例來說,如要選取要使用的 Android 裝置或模擬器:

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

adb 叫用為

adb -s deadbeef install ...

--incremental_install_verbosity=number

增量安裝的詳細程度。將值設為 1,即可將偵錯記錄列印到主控台。

dump

dump 指令會輸出 Bazel 伺服器的內部狀態。這個指令主要供 Bazel 開發人員使用,因此不會指定這個指令的輸出內容,且可能隨時變更。

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

支援下列選項:

  • --action_cache 會傾印動作快取內容。
  • --packages 傾印套件快取內容。
  • --skyframe 會傾印內部 Bazel 依附元件圖表的狀態。
  • --rules 會為每個規則和切面類別傾印規則摘要, 包括計數和操作次數包括原生和 Starlark 規則。如果已啟用記憶體追蹤以及記憶體用量
  • --skylark_memory 轉儲 a 將 .gz 檔案與 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 --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 指令會分析 先前的 JSON 追蹤記錄設定檔 從 Bazel 叫用期間收集而來。

canonicalize-flags

canonicalize-flags 指令,取得 Bazel 指令的選項清單,並傳回 也可以產生 相同效果 的選項新的選項清單是標準清單。例如: 具有相同效果的兩個選項清單,會標準化為相同的新清單。

--for_command 選項可用來選擇 指令目前,只有 buildtest 如下 支援。指定指令不支援的選項會導致錯誤。

例如:

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

啟動選項

本節所述的選項會影響 Bazel 伺服器程序所使用的 Java 虛擬機器啟動作業,並套用至該伺服器處理的所有後續指令。如果已有 且啟動選項不相符

您必須使用 --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 虛擬機器的啟動選項 或任何可執行 Knative 的環境中這可用來設定堆疊大小,例如:

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

這個選項可搭配個別引數使用多次。請注意,您很少需要設定這個旗標。您也可以傳遞以空格分隔的字串清單。 每個函式都會解讀為獨立的 JVM 引數,不過這項功能很快就會 已淘汰。

這「不會」影響 Google Cloud 使用的 JVM 應用程式、測試、工具等如要將 JVM 選項傳遞至可執行的 Java 程式,無論是透過 bazel run 或指令列執行,您都應使用所有 java_binaryjava_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 不使用 標準用戶端/伺服器模式,但會改為執行 Terraform 適用於單一指令的 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 指令而造成長時間等待。

--io_nice_level=n

設定最佳努力 I/O 排程的等級 (0 到 7)。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 環境變數設為 dumbemacsxterm-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 產生的每則訊息中加入時間戳記,指定訊息顯示的時間。