命令和选项

本页面介绍了各种 Bazel 命令(例如 bazel buildbazel runbazel test)可用的选项。本页面是使用 Bazel 构建中的 Bazel 命令列表的配套页面。

目标语法

某些命令(如 buildtest)可对目标列表执行操作。它们使用的语法比标签更灵活,指定构建目标中介绍了这些标签。

选项

下面几部分介绍了构建过程中可用的选项。在帮助命令中使用 --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 工作区执行构建{101 。

示例:从空客户端构建

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

通过使用 -Wl,--strip-debug 选项调用链接器,此选项可确定 Bazel 是否将从所有二进制文件和共享库中删除调试信息。--strip=always 表示始终移除调试信息。--strip=never 表示永不移除调试信息。如果 --compilation_modefastbuild,则默认值 --strip=sometimes 表示剥离。

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

将编译目标,同时从所有生成的二进制文件中删除调试信息。

Bazel 的 --strip 选项与 ld 的 --strip-debug 选项相对应:它只去除调试信息。如果您出于某种原因想要去除所有符号,而不仅仅是 debug 符号,则需要使用 ld 的 --strip-all 选项。可以通过将 --linkopt=-Wl,--strip-all 传递给 Bazel 来实现这一点。另请注意,设置 Bazel 的 --strip 标志会替换 --linkopt=-Wl,--strip-all,因此只应设置其中一个。

如果您只想构建单个二进制文件并希望去除所有符号,还可以传递 --stripopt=--strip-all 并明确构建目标的 //foo:bar.stripped 版本。如 --stripopt 部分所述,此操作会在链接最终二进制文件后应用剥离操作,而不是在所有 build 的链接操作中添加剥离操作。

--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,提供的参数是包含之前生成的 .gcda 文件的文件树的 zip 文件,该文件包含每个 .o 文件的个人资料信息。

或者,所提供的参数可以指向由扩展程序 .afdo 标识的自动配置文件。

对于 LLVM 编译器,提供的参数应指向由 llvm-prodata 工具准备的已编入索引 LLVM 配置文件输出文件,并且应使用 .prodata 扩展名。

选项 --fdo_instrument--fdo_optimize 不能同时使用。

--[no]output_symbol_counts

如果启用了此标记,C++ 可执行二进制文件的每个被黄金调用的链接都会输出一个 symcount 文件(通过 --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。 可能的值包括 localjdklocaljdk_versionremotejdk_11remote_jdk17。您可以使用 local_java_repositoryremote_java_repostory 代码库规则注册自定义 JVM 来扩展这些值。

--tool_java_runtime_version=version

用于执行构建期间所需的工具的 JVM 版本。默认值为 remotejdk_11

--jvmopt=jvm-option

此选项允许将选项参数传递给 Java 虚拟机。它可以与一个大参数一起使用,也可以与单个参数一起使用。例如:

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

使用服务器虚拟机来启动所有 Java 二进制文件,并将虚拟机的启动堆大小设置为 256 MB。

--javacopt=javac-option

此选项允许将选项参数传递给 javac。它可以与一个大参数一起使用,也可以与单个参数一起使用。例如:

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

将使用 javac 默认调试信息(而不是 Bazel 默认值)重新构建 java_binary。

系统会在 Bazel 内置 javac 默认选项之后和每条规则选项之前将该选项传递给 javac。任何 javac 选项的最后规范都是有效的。javac 的默认选项为:

  -source 8 -target 8 -encoding UTF-8
-extra_checks[:(off|on)]

此 javac 选项可实现额外的正确性检查。发现的任何问题都将显示为错误。-extra_checks-extra_checks:on 均可用于强制启用检查。-extra_checks:off 会完全停用分析。如果未指定此选项,则使用默认行为。

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

此选项可控制 javac 是否检查缺少直接依赖项。 Java 目标必须明确将所有直接使用的目标声明为依赖项。此标志会指示 javac 确定用于对各个 java 文件进行类型检查的 jar,如果它们并非当前目标的直接依赖项的输出,则发出警告/错误。

  • off 表示已停用检查。
  • warn 表示 javac 将为每个缺失的直接依赖项生成 [strict] 类型的标准 Java 警告。
  • defaultstricterror 表示所有 javac 都会生成错误而不是警告;如果发现缺少任何直接依赖项,就无法构建当前目标。如果未指定该标志,这也是默认行为。

构建语义

这些选项会影响构建命令和/或输出文件内容。

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

--compilation_mode 选项(通常简写为 -c,具体来讲是 -c opt)接受 fastbuilddbgopt 参数,并影响各种 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添加到 build 图中。

--[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 规则的传递 depscc_binary 规则中,则至少构建 cc_library 两次:一次,针对 android_binary 规则使用 --fat_apk_cpu 指定的 CPU 一次;针对 cc_binary 规则通过 --cpu 指定的 CPU 一次。

默认为 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++ 文件的基本名称(包括扩展名)。此外,它还包含任何依赖于平台的前缀。

为了匹配生成的文件(例如通用规则输出),Bazel 只能使用执行路径。在这种情况下,正则表达式不应以“//”开头,因为不匹配任何执行路径。可以使用如下软件包名称:--per_file_copt=base/.*\.pb\.cc@-g0。这将匹配 base 目录下的所有 .pb.cc 文件。

此选项可以多次使用。

无论使用何种编译模式,系统都会应用该选项。例如,您可以使用 --compilation_mode=opt 进行编译,并选择性地编译启用更强优化或停用优化的部分文件。

注意:如果某些文件是使用调试符号选择性地编译的,链接时可能会删除符号。这可以通过设置 --strip=never 来阻止。

语法[+-]regex[,[+-]regex]...@option[,option]...,其中 regex 表示正则表达式,您可为其添加 + 前缀以识别包含模式,并以 - 作为前缀识别排除模式。option 表示传递给 C++ 编译器的任意选项。选项包含 , 时,必须用引号括住它,例如 \,。选项还可以包含 @,因为只有第一个 @ 用于分隔正则表达式与选项。

示例--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs-O0以及-fprofile-arcs这些选项适用于所有人的 C++ 编译器的命令行.cc文件中包含//foo/file.cc中披露政府所要求信息的数量和类型。

--dynamic_mode=mode

确定是否会与编译规则中的 linkstatic 属性交互,以动态方式链接 C++ 二进制文件。

模式:

  • auto:转换为特定于平台的模式;对于 Linux,default ;对于 cygwin,转换为 off
  • default:允许 Bazel 选择是否要动态链接。如需了解详情,请参阅 linkstatic
  • fully:动态关联所有定位条件。这将加快链接时间,并减小生成的二进制文件的大小。
  • off:以大部分为静态模式链接所有目标。如果在 linkopts 中设置了 -static,目标将更改为完全静态。

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

启用 Fission,此进程会将 C++ 调试信息写入专用的 .dwo 文件(而非 .o 文件),否则会将前者写入该文件。这将大大减小链接的输入大小,并缩短链接时间。

设置为 [dbg][,opt][,fastbuild](例如:--fission=dbg,fastbuild)时,仅会为一组指定的编译模式启用 Fission。这对于 Bazelrc 设置很有用。设置为 yes 时,Fission 普遍处于启用状态。设置为 no 时,Fission 会被广泛停用。默认值为 no

--force_ignore_dash_static

如果设置了此标志,则系统将忽略 cc_* 规则 BUILD 文件中的任何 -static 选项。这仅适用于解决 C++ 安全强化 build 的问题。

--[no]force_pic

启用后,所有 C++ 编译都会生成与位置无关的代码(“-fPIC”),而链接则会首选 PIC 预构建库,而非非 PIC 库;而链接也会生成位置无关可执行文件(“-pie”)中披露政府所要求信息的数量和类型。默认设置为停用。

--android_resource_shrinking

选择是否对 android_binary 规则执行资源缩减。为 android_binary 规则的 reduce_resources attribute 设置默认值;有关详情,请参阅该规则的文档。默认为关闭。

--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++ 规则的 Crosstool。如果构建中的其他目标需要不同的交叉工具,此方法非常有用。默认设置是在 WORKSPACE 文件中使用由 android_ndk_repository 规则生成的 crosstool。另请参阅 --fat_apk_cpu

--compiler=version

此选项可指定在构建过程中用于编译二进制文件的 C/C++ 编译器版本(例如 gcc-4.1.0)。如果要使用自定义交叉工具进行构建,则应使用 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 运行Bazel 测试以及由 java_binaryjava_test 规则。JAVABASEJAVA "Make" 变量衍生自此选项。

--host_javabase=label

此选项可设置要在主机配置中使用的基本 Java 安装的 label,例如 Java Builder 和 Singlejar 等主机构建工具。

它不会选择用于编译 Java 源文件的 Java 编译器。您可以通过设置 --java_toolchain 选项来选择编译器。

执行策略

这些选项会影响 Bazel 执行构建的方式。它们应该不会对构建生成的输出文件产生任何重大影响。它们的主要影响通常是构建速度。

--spawn_strategy=strategy

此选项控制命令的执行方式和方式。

  • standalone 使命令作为本地子进程执行。此值已被弃用。请改用“local”。
  • sandboxed 使命令在本地机器上的沙盒内执行。这要求在 srcsdatatools 属性中将所有输入文件、数据依赖项和工具列为直接依赖项。默认情况下,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 策略运行“Compile //foo/bar/baz”,但逆转顺序会使用 local 运行它。
  • 示例:--strategy_regexp='Compiling.*/bar=local,sandboxed' 使用 local 策略运行 "fooiling //foo/bar/baz",如果失败,则回退到 sandboxed

--genrule_strategy=strategy

这是 --strategy=Genrule=strategy 的已弃用简写形式。

--jobs=n(-j)

此选项采用整数参数,用于指定在构建作业执行期间可以并发执行的作业数量的上限。

--progress_report_interval=n

Bazel 会定期输出尚未完成的作业(例如长时间运行的测试)的进度报告。此选项可设置报告频率,每 n 秒输出一次进度。

默认值为 0,这意味着增量算法:第 10 份报告将在 10 秒钟后输出,之后 30 秒钟后,报告每分钟的进度一次。

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

通过这些选项,Bazel 可以在安排构建和测试活动在本地运行时考虑的本地资源(MB 和 MB 逻辑 CPU 数量)。接受整数,或者采用关键字(HOST_RAM 或 HOST_CPUS),后面可视需要添加整数[-|*浮点数] (例如,--local_cpu_resources=2--local_ram_resources=HOST_RAM*.5--local_cpu_resources=HOST_CPUS-1 )。这些标志是独立的;可以设置其中之一,也可以同时设置两者。默认情况下,Bazel 会直接从本地系统的配置估算 RAM 和 CPU 核心数。

此选项默认处于启用状态,用于指定是否应在输出目录中构建测试和二进制文件的 runfiles 符号链接。 使用 --nobuild_runfile_links 可以验证所有目标是否都能编译,而不会产生构建 runfiles 树的开销。

执行测试(或应用)时,其运行时数据依赖项会汇集到一处。在 Bazel 的输出树中,此“runfiles”树通常会被作为相应二进制文件或测试的同级根获得。在测试执行期间,您可以使用 $TEST_SRCDIR/workspace/packagename/filename 形式的路径访问 runfile。 runfiles 树确保测试可以访问其声明了依赖项的所有文件。默认情况下,runfiles 树通过构建一组指向所需文件的符号链接来实现。随着链接集的增加,此操作的成本也随之增加,并且对于一些大型构建而言,它会显著增加总构建时间,特别是因为每个单独的测试(或应用)都有自己的 runfiles 树。

--[no]build_runfile_manifests

此选项默认处于启用状态,用于指定是否应将 runfiles 清单写入输出树。停用此功能意味着 --nobuild_runfile_links

您可以在远程执行测试时将其停用,因为系统将通过内存中的清单远程创建 runfiles 树。

--[no]discard_analysis_cache

启用此选项后,Bazel 会在执行开始前舍弃分析缓存,从而在执行阶段释放更多内存(约 10%)。但缺点是,增量增量构建的速度会减慢。另请参阅内存节省模式

--[no]keep_going(-k)

与 GNU Make 一样,构建的执行阶段会在遇到第一个错误时停止。有时,即使出现错误,尝试尽可能多地构建也很有用。此选项可实现该行为;如果指定了该选项,构建将尝试构建成功构建前提条件的所有目标,但会忽略错误。

虽然此选项通常与构建的执行阶段相关联,但它也会影响分析阶段:如果在构建命令中指定了多个目标,但其中只有部分目标可以成功分析,请执行以下操作:除非指定了 --keep_going,否则构建将停止,并显示错误,在这种情况下,构建将继续执行,但仅针对成功分析的目标。

--[no]use_ijars

此选项会更改 Bazel 编译 java_library 目标的方式。您无需使用java_library编译依赖项 java_library目标,Bazel 将创建仅包含非隐私成员(公开、受保护和默认(软件包)访问方法和字段)的接口 jar,并使用接口 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 不执行构建,而只是检查所有指定的目标是否为最新。如果存在,构建会成功完成。但是,如果任何文件已过期(而不是构建),则系统会报告错误,并且构建会失败。此选项可用于确定某个 build 是否比源修改(例如,用于提交前检查)刚好被执行过,并且不产生 build 费用。

另请参阅 --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 将仅构建至少有一个必需标记(如果已指定任何标记)且不包含任何被排除标记的目标。Build 代码过滤器可指定为以英文逗号分隔的标记关键字列表,选择性地加上“-”符号,用于表示已排除的标记。必需标记也可能前面带有“+”号。

运行测试时,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_filter

默认情况下,系统不会应用测试超时过滤。

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

针对包含官方 *_test 规则的语言,指定以英文逗号分隔的测试语言列表(如需查看这些规则的完整列表,请参阅 build encyclopedia)。可以选择性地在每个语言前面加上“-”以指定已排除的语言。每种语言使用的名称应与 *_test 规则中的语言前缀相同,例如 ccjavash

如果已指定,Bazel 将仅测试指定语言的目标,或者构建(如果还指定了 --build_tests_only)。

例如,

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

只会测试 foo/... 中的 C/C++ 和 Java 测试(分别使用 cc_testjava_test 规则定义),

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

将运行 foo/... 中的所有测试,sh_testjava_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 命令分析或解析数据。build 配置文件对于了解 Bazel 的 build 命令所花的时间非常有用。

--[no]show_loading_progress

此选项会使 Bazel 输出软件包加载进度消息。如果停用此设置,系统将不会显示消息。

--[no]show_progress

此选项可显示进度消息;它默认处于开启状态。停用后,系统不会显示进度消息。

--show_progress_rate_limit=n

此选项会导致 Bazel 每 n 秒仅显示一条进度消息,其中 n 是实数。如果 n 为 -1,则会显示所有进度消息。此选项的默认值为 0.02,表示 Bazel 将每 0.02 秒将进度消息限制为一条。

--show_result=n

此选项用于控制在 bazel build 命令结束时输出结果信息的方式。默认情况下,如果指定了单个构建目标,Bazel 将输出一条消息,说明目标是否已成功更新,如果成功,则输出文件的列表目标已创建。如果指定了多个目标,系统不会显示结果信息。

虽然结果信息可能对单个目标或少数目标的构建很有用,但对于大型 build(如整个顶级项目树),这些信息可能会变得让人应接不 and,分散注意力。 通过此选项可以对其进行控制。--show_result 接受一个整数参数,该参数是应输出完整结果信息的目标数上限。默认值为 1。超过此阈值时,系统不会显示各个目标的结果信息。因此,零会导致结果信息总是被抑制,而如果值非常大,则始终会输出结果。

如果用户经常在构建少量目标(例如,在编译-修改-测试周期内)和大量目标之间交替,他们可能会希望在两者之间选择一个值例如,在创建新的工作区或运行回归测试时)。在前一种情况下,结果信息非常有用,而在后一种情况下,它的信息会不太实用。与所有选项一样,这可以通过 .bazelrc 文件隐式指定。

系统会输出文件,以便轻松地将文件名复制并粘贴到 shell 以运行构建的可执行文件。推动目标构建的脚本可以轻松解析每个目标的“最新”或“失败”消息。

--sandbox_debug

使用此选项时,Bazel 会在使用沙盒执行操作时输出额外的调试信息。此选项还会保留沙盒目录,以便检查在执行期间对操作可见的文件。

--subcommands-s

此选项会使 Bazel 的执行阶段在执行每个命令之前输出完整的命令行。

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

尽可能以与 Bourne shell 兼容的语法输出命令,以便轻松将其复制并粘贴到 shell 命令提示符中。(附带的英文圆括号旨在保护您的 shell 免受 cdexec 调用;请务必复制它们!) 不过,某些命令在 Bazel 内部实现,例如创建符号链接树。对于这些对象,没有可显示的命令行。

可以传递 --subcommands=pretty_print,以将命令的参数输出为列表(而不是单行)。这样有助于提高长命令行的可读性。

另请参阅下文的 --verbose_failures

如需将子命令记录到工具格式的文件,请参阅 -- execution_log_json_file-- execution_log_binary_file

--verbose_failures

此选项会使 Bazel 的执行阶段针对失败的命令输出完整的命令行。这对于调试失败的构建至关重要。

失败的命令以与 Bourne shell 兼容的语法输出,适用于复制和粘贴到 shell 提示符。

工作区状态

使用这些选项可“标记”Bazel 构建的二进制文件:将其他信息(例如源代码控制修订版本或其他与工作区相关的信息)嵌入二进制文件。您可以将此机制与支持 stamp 特性的规则(例如 genrulecc_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 包含其余键及其对应的值

该合约是:

  • 如果可能的话,“stable”键的值很少发生变化。如果 bazel-out/stable-status.txt 的内容发生更改,Bazel 将使依赖于这些操作的操作失效。换言之,如果稳定键的值发生变化,Bazel 将重新运行盖章的操作。 因此,稳定状态不应包含时间戳之类的内容,因为时间戳始终都会更改,并且会使 Bazel 在每次构建时重新运行时间戳操作。

    Bazel 始终会输出以下稳定的键:

    • BUILD_EMBED_LABEL--embed_label 的值
    • BUILD_HOST:运行 Bazel 的主机的名称
    • BUILD_USER:运行 Bazel 的用户的名称
  • “volatile”键的值可能会经常变化。与时间戳一样,Bazel 期望该值始终发生变化,并相应地更新 bazel-out/volatile-status.txt 文件。不过,为了避免始终重新运行有时间戳的操作,Bazel 会假设 volatile 文件永远不会更改。换句话说,如果易失性状态文件是唯一内容发生更改的文件,Bazel 将不会使依赖于该文件的操作失效。如果操作的其他输入发生更改,Bazel 会重新运行该操作,并且该操作将看到更新后的 volatile 状态,但仅更改 volatile 状态不会使该操作失效。

    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 属性根据每条规则明确启用或停用标记。如需了解详情,请参阅 Build 百科全书。当规则设置 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-binbazel-testlogsbazel-genfiles

如果符号链接因任何原因无法创建,则系统会发出警告,但构建仍会被视为成功。具体来说,它允许您在只读目录中或您没有写入权限的目录中进行构建。在构建结束时输出的信息性消息中的所有路径都仅在符号链接指向预期位置时使用符号链接相对短形式;换句话说,即使您不能依靠正在创建的符号链接,也可以依靠这些路径的正确性。

此选项的一些常用值如下:

  • 禁止创建符号链接--symlink_prefix=/ 会导致 Bazel 不创建或更新任何符号链接,包括 bazel-outbazel-<workspace> 符号链接中披露政府所要求信息的数量和类型。使用此选项可完全禁止创建符号链接。

  • 减少杂乱问题--symlink_prefix=.bazel/ 会导致 Bazel 在隐藏目录 .bazel 内创建一个名为 bin 等的符号链接。

--platform_suffix=string

向配置简称添加后缀,用于确定输出目录。将此选项设置为不同的值会将文件放入不同的目录中,例如,有助于提高 build 的缓存命中率,从而破坏各个输出文件,或保留输出文件进行比较。

--default_visibility=(private|public)

用于测试 Bazel 默认可见性更改的临时标志。并非一般用途,但是为了本文档的完整性。

--[no]use_action_cache

此选项默认处于启用状态。停用后,Bazel 将不会使用其本地操作缓存。停用本地操作缓存可节省干净构建的内存和磁盘空间,但会减慢增量构建的速度。

--starlark_cpu_profile=_file_

该标记(其值为文件名)会使 Bazel 收集所有 Starlark 线程的 CPU 使用率统计信息,并以 ppro 格式写入配置文件, 。

使用此选项有助于识别由于计算过多而导致加载和分析速度变慢的 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 在开发周期中由软件工程师使用,在准备二进制文件以部署到生产环境时供发布工程师使用。本部分列出了针对使用 Bazel 的发布工程师的提示。

重要选项

将 Bazel 用于发布构建时,会出现与执行构建的其他脚本相同的问题。如需了解详情,请参阅从脚本调用 Bazel。具体而言,强烈建议您使用以下选项:

这些选项也很重要:

  • --package_path
  • --symlink_prefix:对于管理多个配置的 build,用不同的标识符(例如“64bit”和“32bit”)区分每个 build 可能很方便。此选项用于区分 bazel-bin(等)符号链接。

运行测试

如需使用 Bazel 构建和运行测试,请输入 bazel test,后跟测试目标的名称。

默认情况下,此命令会同时执行构建和测试活动,构建所有指定的目标(包括在命令行中指定的任何非测试目标)并测试 *_testtest_suite 目标其前提条件已构建,这意味着测试执行将与构建交错。这样做通常会显著提升速度。

bazel test的选项

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

如果此选项设置为“auto”(默认值),则 Bazel 仅在以下任何条件适用时才会重新运行测试:

  • Bazel 会检测测试或其依赖项的变化
  • 测试被标记为 external
  • 使用 --runs_per_test 请求了多次测试运行
  • 测试失败。

如果为“no”,则所有测试都将无条件执行。

如果为“yes”,则缓存行为将与 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 或 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 会输出每个测试的结果以及包含测试输出的文件的名称(如果测试失败)。此设置为默认值。
  • terseshort 类似,但较短:仅输出未通过的测试的信息。
  • 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 会为所有测试使用这些超时,方法是通过根据测试大小推断超时限制(无论大小是隐式还是显式)。

如果测试明确声明了超时类别与大小的区别,那么会收到相同的值,就像超时标记已隐式设置超时一样。因此,大小为“small”(声明“long”超时)的测试的有效超时与“large”测试相同,没有明确的超时限制。

--test_arg=arg

将命令行选项/标志/参数传递给每个测试过程。此选项可用于多次传递多个参数。例如,--test_arg=--logtostderr --test_arg=--v=3

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

指定每个测试必须注入测试环境的其他变量。如果未指定 value,它将从用于启动 bazel test 命令的 shell 环境中继承。

可以使用 System.getenv("var")、Java、getenv("var")(C 或 C++)从测试中访问环境。

--run_under=command-prefix

这会指定测试运行程序在运行前将在测试命令之前插入的前缀。使用 Bourne shell 令牌化规则将 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 构建的二进制文件类似,但并不完全相同,具体取决于要调用的二进制文件是否为测试。

当二进制文件不是测试文件时,当前工作目录将是二进制文件的 runfiles 树。

当二进制文件是测试文件时,当前工作目录将是执行根目录,并且系统将本着善意诚信的原则尝试复制环境测试。不过,模拟并不完美,具有多个分片的测试无法以这种方式运行(--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 添加的依赖项。

示例:“显示 PEBL 树中构建所有测试所需的所有 genrule 的定义位置(在 BUILD 文件中)。

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

查询操作图

借助 aquery 命令,您可以在构建图中查询操作。它针对配置后分析的目标图执行操作,并提供有关操作、工件及其关系的信息。

该工具接受多个命令行选项。--output,用于选择输出格式。默认输出格式 (text) 是人类可读格式,使用 prototextproto 作为机器可读格式。特别是,查询命令在常规 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:命令日志文件的绝对路径,其中包含最新 Bazel 命令的交错 stdout 和 stderr 流。请注意,运行 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 命令接受控制依赖项分析的所有选项,因为其中一些选项决定了 build 的输出目录的位置、编译器的选择等。

  • bazel-binbazel-testlogsbazel-genfiles:报告由 build 生成的程序所在的 bazel-* 目录的绝对路径。这通常(但并非总是)与成功构建后在基本工作区目录中创建的 bazel-* 符号链接相同。但是,如果工作区目录为只读,则无法创建 bazel-* 符号链接。使用 bazel info 报告的值的脚本将更加可靠,而不会假定存在符号链接。
  • 完整的“生成”环境。如果指定了 --show_make_env 标志,则还会显示当前配置的“Make”环境中的所有变量(例如 CCGLIBC_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

version 命令将输出已构建的 Bazel 二进制文件的版本详细信息,包括其构建时的更改列表及日期。这些库特别适用于确定您是否拥有最新的 Bazel,或者您要报告 Bug。其中一些有趣的值包括:

  • changelist:此版本 Bazel 的发布更改列表。
  • label:此 Bazel 实例的版本标签;如果该版本不是已发布的二进制文件,则为“开发版本”。在报告错误时非常有用。

不带其他参数的 bazel --version 将发出与 bazel version --gnu_format 相同的输出,只是没有可能启动 Bazel 服务器或解压缩服务器归档的副作用。bazel --version 可以从任何位置运行 - 它不需要工作区目录。

mobile-install

mobile-install 命令可将应用安装到移动设备上。 目前仅支持运行 ART 的 Android 设备。

如需了解详情,请参阅 Bazel mobile-install

支持的选项如下:

--incremental

如果已设置,Bazel 会尝试逐步安装应用,即自上次构建以来发生了更改的部分。这样无法更新从 AndroidManifest.xml、原生代码或 Java 资源(如 Class.getResource() 引用的资源)引用的资源。如果这些内容发生变化,则必须省略此选项。与 Bazel 相反,由于 Android 平台的限制,用户的责任是知道此命令何时足够好以及何时将需要安装。

如果您使用的是搭载 Marshmallow 或更高版本的设备,请考虑使用 --split_apks 标志。

--split_apks

是否使用拆分 APK 在设备上安装和更新应用。 仅适用于运行 Marshmallow 或更高版本的设备。请注意,使用 --split_apks 时,--incremental 标志不是必需的。

--start_app

安装后,以干净的状态启动应用。等同于 --start=COLD

--debug_app

在安装完成后,先等待应用以调试程序处于干净状态启动,然后再连接调试程序。 等同于 --start=DEBUG

--start=_start_type_

应用安装后应如何启动。支持的 _start_type_ 包括:

  • NO无法启动应用。这是默认设置。
  • COLD:用于在安装后从干净状态启动应用。
  • WARM:可在增量安装时保留并恢复应用状态。
  • DEBUG:在安装完成后,先等待调试程序,然后再让应用以干净状态启动。

--adb=path

表示要使用的 adb 二进制文件。

默认设置是在 --android_sdk 指定的 Android SDK 中使用 adb。

--adb_arg=serial

adb 的额外参数。这些项均位于命令行中的子命令之前,通常用于指定要安装到哪个设备。 例如,如需选择要使用的 Android 设备或模拟器:

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

调用 adb 类型:

adb -s deadbeef install ...

--incremental_install_verbosity=number

增量安装的详细程度。将此标志设置为 1 即可将调试日志记录输出到控制台。

dump

dump 命令用于输出 Bazel 服务器内部状态的转储。此命令主要供 Bazel 开发者使用,因此未指定该命令的输出,并且可能会发生变化。

默认情况下,命令将仅输出帮助消息,列出可能转储 Bazel 状态的特定区域的选项。要转储内部状态,必须至少指定一个选项。

支持的选项如下:

  • --action_cache 会转储操作缓存内容。
  • --packages 会转储软件包缓存内容。
  • --skyframe 转储内部 Bazel 依赖项图的状态。
  • --rules 会转储每个规则和方面类的规则摘要,包括计数和操作计数。这包括原生规则和 Starlark 规则。如果启用了内存跟踪,则也会输出规则的内存消耗量。
  • --skylark_memory转储普罗普兼容的 .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 会签入 Bazel(位于 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 命令可使用 --profile 选项分析之前在构建期间收集的数据。它提供了多个选项,用于分析构建执行情况或以指定格式导出数据。

支持的选项如下:

  • --dump 以简单易懂的格式显示所有收集的数据。但尚不支持其他格式。

如需了解格式详情和使用帮助,请参阅通过性能剖析排查性能问题

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 虚拟机的启动,并且适用于该服务器处理的所有后续命令。如果已经有正在运行的 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 命令并发运行(因为 shell &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_binaryjava_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 可用于选择显式 RERE 以便运行 Bazel。

--batch

批处理模式会导致 Bazel 不使用标准客户端/服务器模式,而是针对单个命令运行 Bazel Java 流程,该流程用于提高可预测性语义关于信号处理、作业控制和环境变量继承,并且是在 chroot 监狱中运行 Bazel 的必要操作。

批处理模式在同一个 output_base 中保留适当的队列语义。也就是说,并发调用将按顺序处理,不会出现重叠。如果批量模式 Bazel 是在具有正在运行的服务器的客户端上运行,则它会先终止服务器,然后再处理命令。

Bazel 在使用批处理模式或上述替代方案时运行速度变慢。 这是因为,构建文件缓存只是内存常驻,所以不会在连续的批量调用之间得到保留。 因此,在性能不太重要(如连续构建)的情况下,使用批处理模式通常更合理。

--max_idle_secs=n

此选项用于指定 Bazel 服务器进程在最后一个客户端请求之后等待多长时间(以秒为单位)。默认值为 10800(3 小时)。--max_idle_secs=0 会使 Bazel 服务器进程无限期地保留下去。

调用 Bazel 的脚本可以使用此选项,以确保它们不会在用户计算机上不运行 Bazel 服务器进程的情况下离开。例如,提交前脚本可能希望调用 bazel query,以确保用户的待处理更改不会引入不需要的依赖项。但是,如果用户尚未在该工作区中完成最近的构建,则不应让提交前脚本仅启动 Bazel 服务器,以使其在当天剩余时间内处于空闲状态。 通过在查询请求中指定较小的 --max_idle_secs 值,脚本可以确保如果它导致新服务器启动,则该服务器将立即退出,但如果相反,您已经有一台服务器在运行,该服务器将继续运行,直到在空闲时间结束为止。当然,现有服务器的空闲计时器会被重置。

--[no]shutdown_on_low_sys_mem

如果已启用并且 --max_idle_secs 设置为正时长,则在构建服务器空闲一段时间后,在系统内存不足时关闭服务器。仅限 Linux。

除了运行与 max_idle_secs 对应的空闲检查以外,构建服务器还会在服务器空闲一段时间后开始监控可用的系统内存。如果可用系统内存严重不足,服务器将会退出。

--[no]block_for_lock

启用后,Bazel 会等待其他持有服务器锁的 Bazel 命令完成后再继续执行操作。停用后,如果 Bazel 无法立即获取锁定并继续,则会错误地退出。

开发者可以在提交前检查中使用此方法,以避免由同一客户端中的其他 Bazel 命令导致的长时间等待。

--io_nice_level=n

设置一个 0-7 之间的级别,用于尽力安排 IO。0 表示最高优先级,7 表示最低优先级。预期调度程序最多只能遵循优先级 4。 负值会被忽略。

--batch_cpu_scheduling

为 Bazel 使用 batch CPU 调度。此政策适用于非交互式工作负载,但不希望降低它们的合理价值。请参阅“man 2 sched_setscheduler”。此政策可能会以 better Bazel 吞吐量为代价,提供更好的系统交互性。

其他选项

--[no]announce_rc

控制 Bazel 是否在启动时读出 Bazelrc 文件中读取的命令选项。(无条件公布启动选项)。

--color (yes|no|auto)

此选项用于确定 Bazel 是否使用颜色在屏幕上突出显示其输出。

如果此选项设置为 yes,则会启用颜色输出。如果此选项设置为 auto,那么只有在将输出发送到终端并且 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 生成的每条消息添加一个时间戳,用于指定消息的显示时间。