命令和选项

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

目标语法

某些命令(例如 buildtest)可以对目标列表进行操作。它们使用的语法比标签更灵活,相关文档请参阅指定要构建的目标

选项

以下部分介绍了 build 期间可用的选项。当 --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,则 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 WORKSPACE
  % bazel build --package_path /some/other/path //foo

--deleted_packages

此选项指定一个以英文逗号分隔的软件包列表,Bazel 应将这些软件包视为已删除,并且不尝试从软件包路径上的任何目录加载这些软件包。此标志可用于模拟删除软件包,而不会实际删除软件包。此选项可以多次传递,在这种情况下,各个列表会串联起来。

错误检查

这些选项用于控制 Bazel 的错误检查和/或警告。

--[no]check_visibility

如果此选项设为 false,则将可见性检查降级为警告。 此选项的默认值为 true,因此默认情况下会进行可见性检查。

--output_filter=regex

--output_filter 选项只会显示与正则表达式匹配的目标的 build 和编译警告。如果目标与给定的正则表达式不匹配,但其执行成功,则其标准输出和标准错误会被舍弃。

以下是此选项的一些典型值:

`--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 选项,但仅适用于 exec 配置。

--host_conlyopt=cc-option

此选项接受一个实参,该实参将传递给编译器,用于在 exec 配置中编译的 C 源文件。这类似于 --conlyopt 选项,但仅适用于 exec 配置。

--host_cxxopt=cc-option

此选项接受一个实参,该实参将传递给在 exec 配置中编译的 C++ 源文件的编译器。这类似于 --cxxopt 选项,但仅适用于 exec 配置。

--host_linkopt=linker-option

此选项接受一个实参,该实参将传递给链接器,用于在 exec 配置中编译的源文件。这类似于 --linkopt 选项,但仅适用于 exec 配置。

--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_modefastbuild,则进行剥离。

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

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

Bazel 的 --strip 选项对应于 ld 的 --strip-debug 选项:它仅剥离调试信息。如果您出于某种原因想要剥离所有符号(而不仅仅是调试符号),则需要使用 ld 的 --strip-all 选项,为此您可以将 --linkopt=-Wl,--strip-all 传递给 Bazel。另请注意,设置 Bazel 的 --strip 标志会覆盖 --linkopt=-Wl,--strip-all,因此您只需设置其中一个。

如果您只构建一个二进制文件,并希望剥离所有符号,也可以传递 --stripopt=--strip-all 并显式构建目标的 //foo:bar.stripped 版本。如 --stripopt 部分中所述,这会在最终二进制文件链接后应用剥离操作,而不是在所有 build 的链接操作中都包含剥离。

--stripopt=strip-option

这是在生成 *.stripped 二进制文件时要传递给 strip 命令的额外选项。默认值为 -S -p。此选项可多次使用。

--fdo_instrument=profile-output-dir

--fdo_instrument 选项可在执行构建的 C/C++ 二进制文件时生成 FDO(反馈导向型优化)配置文件输出。对于 GCC,所提供的实参用作每个 .o 文件的包含配置信息的 .gcda 文件的每个对象文件目录树的目录前缀。

生成配置文件数据树后,应将配置文件树压缩,并提供给 --fdo_optimize=profile-zip Bazel 选项以启用 FDO 优化编译。

对于 LLVM 编译器,该实参也是转储原始 LLVM 配置文件的数据文件所在的目录。例如:--fdo_instrument=/path/to/rawprof/dir/

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

--fdo_optimize=profile-zip

--fdo_optimize 选项可用于在编译时使用每个对象文件的配置信息来执行 FDO(反馈引导型优化)优化。对于 GCC,提供的实参是 ZIP 文件,其中包含之前生成的 .gcda 文件树,该文件树包含每个 .o 文件的配置文件信息。

或者,所提供的实参可以指向扩展名为 .afdo 的自动配置文件。

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

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

--java_language_version=version

此选项用于指定 Java 源代码的版本。例如:

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

编译并仅允许与 Java 8 规范兼容的构造。 默认值为 11。--> 可能的值为:8、9、10、11、14 和 15,并且可以通过使用 default_java_toolchain 注册自定义 Java 工具链来扩展。

--tool_java_language_version=version

用于构建在 build 期间执行的工具的 Java 语言版本。 默认值为 11。

--java_runtime_version=version

此选项用于指定要用于执行代码和运行测试的 JVM 版本。例如:

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

从远程代码库下载 JDK 11 并使用它运行 Java 应用。

默认值为 local_jdk。 可能的值包括:local_jdklocal_jdk_versionremotejdk_11remotejdk_17。您可以使用 local_java_repositoryremote_java_repository 代码库规则注册自定义 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

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

此选项用于控制 javac 是否检查缺失的直接依赖项。Java 目标必须明确声明所有直接使用的目标作为依赖项。此标志指示 javac 确定用于对每个 Java 文件进行类型检查的实际 jar,如果这些 jar 不是当前目标的直接依赖项的输出,则发出警告/错误。

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

构建语义

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

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

此选项用于指定在 build 期间编译二进制文件时要使用的目标 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 架构来构建主机工具。

--android_platforms=platform[,platform]*

用于构建 android_binary 规则的传递 deps 的平台(专门针对 C++ 等原生依赖项)。例如,如果 cc_library 出现在 android_binary 规则的传递 deps 中,则会针对 android_binary 规则的 --android_platforms 中指定的每个平台构建一次,并包含在最终输出中。

此标志没有默认值:必须定义并使用自定义 Android 平台。

系统会为通过 --android_platforms 指定的每个平台创建一个 .so 文件并将其打包到 APK 中。.so 文件的名称以“lib”作为 android_binary 规则名称的前缀。例如,如果 android_binary 的名称为“foo”,则相应的文件为 libfoo.so

--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...

如果存在,则任何具有标签或执行路径与包含正则表达式之一匹配且与任何排除表达式都不匹配的 C++ 文件都将使用给定的选项进行构建。标签匹配使用标签的规范形式(即 //package:label_name)。

执行路径是工作区目录的相对路径,包括 C++ 文件的基本名称(包括扩展名)。它还包括任何平台相关的前缀。

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

此选项可多次使用。

无论使用哪种编译模式,此选项都会应用。例如,可以使用 --compilation_mode=opt 进行编译,并选择性地编译一些开启了更强优化功能或停用了优化功能的文件。

注意事项:如果某些文件是使用调试符号有选择地编译的,则这些符号可能会在链接期间被剥离。可以通过设置 --strip=never 来防止这种情况。

语法[+-]regex[,[+-]regex]...@option[,option]... 其中,regex 表示一个正则表达式,可以添加 + 前缀来标识包含模式,也可以添加 - 前缀来标识排除模式。option 表示传递给 C++ 编译器的任意选项。如果某个选项包含 ,,则必须使用引号将其括起来,如 \, 所示。选项也可以包含 @,因为只有第一个 @ 用于将正则表达式与选项分开。

示例--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs-O0-fprofile-arcs 选项添加到 C++ 编译器的命令行中,用于 //foo/ 中除 file.cc 之外的所有 .cc 文件。

--dynamic_mode=mode

确定 C++ 二进制文件是否会动态链接,并与 build 规则上的 linkstatic 属性进行交互。

模式:

  • auto:转换为平台相关模式;default 适用于 Linux,off 适用于 Cygwin。
  • default:允许 Bazel 选择是否动态链接。 如需了解详情,请参阅 linkstatic
  • fully:动态关联所有目标。这样可以缩短链接时间,并减小生成的二进制文件的大小。
  • off:以大多为静态模式关联所有目标。 如果在 linkopts 中设置了 -static,目标将更改为完全静态。

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

启用 Fission,该功能会将 C++ 调试信息写入专用的 .dwo 文件,而不是写入原本应写入的 .o 文件。这可大幅缩减链接的输入大小,并缩短链接时间。

如果设置为 [dbg][,opt][,fastbuild](例如:--fission=dbg,fastbuild),则仅针对指定的编译模式集启用 Fission。这对于 bazelrc 设置很有用。设置为 yes 时,Fission 会在所有位置启用。如果设置为 no,则会全局停用 Fission。默认值为 no

--force_ignore_dash_static

如果设置了此标志,则会忽略 cc_* 规则 BUILD 文件的 linkopts 中的所有 -static 选项。这仅用作 C++ 强化 build 的解决方法。

--[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)的目标中的 malloc="target" 属性。

--crosstool_top=label

此选项用于指定在构建期间用于所有 C++ 编译的 crosstool 编译器套件的位置。Bazel 将在该位置查找 CROSSTOOL 文件,并使用该文件自动确定 --compiler 的设置。

--host_crosstool_top=label

如果未指定,Bazel 会使用 --crosstool_top 的值来编译执行配置中的代码,例如在 build 期间运行的工具。此标志的主要目的是启用交叉编译。

--apple_crosstool_top=label

用于在 objc*、ios* 和 apple* 规则的传递性 deps 中编译 C/C++ 规则的 crosstool。对于这些目标,此标志会覆盖 --crosstool_top

--android_crosstool_top=label

用于编译 android_binary 规则的传递 deps 中的 C/C++ 规则的交叉工具。如果 build 中的其他目标需要不同的交叉工具链,则此功能非常有用。默认情况下,使用由 WORKSPACE 文件中的 android_ndk_repository 规则生成的 crosstool。 另请参阅 --android_platforms

--compiler=version

此选项用于指定在 build 期间用于编译二进制文件的 C/C++ 编译器版本(例如 gcc-4.1.0)。如果您想使用自定义 CROSSTOOL 进行构建,则应使用 CROSSTOOL 文件,而不是指定此标志。

--android_sdk=label

已弃用。不应直接指定此值。

此选项用于指定将用于构建任何 Android 相关规则的 Android SDK/平台工具链和 Android 运行时库。

如果在 WORKSPACE 文件中定义了 android_sdk_repository 规则,系统会自动选择 Android SDK。

--java_toolchain=label

此选项用于指定用于编译 Java 源文件的 java_toolchain 的标签。

--host_java_toolchain=label

如果未指定,bazel 会使用 --java_toolchain 的值来编译执行配置中的代码,例如在 build 期间运行的工具。此标志的主要目的是启用交叉编译。

--javabase=(label)

此选项用于设置基础 Java 安装的 标签,以供 bazel runbazel test 以及由 java_binaryjava_test 规则构建的 Java 二进制文件使用。JAVABASEJAVA “Make”变量由此选项派生而来。

--host_javabase=label

此选项用于设置要在执行配置中使用的基本 Java 安装的标签,例如用于主机 build 工具(包括 JavaBuilder 和 Singlejar)。

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

执行策略

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

--spawn_strategy=strategy

此选项用于控制命令的执行位置和方式。

  • standalone 会导致命令作为本地子进程执行。此值已弃用。请改用“local”。
  • sandboxed 会导致命令在本地机器上的沙盒内执行。这要求所有输入文件、数据依赖项和工具都列为 srcsdatatools 属性中的直接依赖项。在支持沙盒执行的系统上,Bazel 默认启用本地沙盒。
  • local 会导致命令作为本地子进程执行。
  • worker 会导致命令使用持久工作器(如果可用)执行。
  • docker 会导致命令在本地机器上的 Docker 沙盒中执行。这需要安装 Docker。
  • remote 会导致命令远程执行;只有在单独配置了远程执行器的情况下,此选项才可用。

--strategy mnemonic=strategy

此选项用于控制命令的执行位置和方式,并按助记符替换 --spawn_strategy(以及助记符为 Genrule 的 --genrule_strategy)。如需了解支持的策略及其效果,请参阅 --spawn_strategy

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

此选项用于指定应使用哪种策略来执行描述与特定 regex_filter 相匹配的命令。如需详细了解 regex_filter 匹配,请参阅 --per_file_copt。如需了解支持的策略及其效果,请参阅 --spawn_strategy

系统会使用与说明匹配的最后一个 regex_filter。此选项会替换用于指定策略的其他标志。

  • 示例:--strategy_regexp=//foo.*\\.cc,-//foo/bar=local 表示如果操作的说明与 //foo.*.cc 匹配但不与 //foo/bar 匹配,则使用 local 策略运行操作。
  • 示例: --strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed 使用 sandboxed 策略运行“Compiling //foo/bar/baz”,但反转顺序后,则使用 local 运行。
  • 示例:--strategy_regexp='Compiling.*/bar=local,sandboxed' 使用 local 策略运行“正在编译 //foo/bar/baz”,如果失败,则回退到 sandboxed

--genrule_strategy=strategy

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

--jobs=n (-j)

此选项接受一个整数实参,用于指定在 build 的执行阶段应并发执行的作业数量上限。

--progress_report_interval=n

Bazel 会定期打印尚未完成的作业(例如长时间运行的测试)的进度报告。此选项用于设置报告频率,系统每隔 n 秒就会输出进度。

默认值为 0,表示采用增量算法:第一个报告将在 10 秒后打印,然后是 30 秒,之后每分钟报告一次进度。

当 bazel 使用光标控制(如 --curses 所指定)时,每秒报告一次进度。

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

这些选项用于指定 Bazel 在安排本地运行的 build 和测试活动时可以考虑的本地资源量(以 MB 为单位的 RAM 和 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 核心数。

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

执行测试(或应用)时,其运行时数据依赖项会集中在一个位置。在 Bazel 的输出树中,此“runfiles”树通常以相应二进制文件或测试的同级节点为根。在测试执行期间,可以使用 $TEST_SRCDIR/workspace/packagename/filename 形式的路径访问 runfile。runfiles 树可确保测试能够访问其声明依赖的所有文件,而不能访问其他文件。默认情况下,通过构建一组指向所需文件的符号链接来实现 runfiles 树。随着链接集的增大,此操作的开销也会随之增加,对于某些大型 build,此操作可能会显著增加总体 build 时间,尤其因为每个单独的测试(或应用)都需要自己的 runfiles 树。

--[no]build_runfile_manifests

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

在远程执行测试时,可以停用此功能,因为 runfiles 树将根据内存中的清单远程创建。

--[no]discard_analysis_cache

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

--[no]keep_going (-k)

与 GNU Make 一样,构建的执行阶段会在遇到第一个错误时停止。有时,即使遇到错误,也要尽可能尝试构建。此选项可启用该行为,指定此选项后,构建将尝试构建所有前提条件已成功构建的目标,但会忽略错误。

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

--[no]use_ijars

此选项会更改 Bazel 编译 java_library 目标的方式。Bazel 不会使用 java_library 的输出编译依赖的 java_library 目标,而是会创建仅包含非私有成员(公共、受保护和默认(软件包)访问方法和字段)签名的接口 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 树中的所有 build breakages。

--[no]check_up_to_date

此选项会导致 Bazel 不执行 build,而只是检查所有指定的目标是否是最新的。如果存在,则构建会像往常一样成功完成。不过,如果任何文件过时,系统不会构建这些文件,而是报告错误并导致构建失败。此选项有助于确定 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_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 执行阶段的依赖项检查器针对每个 build 步骤说明执行原因或说明其是最新的。说明已写入日志文件

如果您遇到意外的重建,此选项有助于了解原因。将其添加到 .bazelrc,以便对所有后续 build 进行日志记录,然后在看到执行步骤意外执行时检查日志。此选项可能会略微降低性能,因此您可能需要在不再需要时将其移除。

--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 是一个实数。此选项的默认值为 0.02,这意味着 Bazel 会将进度消息限制为每 0.02 秒一条。

--show_result=n

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

虽然结果信息对于单个目标或少量目标的 build 很有用,但对于大型 build(例如整个顶级项目树),此信息可能会让人感到不知所措并分散注意力;此选项可用于控制此信息。--show_result 接受一个整数实参,该实参表示应打印完整结果信息的目标数量上限。默认情况下,值为 1。如果超过此阈值,系统将不会显示各个目标的任何结果信息。因此,零会导致结果信息始终被抑制,而非常大的值会导致结果始终被打印。

如果用户经常在构建小目标群组(例如,在编译-编辑-测试周期内)和大目标群组(例如,在建立新工作区或运行回归测试时)之间交替,则可能希望选择介于两者之间的值。在前一种情况下,结果信息非常有用;而在后一种情况下,结果信息则不太有用。与所有选项一样,此选项可以通过 .bazelrc 文件隐式指定。

这些文件以易于将文件名复制并粘贴到 shell 的方式打印,以便运行已构建的可执行文件。脚本(用于驱动 build)可以轻松解析每个目标的“最新”或“失败”消息。

--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 的执行阶段输出失败命令的完整命令行。这对于调试失败的 build 非常有用。

失败的命令以 Bourne shell 兼容的语法打印,适合复制并粘贴到 shell 提示符中。

工作区状态

使用这些选项可“标记”Bazel 构建的二进制文件:将其他信息(例如源代码控制修订版本或其他与工作区相关的信息)嵌入到二进制文件中。您可以将此机制与支持 stamp 属性的规则搭配使用,例如 genrulecc_binary 等。

--workspace_status_command=program

此标志可让您指定 Bazel 在每次 build 之前运行的二进制文件。该程序可以报告有关工作区状态的信息,例如当前源代码管理修订版本。

相应标志的值必须是原生程序的路径。在 Linux/macOS 上,这可以是任何可执行文件。 在 Windows 上,这必须是原生二进制文件,通常是“.exe”“.bat”或“.cmd”文件。

程序应将零个或多个键/值对打印到标准输出,每个条目占一行,然后以零退出(否则 build 会失败)。键名称可以是任何内容,但只能使用大写字母和下划线。键名称后的第一个空格用于将键名称与值分隔开。该值是行的其余部分(包括额外的空格)。键和值都不得跨多行。键不得重复。

Bazel 将键划分为两个存储分区:“稳定”和“易变”。(“稳定”和“易失”这两个名称有点反直觉,因此不必过多考虑。)

然后,Bazel 会将键值对写入两个文件:

  • bazel-out/stable-status.txt 包含键名以 STABLE_ 开头的所有键和值
  • bazel-out/volatile-status.txt 包含其余的键及其值

合同为:

  • “稳定”键的值应尽可能少地更改。如果 bazel-out/stable-status.txt 的内容发生变化,Bazel 会使依赖于这些内容的操作失效。换句话说,如果稳定键的值发生变化,Bazel 将重新运行已标记的操作。 因此,稳定状态不应包含时间戳等内容,因为它们会不断变化,并且会导致 Bazel 在每次 build 时重新运行已标记的操作。

    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 纪元以来的 build 时间(System.currentTimeMillis() 的值除以 1,000)
    • FORMATTED_DATE:build 的时间,以 yyyy MMM d HH mm ss EEE 格式(例如 2023 年 6 月 2 日 01:44:29 星期五)表示,采用世界协调时间(UTC)。

在 Linux/macOS 上,您可以传递 --workspace_status_command=/bin/true 来停用检索工作区状态,因为 true 不执行任何操作,成功(以零退出)且不打印任何输出。在 Windows 上,您可以传递 MSYS 的 true.exe 路径,以实现相同的效果。

如果工作区状态命令因任何原因失败(以非零状态退出),则 build 将失败。

在 Linux 上使用 Git 的示例程序:

#!/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 规则属性结合使用,用于控制是否在二进制文件中嵌入 build 信息。

您可以使用 stamp 属性,根据具体规则显式启用或停用标记。如需了解详情,请参阅 Build 百科全书。如果规则设置了 stamp = -1*_binary 规则的默认值),此选项将决定是否启用加盖时间戳。

无论此选项或 stamp 属性如何,Bazel 绝不会为执行配置构建的二进制文件添加 build 信息。对于设置了 stamp = 0*_test 规则的默认值)的规则,无论 --[no]stamp 的值如何,标记都会被停用。指定 --stamp 不会强制重建依赖项未更改的目标。

设置 --nostamp 通常有助于提高 build 性能,因为它可以降低输入波动性并最大限度地提高 build 缓存。

平台

您可以使用这些选项来控制主机平台和目标平台,从而配置构建的工作方式,并控制哪些执行平台和工具链可供 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 build 设置绑定到较短的名称。如需了解详情,请参阅 Starlark 配置

更改了生成的便捷符号链接的前缀。符号链接前缀的默认值为 bazel-,这将创建符号链接 bazel-binbazel-testlogsbazel-genfiles

如果由于任何原因无法创建符号链接,系统会发出警告,但仍会将 build 视为成功。具体来说,这允许您构建只读目录或您无权写入的目录。在 build 结束时,信息性消息中打印的任何路径都将仅使用符号链接相对的简短形式(如果符号链接指向预期位置);换句话说,您可以依赖这些路径的正确性,即使您无法依赖所创建的符号链接也是如此。

此选项的一些常见值:

  • 禁止创建符号链接--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,发布工程师在准备将二进制文件部署到生产环境时也使用 Bazel。本部分提供了一份使用 Bazel 的发布工程师提示列表。

重要选项

使用 Bazel 进行发布 build 时,会遇到与执行 build 的其他脚本相同的问题。如需了解详情,请参阅从脚本调用 Bazel。我们强烈建议您选择以下选项:

以下选项也很重要:

  • --package_path
  • --symlink_prefix:为了管理多种配置的 build,最好使用不同的标识符来区分每个 build,例如“64 位”与“32 位”。此选项用于区分 bazel-bin(等)符号链接。

运行测试

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

默认情况下,此命令会同时执行构建和测试活动,构建所有指定的目标(包括命令行中指定的任何非测试目标),并在 *_testtest_suite 目标的前提条件构建完成后立即测试这些目标,这意味着测试执行与构建交织在一起。这样做通常会显著提高速度。

bazel test”的选项

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

如果此选项设置为“自动”(默认值),则仅当满足以下任一条件时,Bazel 才会重新运行测试:

  • Bazel 检测到测试或其依赖项发生了变化
  • 测试标记为 external
  • 请求了多次测试运行,但 --runs_per_test
  • 测试失败。

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

如果为“是”,则缓存行为与“自动”相同,但可能会缓存测试失败和带有 --runs_per_test 的测试运行。

如果用户已在 .bazelrc 文件中默认启用此选项,则可能会发现使用缩写 -t(开启)或 -t-(关闭)在特定运行中覆盖默认设置非常方便。

--check_tests_up_to_date

此选项会告知 Bazel 不运行测试,而只是检查并报告缓存的测试结果。如果有任何测试之前未构建和运行过,或者其测试结果已过时(例如,由于源代码或 build 选项已更改),则 Bazel 会报告错误消息(“测试结果不是最新结果”),将测试的状态记录为“无状态”(如果启用了彩色输出,则为红色),并返回非零退出代码。

此选项还意味着 [--check_up_to_date](#check-up-to-date) 行为。

此选项可能有助于进行提交前检查。

--test_verbose_timeout_warnings

此选项会指示 Bazel 在测试的超时时间明显长于测试的实际执行时间时,明确警告用户。虽然测试的超时时间应设置为不会出现不稳定的情况,但如果测试的超时时间过长,可能会隐藏意外出现的实际问题。

例如,通常在一两分钟内执行完毕的测试不应将超时时间设置为 ETERNAL 或 LONG,因为这些值过于宽松。

此选项有助于用户确定合适的超时值或对现有超时值进行健全性检查。

--[no]test_keep_going

默认情况下,所有测试都会运行到完成。不过,如果停用此标志,则在任何测试未通过时,build 都会中止。后续 build 步骤和测试调用不会运行,并且正在进行的调用会被取消。请勿同时指定 --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,则测试将收到 flaky 状态(除非其他失败的运行导致测试失败)。

如果指定了单个数字,则所有测试都将运行相应次数。 或者,也可以使用 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 显示了每项测试是通过还是失败的摘要。还会显示失败测试的输出日志文件名。摘要将在 build 结束时打印出来(在 build 期间,当测试开始、通过或失败时,只会看到简单的进度消息)。 这是默认行为。
  • errors 仅在测试完成后立即将失败测试的组合 stdout/stderr 输出发送到 stdout,确保同时进行的测试的输出不会相互交错。在 build 时打印摘要,如上面的摘要输出所示。
  • 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 会将这些超时时间用于所有测试,并根据测试的大小(无论大小是隐式还是显式设置的)推断超时时间限制。

如果测试明确声明其超时类别与大小不同,则会收到与通过大小标记隐式设置的超时相同的值。因此,声明了“long”超时时长的“small”大小的测试将具有与未明确指定超时时长的“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

此属性用于指定测试运行程序在运行测试命令之前将插入到该命令前面的前缀。command-prefix 使用 Bourne shell 标记化规则拆分为字词,然后将字词列表添加到将要执行的命令之前。

如果第一个字词是完全限定标签(以 // 开头),则会构建该标签。然后,该标签会被替换为相应的可执行位置,该位置会附加到将与其他字词一起执行的命令前面。

请注意以下事项:

  • 用于运行测试的 PATH 可能与您环境中的 PATH 不同,因此您可能需要为 --run_under 命令(command-prefix 中的第一个字词)使用绝对路径
  • stdin 未连接,因此 --run_under 无法用于交互式命令。

示例:

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

测试选择

输出选择选项中所述,您可以按大小超时时间标记语言过滤测试。便捷的常规名称过滤条件可以将特定的过滤条件实参转发给测试运行程序。

bazel test”的其他选项

语法和其余选项与 bazel build 完全相同。

运行可执行文件

bazel run 命令与 bazel build 类似,但用于构建和运行单个目标。以下是一个典型的会话:

  % 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 的工作区的根目录。
  • 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_* 实参均无效。

清理 build 输出

clean 命令

Bazel 有一个与 Make 类似的 clean 命令。它会删除此 Bazel 实例执行的所有 build 配置的输出目录,或此 Bazel 实例创建的整个工作树,并重置内部缓存。如果执行时未指定任何命令行选项,则会清理所有配置的输出目录。

请注意,每个 Bazel 实例都与一个工作区相关联,因此 clean 命令会删除您在该工作区中使用相应 Bazel 实例执行的所有 build 的所有输出。

如需完全移除由 Bazel 实例创建的整个工作树,您可以指定 --expunge 选项。使用 --expunge 执行 clean 命令时,该命令只会移除整个输出库树,其中除了包含 build 输出之外,还包含 Bazel 创建的所有临时文件。它还会在清理后停止 Bazel 服务器,相当于 shutdown 命令。例如,如需清理 Bazel 实例的所有磁盘和内存轨迹,您可以指定:

  % bazel clean --expunge

或者,您也可以使用 --expunge_async 在后台执行清除操作。在异步清除继续运行时,在同一客户端中调用 Bazel 命令是安全的。

clean 命令主要用于回收不再需要的工作区的磁盘空间。Bazel 的增量重建可能并不完美,因此在出现问题时,可以使用 clean 来恢复一致的状态。

Bazel 的设计使得这些问题可以修复,并且这些 bug 是需要优先修复的。如果您发现增量 build 不正确,请提交 bug 报告,并在工具中报告 bug,而不是使用 clean

查询依赖关系图

Bazel 包含一种查询语言,可用于询问有关 build 期间使用的依赖关系图的问题。查询语言由两个命令使用:query 和 cquery。这两个命令的主要区别在于,query 在加载阶段之后运行,而 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 命令查询 build 图中的操作。它基于配置的后分析目标图运行,并公开有关操作、制品及其关系的信息。

该工具接受多个命令行选项。 --output 选择输出格式。默认输出格式 (text) 为人类可读格式,使用 prototextproto 可获得机器可读格式。 值得注意的是,aquery 命令在常规 Bazel build 的基础上运行,并继承 build 期间可用的选项集。

它支持与传统 query 相同的函数集,但 siblingsbuildfilestests 除外。

如需了解详情,请参阅操作图表查询

其他命令和选项

help

help 命令提供在线帮助。默认情况下,它会显示可用命令和帮助主题的摘要,如使用 Bazel 进行构建中所述。 指定实参会显示特定主题的详细帮助。大多数主题都是 Bazel 命令,例如 buildquery,但也有一些不对应于命令的额外帮助主题。

--[no]long (-l)

默认情况下,bazel help [topic] 仅会输出主题的相关选项摘要。如果指定了 --long 选项,系统还会显示每个选项的类型、默认值和完整说明。

shutdown

您可以使用 shutdown 命令停止 Bazel 服务器进程。此命令会导致 Bazel 服务器在空闲时(例如,在完成当前正在进行的任何 build 或其他命令后)立即退出。如需了解详情,请参阅客户端/服务器实现

Bazel 服务器会在空闲超时后自行停止,因此很少需要使用此命令;不过,如果已知在给定工作区中不会再进行任何构建,此命令在脚本中会很有用。

shutdown 接受一个选项 --iff_heap_size_greater_than _n_,该选项需要一个整数实参(以 MB 为单位)。如果指定,则此参数会使关机操作取决于已消耗的内存量。这对于启动大量 build 的脚本非常有用,因为 Bazel 服务器中的任何内存泄漏都可能导致其偶尔出现意外崩溃;执行有条件的重启可以避免这种情况。

info

info 命令会输出与 Bazel 服务器实例或特定 build 配置关联的各种值。(这些变量可能由驱动 build 的脚本使用。)

info 命令还允许使用单个(可选)实参,即下方列表中某个键的名称。在这种情况下,bazel info key 将仅输出相应键的值。(在编写 Bazel 脚本时,这尤其方便,因为这样一来,就不需要通过 sed -ne /key:/s/key://p 管道传输结果:

与配置无关的数据

  • release:相应 Bazel 实例的发布标签,如果不是已发布的二进制文件,则为“开发版本”。
  • workspace 基本工作区目录的绝对路径。
  • install_base:相应 Bazel 实例为当前用户使用的安装目录的绝对路径。Bazel 会将内部所需的执行程序安装在此目录下。

  • output_base:此 Bazel 实例针对当前用户和工作区组合所使用的基本输出目录的绝对路径。Bazel 将其所有临时文件和 build 输出都放在此目录下。

  • 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 服务器启动以来垃圾回收的累计次数以及执行这些垃圾回收所花费的时间。请注意,这些值不会在每次 build 开始时重置。

  • package_path:以英文冒号分隔的路径列表,Bazel 将在这些路径中搜索软件包。与 --package_path build 命令行实参具有相同的格式。

示例:Bazel 服务器的进程 ID。

% bazel info server_pid
1285

配置专用数据

这些数据可能会受到传递给 bazel info 的配置选项的影响,例如 --cpu--compilation_mode 等。info 命令接受所有控制依赖项分析的选项,因为其中一些选项会决定 build 的输出目录位置、编译器的选择等。

  • bazel-binbazel-testlogsbazel-genfiles:报告 build 生成的程序所在的 bazel-* 目录的绝对路径。这通常(但不一定)与成功构建后在基本工作区目录中创建的 bazel-* 符号链接相同。不过,如果工作区目录是只读的,则无法创建任何 bazel-* 符号链接。使用 bazel info 报告的值(而不是假设符号链接存在)的脚本将更加可靠。
  • 完整的 “Make”环境。如果指定了 --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

版本命令会输出有关已构建 Bazel 二进制文件的版本详细信息,包括构建时所处的变更列表和日期。这些信息对于确定您是否拥有最新的 Bazel 版本或报告 bug 非常有用。一些有趣的值包括:

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

bazel --version(不带其他实参)将生成与 bazel version --gnu_format 相同的输出,但不会产生可能启动 Bazel 服务器或解压缩服务器归档文件的副作用。bazel --version 可从任何位置运行,不需要工作区目录。

mobile-install

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

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

支持的选项如下:

--incremental

如果设置了该标志,Bazel 会尝试以增量方式安装应用,即仅安装自上次 build 以来发生更改的部分。此选项无法更新从 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 将与 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 命令用于分析之前在 Bazel 调用期间收集的 JSON 跟踪配置文件

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。请改用 build 选项 --javabase--host_javabase

此标志之前名为 --host_javabase(有时称为“左侧”--host_javabase),但已重命名,以免与 build 标志 --host_javabase(有时称为“右侧”--host_javabase)混淆。

--host_jvm_args=string

指定要传递给运行 Bazel 本身的 Java 虚拟机的启动选项。这可用于设置堆栈大小,例如:

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

此选项可多次使用,并搭配不同的实参。请注意,很少需要设置此标志。您还可以传递以空格分隔的字符串列表,每个字符串都将被解读为单独的 JVM 实参,但此功能很快就会被弃用。

不会影响 Bazel 子进程(应用、测试、工具等)使用的任何 JVM。如需将 JVM 选项传递给可执行的 Java 程序(无论是由 bazel run 运行还是在命令行中运行),您都应使用所有 java_binaryjava_test 程序都支持的 --jvm_flags 实参。或者,对于测试,请使用 bazel test --test_arg=--jvm_flags=foo ...

--host_jvm_debug

此选项会导致 Java 虚拟机在调用 Bazel 本身的 main 方法之前,等待来自符合 JDWP 标准的调试器的连接。此属性主要供 Bazel 开发者使用。

--autodetect_server_javabase

此选项会导致 Bazel 在启动时自动搜索已安装的 JDK,并在嵌入式 JRE 不可用时回退到已安装的 JRE。--explicit_server_javabase 可用于选择运行 Bazel 时使用的显式 JRE。

--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,以确保用户的待处理更改不会引入不必要的依赖项。不过,如果用户最近未在该工作区中进行过 build,那么预提交脚本启动 Bazel 服务器后,该服务器在一天剩余的时间内都处于闲置状态,这并不理想。通过在查询请求中指定较小的 --max_idle_secs 值,脚本可以确保如果它导致新服务器启动,该服务器将立即退出;但如果已有服务器在运行,该服务器将继续运行,直到空闲时间达到正常时间。当然,现有服务器的空闲计时器将被重置。

--[no]shutdown_on_low_sys_mem

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

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

--[no]block_for_lock

如果启用,Bazel 将等待持有服务器锁的其他 Bazel 命令完成后再继续执行。如果停用,当 Bazel 无法立即获取锁并继续运行时,会以错误状态退出。

开发者可能会在预提交检查中使用此标志,以避免同一客户端中的另一个 Bazel 命令导致长时间等待。

--io_nice_level=n

为尽力而为的 IO 调度设置 0-7 之间的级别。0 为最高优先级,7 为最低优先级。预期调度程序可能仅支持最高优先级 4。系统会忽略负值。

--batch_cpu_scheduling

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

其他选项

--[no]announce_rc

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

--color (yes|no|auto)

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

如果此选项设置为 yes,则会启用彩色输出。 如果此选项设置为 auto,则仅当输出发送到终端且 TERM 环境变量设置为 dumbemacsxterm-mono 以外的值时,Bazel 才会使用彩色输出。如果此选项设置为 no,则无论输出是否发送到终端,也无论 TERM 环境变量的设置如何,系统都会停用彩色输出。

--config=name

rc 文件中选择其他配置部分;对于当前的 command,如果存在这样的部分,它还会从 command:name 中拉取相应选项。可以多次指定此标志,以添加多个配置部分中的标志。扩展可以引用其他定义(例如,扩展可以链接在一起)。

--curses (yes|no|auto)

此选项用于确定 Bazel 是否会在其屏幕输出中使用光标控制。这样可以减少滚动数据,并使 Bazel 的输出流更加紧凑,更易于阅读。此功能可与 --color 搭配使用。

如果此选项设置为 yes,则启用光标控制功能。 如果此选项设置为 no,则光标控制功能处于停用状态。 如果此选项设置为 auto,则在与 --color=auto 相同的条件下启用光标控制。

--[no]show_timestamps

如果指定,则会向 Bazel 生成的每条消息添加一个时间戳,用于指定显示消息的时间。