命令和选项

报告问题 查看源代码 每夜 build · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

本页介绍了各种 Bazel 命令（例如 bazel build、bazel run 和 bazel test）可用的选项。本页面与使用 Bazel 进行构建中的 Bazel 命令列表相辅相成。

目标语法

某些命令（例如 build 或 test）可以对目标列表执行操作。它们使用的语法比标签更灵活，如指定要构建的目标中所述。

选项

以下部分介绍了构建期间可用的选项。在帮助命令中使用 --long 时，在线帮助消息会提供有关每个选项的含义、类型和默认值的摘要信息。

大多数选项只能指定一次。如果多次指定，则最后一个实例为有效实例。在线帮助中，可多次指定的选项会带有“可多次使用”字样。

软件包位置

--package_path

此选项用于指定用于搜索给定软件包的 BUILD 文件的一组目录。

Bazel 会通过搜索软件包路径来查找软件包。这是一个以英文冒号分隔的 Bazel 目录有序列表，每个目录都是部分源代码树的根目录。

如需使用 --package_path 选项指定自定义软件包路径，请执行以下操作：

  % bazel build --package_path %workspace%:/some/other/root

软件包路径元素可以采用以下三种格式进行指定：

  1. 如果第一个字符为 /，则路径为绝对路径。
  2. 如果路径以 %workspace% 开头，则路径相对于最近的封闭 bazel 目录。例如，如果您的工作目录为 /home/bob/clients/bob_client/bazel/foo，则 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 选项类似，但仅适用于主机配置。

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

build 规则还可以在其属性中指定链接选项。此选项的设置始终优先。另请参阅 cc_library.linkopts。

--strip (always|never|sometimes)

此选项用于确定 Bazel 是否会使用 -Wl,--strip-debug 选项调用链接器，从所有二进制文件和共享库中剥离调试信息。--strip=always 表示始终剥离调试信息。--strip=never 表示永远不会剥离调试信息。如果 --compilation_mode 为 fastbuild，则 --strip=sometimes 的默认值表示剥离。

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

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

Bazel 的 --strip 选项与 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，提供的参数将用作 .gcda 文件（包含每个 .o 文件的配置文件信息）的每个对象文件目录树的目录前缀。

生成配置数据树后，应将配置树压缩为 ZIP 文件，并提供给 --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-profdata 工具准备的编有索引的 LLVM 配置文件输出文件，并且应具有 .profdata 扩展名。

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

--[no]output_symbol_counts

如果启用，C++ 可执行二进制文件的每个金标准调用链接都会输出一个符号计数文件（通过 --print-symbol-counts 金标准选项）。对于每个链接器输入，该文件都会记录定义的符号数和二进制文件中使用的符号数。这些信息可用于跟踪不必要的链接依赖项。符号计数文件会写入二进制的输出路径，并命名为 [targetname].sc。

此选项在默认情况下处于停用状态。

--java_language_version=version

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

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

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

--tool_java_language_version=version

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

--java_runtime_version=version

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

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

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

默认值为 localjdk。 可能的值包括：localjdk、localjdk_version、remotejdk_11 和 remote_jdk17。您可以使用 local_java_repository 或 remote_java_repostory 代码库规则注册自定义 JVM，以扩展这些值。

--tool_java_runtime_version=version

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

--jvmopt=jvm-option

此选项允许将选项参数传递给 Java VM。它可以与一个大参数一起使用，也可以多次与单个参数一起使用。例如：

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

将使用服务器虚拟机启动所有 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，如果它们不是当前目标的直接依赖项的输出，则会发出警告/错误。

  • off 表示检查已停用。
  • warn 表示 javac 会针对每个缺失的直接依赖项生成类型为 [strict] 的标准 Java 警告。
  • default、strict 和 error 都表示 javac 会生成错误而非警告，如果发现任何缺失的直接依赖项，都会导致当前目标构建失败。这也是在未指定标志的情况下的默认行为。

build 语义

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

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

--compilation_mode 选项（通常缩写为 -c，尤其是 -c opt）采用 fastbuild、dbg 或 opt 作为参数，并会影响各种 C/C++ 代码生成选项，例如优化级别和调试表的完整性。Bazel 会为每种不同的编译模式使用不同的输出目录，因此您可以在模式之间切换，而无需每次都进行完整重建。

  • fastbuild 表示尽可能快地构建：生成最少的调试信息 (-gmlt -Wl,-S)，并且不进行优化。这是默认值。注意：系统不会设置 -DNDEBUG。
  • dbg 表示启用了调试功能 (-g) 的 build，以便您使用 gdb（或其他调试程序）。
  • opt 表示启用了优化并停用了 assert() 调用（-O2 -DNDEBUG）的 build。除非您还传递 --copt -g，否则 opt 模式不会生成调试信息。

--cpu=cpu

此选项用于指定在构建期间用于编译二进制文件的目标 CPU 架构。

--action_env=VAR=VALUE

指定在执行所有操作期间可用的一组环境变量。变量可以按名称指定，在这种情况下，值将从调用环境中获取；也可以通过 name=value 对指定，该对可独立于调用环境设置值。

此 --action_env 标志可以多次指定。如果在多个 --action_env 标志中向同一变量分配了值，则最新的分配将生效。

--experimental_action_listener=label

experimental_action_listener 选项会指示 Bazel 使用 label 指定的 action_listener 规则中的详细信息将 extra_actions 插入到构建图中。

--[no]experimental_extra_action_top_level_only

如果此选项设为 true， --experimental_action_listener 命令行选项指定的额外操作将仅针对顶级目标进行调度。

--experimental_extra_action_filter=regex

experimental_extra_action_filter 选项会指示 Bazel 过滤要为其安排 extra_actions 的一组目标。

此标志只能与 --experimental_action_listener 标志结合使用。

默认情况下，请求的要构建的目标的传递闭包中的所有 extra_actions 都会被安排执行。--experimental_extra_action_filter 会将安排操作限制为仅针对所有者的标签与指定正则表达式匹配的 extra_actions。

以下示例将限制 extra_actions 的安排，使其仅适用于所有者的标签包含“/bar/”的操作：

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

--host_cpu=cpu

此选项用于指定应用于构建宿主工具的 CPU 架构的名称。

--fat_apk_cpu=cpu[,cpu]*

在 android_binary 规则的传递 deps 中，要为其构建 C/C++ 库的 CPU。其他 C/C++ 规则不受影响。例如，如果 cc_library 出现在 android_binary 规则和 cc_binary 规则的传递 deps 中，则 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++ 文件的基础名称（包括扩展名）。还包括任何平台依赖的接头。

为了匹配生成的文件（例如 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/ 中除 file.cc 之外的所有 .cc 文件的 C++ 编译器命令行。

--dynamic_mode=mode

确定 C++ 二进制文件是否将动态链接，并与构建规则中的 linkstatic 属性进行交互。

模式：

  • 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）时，仅为指定的一组编译模式启用分裂。这对于 bazelrc 设置很有用。设置为 yes 时，系统会普遍启用分裂功能。设置为 no 时，系统会全面停用分裂。默认值为 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）的目标。

--crosstool_top=label

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

--host_crosstool_top=label

如果未指定，Bazel 将使用 --crosstool_top 的值来编译主机配置中的代码，例如构建期间运行的工具。此标志的主要用途是启用交叉编译。

--apple_crosstool_top=label

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

--android_crosstool_top=label

用于在 android_binary 规则的传递 deps 中编译 C/C++ 规则的交叉工具。如果 build 中的其他目标需要不同的交叉工具，这非常有用。默认是使用 WORKSPACE 文件中的 android_ndk_repository 规则生成的跨工具。另请参阅 --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)

此选项用于设置要用于 bazel run、bazel test 以及由 java_binary 和 java_test 规则构建的 Java 二进制文件的基础 Java 安装的标签。JAVABASE 和 JAVA “品牌”变量派生自此选项。

--host_javabase=label

此选项用于设置要在主机配置中使用的 Java 基础安装的标签，例如主机构建工具（包括 JavaBuilder 和 Singlejar）。

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

执行策略

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

--spawn_strategy=strategy

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

  • standalone 会导致命令作为本地子进程执行。此值已废弃。请改用“local”。
  • sandboxed 会导致命令在本地机器上的沙盒中执行。这要求将所有输入文件、数据依赖项和工具都列为 srcs、data 和 tools 属性中的直接依赖项。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 策略运行“Compiling //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 在安排在本地运行的构建和测试活动时可以考虑的本地资源量（以 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 核心数。

此选项默认处于启用状态，用于指定是否应在输出目录中构建测试和二进制文件的 runfile 符号链接。使用 --nobuild_runfile_links 有助于验证所有目标是否已编译，而无需为构建 runfile 树而产生开销。

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

--[no]build_runfile_manifests

此选项默认处于启用状态，用于指定是否应将 runfile 清单写入输出树。停用此功能即表示 --nobuild_runfile_links。

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

--[no]discard_analysis_cache

启用此选项后，Bazel 会在执行开始前立即舍弃分析缓存，从而为执行阶段释放额外的内存（约 10%）。缺点是，后续增量 build 的速度会变慢。另请参阅节省内存模式。

--[no]keep_going（-k）

与 GNU Make 一样，构建的执行阶段会在遇到第一个错误时停止。有时，即使遇到错误，也应尝试尽可能进行构建，这很有用。此选项可启用此行为，如果指定此选项，构建系统会尝试构建已成功构建其前提条件的每个目标，但会忽略错误。

虽然此选项通常与 build 的执行阶段相关联，但它也会影响分析阶段：如果 build 命令中指定了多个目标，但只有其中一些目标可以成功分析，除非指定 --keep_going，否则 build 将停止并出错；在这种情况下，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 将仅构建运行 *_test 和 test_suite 规则所需的文件，这些规则并未因大小、超时、标记或语言而被过滤。如果指定了此参数，Bazel 会忽略命令行中指定的其他目标。 默认情况下，此选项处于停用状态，并且 Bazel 将构建请求的所有内容，包括从测试中滤除的 *_test 和 test_suite 规则。这很有用，因为运行 bazel test --build_tests_only foo/... 可能无法检测 foo 树中的所有构建故障。

--[no]check_up_to_date

此选项会导致 Bazel 不执行构建，而仅检查所有指定目标是否是最新的。如果是，构建会照常成功完成。但是，如果有任何文件已过时，系统会报告错误，并导致构建失败，而不是进行构建。此选项可能有助于确定构建时间是否比源代码修改时间更晚（例如，用于提交前检查），而无需产生构建费用。

另请参阅 --check_tests_up_to_date。

--[no]compile_one_dependency

编译参数文件的单个依赖项。这对于在 IDE 中对源文件进行语法检查非常有用，例如，通过重新构建依赖于源文件的单个目标，以便在编辑/构建/测试周期中尽早检测错误。此参数会影响对所有非标志参数的解读方式：每个参数都必须是文件目标标签或相对于当前工作目录的普通文件名，并且系统会构建一个依赖于每个源文件名的规则。适用于

C++ 和 Java 源代码，优先选择同一语言空间中的规则。对于具有相同偏好的多个规则，系统会选择 BUILD 文件中显示的第一个规则。未引用源文件的明确命名目标模式会导致错误。

--save_temps

--save_temps 选项会导致保存编译器的临时输出。这些文件包括 .s 文件（汇编代码）、.i（预处理的 C 语言）和 .ii（预处理的 C++ 语言）文件。这些输出通常对调试很有用。系统只会为命令行中指定的一组目标生成临时文件。

--save_temps 标志目前仅适用于 cc_* 规则。

为确保 Bazel 会输出其他输出文件的位置，请检查 --show_result n 设置是否足够高。

--build_tag_filters=tag[,tag]*

如果指定了，Bazel 将仅构建具有至少一个必需标记（如果指定了任何必需标记）且不含任何排除标记的目标。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

将测试标记为 performance 或 stress 但未标记为 flaky 的目标。

默认情况下，系统不会应用测试代码过滤。请注意，您还可以通过这种方式过滤测试的 size 和 local 标记。

--test_lang_filters=lang[,lang]*

指定具有官方 *_test 规则的语言的测试语言列表（如需查看完整列表，请参阅build 百科全书）。您可以选择在每个语言前面加上“-”以指定要排除的语言。为每种语言使用的名称应与 *_test 规则中的语言前缀相同，例如 cc、java 或 sh。

如果指定了，Bazel 将仅测试（如果还指定了 --build_tests_only，则还会构建）指定语言的测试目标。

例如，

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

只会测试 foo/... 中的 C/C++ 和 Java 测试（分别使用 cc_test 和 java_test 规则定义），而

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

将运行 foo/... 中的所有测试，但 sh_test 和 java_test 测试除外。

默认情况下，系统不会应用测试语言过滤条件。

--test_filter=filter-expression

指定测试运行程序可以用来选择要运行的测试子集的过滤条件。系统会构建调用中指定的所有目标，但可能只会根据表达式执行其中的部分目标；在某些情况下，系统只会运行特定的测试方法。

filter-expression 的具体解释取决于负责运行测试的测试框架。它可以是通配符、子字符串或正则表达式。与传递不同的 --test_arg 过滤器参数相比，--test_filter 更为方便，但并非所有框架都支持它。

详细程度

这些选项用于控制 Bazel 输出到终端或其他日志文件的详细程度。

--explain=logfile

此选项需要一个文件名参数，会导致 bazel build 执行阶段中的依赖项检查器针对每个 build 步骤说明其执行原因或其处于最新状态。说明会写入logfile。

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

--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 会输出一条消息，指明目标是否成功更新，如果成功，则会输出目标创建的输出文件列表。如果指定了多个目标，则不会显示结果信息。

虽然结果信息对于单个目标或几个目标的 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 免受 cd 和 exec 调用的侵害；请务必复制这些括号！） 不过，某些命令是在 Bazel 内部实现的，例如创建符号链接树。这些命令行不会显示。

可以传递 --subcommands=pretty_print，以便将命令的参数作为列表（而非单行）输出。这可能有助于提高长命令行的可读性。

另请参阅下文中的 --verbose_failures。

如需以工具友好的格式将子命令记录到文件，请参阅 --execution_log_json_file 和 --execution_log_binary_file。

--verbose_failures

此选项会导致 Bazel 的执行阶段输出失败命令的完整命令行。这对于调试失败的 build 非常有用。

失败的命令会以 Bourne shell 兼容的语法输出，适合复制并粘贴到 shell 提示符。

Workspace 状态

使用这些选项可为 Bazel 构建的二进制文件“盖章”：将其他信息（例如源代码控制修订版本或其他工作区相关信息）嵌入到二进制文件中。您可以将此机制与支持 stamp 属性的规则（例如 genrule、cc_binary 等）搭配使用。

--workspace_status_command=program

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

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

该程序应将零个或多个键值对输出到标准输出，每行一个条目，然后返回 0（否则构建会失败）。键名称可以是任何内容，但只能使用大写字母和下划线。键名称后面的第一个空格将键与值分隔开来。值是该行的其余部分（包括其他空格）。键和值均不得跨多行。键不得重复。

Bazel 会将键划分为两个令牌桶：“稳定”和“易失”。（“稳定”和“易失”这两个名称有点违反直觉，因此请不要过多关注它们。）

然后，Bazel 会将键值对写入两个文件：

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

合同如下：

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

    Bazel 始终输出以下稳定键：

    • BUILD_EMBED_LABEL：--embed_label 的值
    • BUILD_HOST：运行 Bazel 的主机的名称
    • BUILD_USER：Bazel 以哪个用户身份运行

  • “易失性”键的值可能会经常更改。Bazel 希望它们像时间戳一样一直更改，并会相应地更新 bazel-out/volatile-status.txt 文件。不过，为了避免始终重新运行带有时间戳的操作，Bazel 会假装易失性文件永远不会更改。换句话说，如果易失性状态文件是内容发生更改的唯一文件，Bazel 不会使依赖于它的操作失效。如果操作的其他输入发生了变化，则 Bazel 会重新运行该操作，并且该操作将看到更新后的易失性状态，但仅仅易失性状态发生变化并不会使操作失效。

    Bazel 始终会输出以下易失性键：

    • BUILD_TIMESTAMP：构建时间（自 Unix 纪元以来以秒为单位，即 System.currentTimeMillis() 的值除以 1,000）

在 Linux/macOS 上，您可以传递 --workspace_status_command=/bin/true 以停用检索 Workspace 状态，因为 true 不会执行任何操作，会成功（退出并返回 0）且不会输出任何内容。在 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 规则属性结合使用，用于控制是否将 build 信息嵌入二进制文件中。

您可以使用 stamp 属性按规则明确启用或停用加盖章功能。如需了解详情，请参阅 build 百科全书。当规则设置 stamp = -1（*_binary 规则的默认值）时，此选项会决定是否启用加盖章。

无论是否使用此选项或 stamp 属性，Bazel 都不会为针对主机配置构建的二进制文件添加标记。对于设置 stamp = 0（*_test 规则的默认值）的规则，无论 --[no]stamp 如何，都会停用加盖戳。如果目标的依赖项未发生更改，指定 --stamp 不会强制重新构建目标。

通常，为了提高 build 性能，建议设置 --nostamp，因为这有助于降低输入波动性并最大限度地提高 build 缓存。

平台

您可以使用这些选项来控制用于配置构建方式的宿主平台和目标平台，以及控制 Bazel 规则可用的执行平台和工具链。

请参阅有关平台和工具链的背景信息。

--platforms=labels

平台规则的标签，用于描述当前命令的目标平台。

--host_platform=label

用于描述主机系统的平台规则的标签。

--extra_execution_platforms=labels

可用作执行平台来运行操作的平台。 平台可以通过确切目标或目标模式进行指定。这些平台始终会优先于 WORKSPACE 文件中通过 register_execution_platforms() 声明的平台得到考虑。

--extra_toolchains=labels

在工具链解析期间要考虑的工具链规则。工具链可以按确切目标指定，也可以作为目标模式指定。这些工具链会优先于 WORKSPACE 文件中通过 register_toolchains() 声明的工具链得到考虑。

--toolchain_resolution_debug=regex

在查找工具链时，如果工具链类型与正则表达式匹配，则会输出调试信息。多个正则表达式可以用英文逗号分隔。您可以通过在开头使用 - 来否定正则表达式。这可能有助于 Bazel 或 Starlark 规则的开发者调试因缺少工具链而导致的失败问题。

其他

--flag_alias=alias_name=target_path

这是一个便捷标志，用于将较长的 Starlark build 设置绑定到较短的名称。如需了解详情，请参阅 Starlark 配置。

更改生成的便捷符号链接的前缀。符号链接前缀的默认值为 bazel-，它将创建符号链接 bazel-bin、bazel-testlogs 和 bazel-genfiles。

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

此选项的一些常见值：

  • 禁止创建符号链接： --symlink_prefix=/ 会导致 Bazel 不创建或更新任何符号链接，包括 bazel-out 和 bazel-<workspace> 符号链接。使用此选项可完全禁止创建符号链接。

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

--platform_suffix=string

向配置短名称添加后缀，用于确定输出目录。将此选项设置为不同的值会将文件放入不同的目录，例如，提高构建的缓存命中率（否则会覆盖彼此的输出文件），或保留输出文件以进行比较。

--default_visibility=(private|public)

用于测试 bazel 默认公开范围更改的临时标志。不适用于一般用途，但为了完整起见，我们还是将其记录在案。

--[no]use_action_cache

此选项默认处于启用状态。如果停用，Bazel 将不会使用其本地操作缓存。停用本地操作缓存可为干净 build 节省内存和磁盘空间，但会使增量 build 速度变慢。

--starlark_cpu_profile=_file_

此标志的值是文件的名称，会导致 Bazel 收集有关所有 Starlark 线程 CPU 使用情况的统计信息，并将配置文件以 pprof 格式写入指定的文件。

使用此选项可帮助您找出因计算量过大而导致加载和分析速度缓慢的 Starlark 函数。例如：

$ bazel build --nobuild --starlark_cpu_profile=/tmp/pprof.gz my/project/...
$ pprof /tmp/pprof.gz
(pprof) top
Type: CPU
Time: Feb 6, 2020 at 12:06pm (PST)
Duration: 5.26s, Total samples = 3.34s (63.55%)
Showing nodes accounting for 3.34s, 100% of 3.34s total
      flat  flat%   sum%        cum   cum%
     1.86s 55.69% 55.69%      1.86s 55.69%  sort_source_files
     1.02s 30.54% 86.23%      1.02s 30.54%  expand_all_combinations
     0.44s 13.17% 99.40%      0.44s 13.17%  range
     0.02s   0.6%   100%      3.34s   100%  sorted
         0     0%   100%      1.38s 41.32%  my/project/main/BUILD
         0     0%   100%      1.96s 58.68%  my/project/library.bzl
         0     0%   100%      3.34s   100%  main

如需查看同一数据的不同视图，请尝试使用 pprof 命令 svg、web 和 list。

使用 Bazel 发布

软件工程师在开发周期中会使用 Bazel，发布工程师在准备二进制文件以部署到生产环境时也会使用 Bazel。本部分提供了面向使用 Bazel 的发布工程师的提示列表。

重要选项

使用 Bazel 进行发布 build 时，会出现与执行 build 的其他脚本相同的问题。如需了解详情，请参阅从脚本调用 Bazel。具体而言，我们强烈建议您采用以下选项：

以下选项也很重要：

  • --package_path
  • --symlink_prefix：如需管理多个配置的 build，您可以使用不同的标识符（例如“64 位”与“32 位”）来区分每个 build，这样做会很方便。此选项用于区分 bazel-bin 等符号链接。

运行测试

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

默认情况下，此命令会同时执行构建和测试活动，在构建所有指定目标（包括命令行上指定的所有非测试目标）后立即测试 *_test 和 test_suite 目标，这意味着测试执行会与构建交错。这样做通常会显著提高速度。

“bazel test”的选项

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

如果此选项设为“auto”（默认值），则只有在满足以下任一条件时，Bazel 才会重新运行测试：

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

如果为“no”，则系统将无条件地执行所有测试。

如果为“yes”，缓存行为将与“auto”相同，但可能会缓存使用 --runs_per_test 的测试失败和测试运行。

如果用户在 .bazelrc 文件中默认启用了此选项，则可以使用缩写 -t（开启）或 -t-（关闭）来覆盖特定运行的默认设置。

--check_tests_up_to_date

此选项会告知 Bazel 不要运行测试，而只检查并报告缓存的测试结果。如果有任何测试之前未构建和运行，或者测试结果已过时（例如，由于源代码或 build 选项已更改），则 Bazel 会报告错误消息（“test result is not up-to-date”），将测试状态记录为“NO STATUS”（如果启用了颜色输出，则为红色），并返回非零退出代码。

此选项还暗示 [--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 标志的值：

  • 如果不存在，任何失败的运行都会导致整个测试失败。
  • 如果存在，并且来自同一分片的两次运行分别返回“通过”和“失败”，则测试将收到不稳定的状态（除非其他失败的运行导致其失败）。

如果指定一个数字，则所有测试都会运行该次数。或者，您也可以使用语法 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 仅在测试完成后立即将失败测试的组合标准输出/标准错误输出发送到标准输出，以确保同时进行的测试的输出不会交错。根据上面的摘要输出，在构建时输出摘要。
  • 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 会通过从测试大小（无论是隐式还是显式设置的大小）推断超时限制，为所有测试使用这些超时设置。

如果测试明确声明其超时类别与大小不同，则会收到与大小标记隐式设置的超时相同的值。因此，大小为“小”且声明“长”超时的测试将具有与没有显式超时的“大”测试相同的有效超时。

--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 有一个 clean 命令，类似于 Make 命令。它会删除此 Bazel 实例执行的所有 build 配置的输出目录，或此 Bazel 实例创建的整个工作树，并重置内部缓存。如果不使用任何命令行选项执行，则系统会清理所有配置的输出目录。

回想一下，每个 Bazel 实例都与单个工作区相关联，因此 clean 命令会删除您在该工作区中使用该 Bazel 实例完成的所有 build 的所有输出。

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

  % bazel clean --expunge

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

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

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

查询依赖图

Bazel 包含一种查询语言，用于询问构建期间所用依赖项图表的相关问题。两个命令（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) 是直观易懂的，请使用 proto 或 textproto 以机器可读的格式。值得注意的是，aquery 命令在常规 Bazel build 之上运行，并继承 build 期间可用的一组选项。

它支持传统 query 支持的一组函数，但 siblings、buildfiles 和 tests 不支持。

如需了解详情，请参阅Action Graph 查询。

其他命令和选项

help

help 命令提供在线帮助。默认情况下，它会显示可用命令和帮助主题的摘要，如使用 Bazel 进行构建中所示。指定参数可显示特定主题的详细帮助。大多数主题都是 Bazel 命令，例如 build 或 query，但还有一些其他帮助主题与命令不对应。

--[no]long（-l）

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

shutdown

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

Bazel 服务器会在空闲超时后自行停止，因此很少需要使用此命令；不过，如果您知道给定工作区不会再进行进一步构建，则可以在脚本中使用此命令。

shutdown 接受一个选项 --iff_heap_size_greater_than _n_，该选项需要一个整数参数（以 MB 为单位）。如果指定，则关闭取决于已消耗的内存量。这对于启动大量 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 会将其所有临时文件和构建输出放置在此目录下。

  • execution_root：output_base 下的执行根目录的绝对路径。此目录是构建期间执行的命令可访问的所有文件的根目录，也是这些命令的工作目录。如果工作区目录可写，系统会在其中放置一个名为 bazel-<workspace> 的符号链接，指向此目录。

  • output_path：执行根目录下输出目录的绝对路径，用于存放构建命令实际生成的所有文件。如果工作区目录可写入，系统会在其中放置一个名为 bazel-out 的符号链接，指向此目录。

  • server_pid：Bazel 服务器进程的进程 ID。

  • server_log：Bazel 服务器调试日志文件的绝对路径。此文件包含 Bazel 服务器生命周期内所有命令的调试信息，供 Bazel 开发者和高级用户使用。

  • command_log：命令日志文件的绝对路径；其中包含最新 Bazel 命令的交错 stdout 和 stderr 流。请注意，运行 bazel info 会覆盖此文件的内容，因为它会成为最新的 Bazel 命令。不过，除非您更改 --output_base 或 --output_user_root 选项的设置，否则命令日志文件的位置不会发生变化。

  • used-heap-size、committed-heap-size、max-heap-size：报告各种 JVM 堆大小参数。分别表示：当前使用的内存、系统当前保证可供 JVM 使用的内存、可分配的最大内存。

  • gc-count、gc-time：自此 Bazel 服务器启动以来的垃圾回收累计计数以及执行这些回收所花费的时间。请注意，这些值不会在每次构建开始时重置。

  • package_path：bazel 将搜索以下路径以查找软件包的英文冒号分隔列表。格式与 --package_path build 命令行参数相同。

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

% bazel info server_pid
1285

配置专用数据

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

  • bazel-bin、bazel-testlogs、bazel-genfiles：报告 build 生成的程序所在的 bazel-* 目录的绝对路径。这通常（但不总是）与成功构建后在基础工作区目录中创建的 bazel-* 符号链接相同。不过，如果工作区目录是只读的，则无法创建任何 bazel-* 符号链接。使用 bazel info 报告的值（而不是假定符号链接的存在性）的脚本会更稳健。
  • 完整的 “Make”环境。如果指定了 --show_make_env 标志，系统还会显示当前配置的“Make”环境中的所有变量（例如 CC、GLIBC_VERSION 等）。这些是使用 BUILD 文件中的 $(CC) 或 varref("CC") 语法访问的变量。

示例：当前配置的 C++ 编译器。这是“Make”环境中的 $(CC) 变量，因此需要 --show_make_env 标志。

  % bazel info --show_make_env -c opt COMPILATION_MODE
  opt

示例：当前配置的 bazel-bin 输出目录。即使 bazel-bin 符号链接因某种原因（例如，您是在只读目录中进行构建）而无法创建，此方法也保证是正确的。

% bazel info --cpu=piii bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/piii-opt/bin
% bazel info --cpu=k8 bazel-bin
/var/tmp/_bazel_johndoe/fbd0e8a34f61ce5d491e3da69d959fe6/execroot/io_bazel/bazel-out/k8-opt/bin

version和--version

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 命令会分析之前使用 --profile 选项在构建期间收集的数据。它提供了多个选项，可用于分析 build 执行情况或以指定格式导出数据。

支持的选项如下：

  • --dump 会以人类可读的格式显示所有收集的数据。不过，它尚不支持其他格式。

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

canonicalize-flags

canonicalize-flags 命令，该命令接受 Bazel 命令的选项列表，并返回具有相同效果的选项列表。新的选项列表是规范列表。例如，两个具有相同效果的选项列表会规范化为同一个新列表。

--for_command 选项可用于在不同的命令之间进行选择。目前，仅支持 build 和 test。给定命令不支持的选项会导致错误。

例如：

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

启动选项

本部分介绍的选项会影响 Bazel 服务器进程使用的 Java 虚拟机的启动，并且会应用于该服务器处理的所有后续命令。如果已经有 Bazel 服务器在运行，并且启动选项不匹配，则会重启该服务器。

本节中介绍的所有选项都必须使用 --key=value 或 --key value 语法指定。此外，这些选项必须显示在 Bazel 命令名称的前面。使用 startup --key=value 在 .bazelrc 文件中列出这些内容。

--output_base=dir

此选项需要一个路径实参，该实参必须指定一个可写入的目录。Bazel 将使用此位置写入其所有输出。输出基准也是客户端定位 Bazel 服务器的键。通过更改输出基准，您可以更改将处理该命令的服务器。

默认情况下，输出基准派生自用户的登录名称和工作区目录的名称（实际上是其 MD5 摘要），因此典型值如下所示：/var/tmp/google/_bazel_johndoe/d41d8cd98f00b204e9800998ecf8427e。

例如：

 OUTPUT_BASE=/var/tmp/google/_bazel_johndoe/custom_output_base
% bazel --output_base ${OUTPUT_BASE}1 build //foo  &  bazel --output_base ${OUTPUT_BASE}2 build //bar

在此命令中，两个 Bazel 命令会并行运行（由于 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_binary 和 java_test 程序支持的 --jvm_flags 参数。或者，对于测试，请使用 bazel test --test_arg=--jvm_flags=foo ...。

--host_jvm_debug

此选项会导致 Java 虚拟机在调用 Bazel 本身的主方法之前等待来自符合 JDWP 规范的调试程序的连接。这主要供 Bazel 开发者使用。

--autodetect_server_javabase

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

--batch

批处理模式会导致 Bazel 不使用标准客户端/服务器模式，而是为单个命令运行 bazel Java 进程，该进程用于实现与信号处理、作业控制和环境变量继承相关的更可预测的语义，并且对于在 chroot 监狱中运行 Bazel 来说是必需的。

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

在批处理模式下或使用上述替代方案时，Bazel 的运行速度会变慢。这是因为，除其他外，构建文件缓存驻留在内存中，因此不会在连续批量调用之间保留。因此，在性能不太关键的情况下（例如持续构建），使用批处理模式通常更为合理。

--max_idle_secs=n

此选项指定了在收到最后一个客户端请求后，Bazel 服务器进程应等待多长时间（以秒为单位）后退出。默认值为 10800（3 小时）。--max_idle_secs=0 会导致 Bazel 服务器进程无限期保留。

调用 Bazel 的脚本可以使用此选项，以确保在用户机器上不会留下 Bazel 服务器进程（否则这些进程不会运行）。例如，提交前脚本可能希望调用 bazel query，以确保用户的待处理更改不会引入不需要的依赖项。但是，如果用户最近未在该工作区中进行过构建，则不希望提交前脚本仅仅为了让 Bazel 服务器在当天余下时间保持空闲状态而启动它。通过在查询请求中指定较小的 --max_idle_secs 值，该脚本可以确保：if它导致新服务器启动，则该服务器会立即退出；但如果已经有服务器在运行，则该服务器会继续运行，直到处于空闲状态的时间达到常规时间。当然，现有服务器的空闲计时器将会重置。

--[no]shutdown_on_low_sys_mem

如果启用此功能并将 --max_idle_secs 设置为正时长，则在构建服务器闲置一段时间后，当系统内存不足时关闭服务器。仅 Linux。

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

--[no]block_for_lock

如果启用，Bazel 将等待持有服务器锁的其他 Bazel 命令完成，然后再继续操作。如果停用此选项，如果 Bazel 无法立即获取锁并继续，则会在出错时退出。

开发者可以在提交前检查中使用此选项，以避免因同一客户端中的另一个 Bazel 命令而导致长时间等待。

--io_nice_level=n

为尽力而为的 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 环境变量设置为 dumb、emacs 或 xterm-mono 以外的值时，Bazel 才会使用彩色输出。如果将此选项设置为 no，则无论输出是否要发送到终端，无论 TERM 环境变量的设置如何，系统都会停用彩色输出。

--config=name

从 rc 文件中选择其他配置部分；对于当前 command，如果存在此类部分，它还会从 command:name 中提取选项。可以多次指定此字段，以从多个配置部分添加标志。展开项可以引用其他定义（例如，展开项可以串联）。

--curses (yes|no|auto)

此选项用于确定 Bazel 是否会在其屏幕输出中使用光标控件。这样可以减少滚动数据，并使 Bazel 输出流更紧凑、更易于阅读。这与 --color 搭配使用效果非常好。

如果此选项设为 yes，则启用光标控件。 如果此选项设为 no，则会停用光标控件。 如果此选项设为 auto，则在与 --color=auto 相同的情况下，系统会启用光标控件。

--[no]show_timestamps

如果指定，系统会在 Bazel 生成的每条消息中添加一个时间戳，用于指定消息显示的时间。