本页介绍了各种 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
可以通过三种格式指定软件包路径元素:
- 如果第一个字符是
/
,则路径是绝对路径。 - 如果路径以
%workspace%
开头,则选择相对于最近的封闭 bazel 目录的路径。例如,如果您的工作目录是/home/bob/clients/bob_client/bazel/foo
,则软件包路径中的字符串%workspace%
会展开为/home/bob/clients/bob_client/bazel
。 - 其他所有内容都将相对于工作目录进行。这通常不是您想要执行的操作,而且如果您从 bazel 工作区下的目录使用 Bazel,可能会出现意外行为。例如,如果您使用软件包路径元素
.
,然后通过 cd 命令进入/home/bob/clients/bob_client/bazel/foo
目录,则系统会从/home/bob/clients/bob_client/bazel/foo
目录解析软件包。
如果您使用非默认软件包路径,为方便起见,请在 Bazel 配置文件中指定该路径。
Bazel 不需要当前目录中包含任何软件包,因此,如果您可以在软件包路径上的其他位置找到所有必要的软件包,则您可以从空的 bazel 工作区执行构建。
示例:从空客户端构建
% mkdir -p foo/bazel % cd foo/bazel % touch WORKSPACE % bazel build --package_path /some/other/path //foo
--deleted_packages
此选项以逗号分隔列表的形式指定 Bazel 应将其视为已删除的软件包,并且不会尝试从软件包路径上的任何目录加载这些软件包。这可用于模拟删除软件包而不实际删除软件包的操作。此选项可以传递多次,在这种情况下,各个列表会串联起来。
检查时出错
这些选项用于控制 Bazel 的错误检查和/或警告。
--[no]check_visibility
如果此选项设置为 false,可见性检查会降级为警告。 此选项的默认值为 true,表示系统会默认完成可见性检查。
--output_filter=regex
--output_filter
选项将仅显示与正则表达式匹配的目标的构建和编译警告。如果目标与给定正则表达式不匹配并且其执行成功,则将丢弃其标准输出和标准错误。
以下是此选项的一些典型值:
`--output_filter='^//(first/project|second/project):'` | 显示指定软件包的输出。 |
`--output_filter='^//((?!(first/bad_project|second/bad_project):).)*$'` | 不显示指定软件包的输出。 |
`--output_filter=` | 显示全部内容。 |
`--output_filter=DONT_MATCH_ANYTHING` | 不显示任何内容。 |
工具标志
这些选项用于控制 Bazel 会将哪些选项传递给其他工具。
--copt=cc-option
此选项采用要传递给编译器的参数。每次为了对 C、C++ 或汇编代码进行预处理、编译和/或汇编而调用编译器时,该参数都将传递给编译器。关联时不会传递此参数。
此选项可多次使用。例如:
% bazel build --copt="-g0" --copt="-fpic" //foo
将在没有调试表的情况下编译 foo
库,从而生成位置无关代码。
--host_copt=cc-option
此选项采用一个参数,该参数将传递到在 exec 配置中编译的源文件的编译器。这与 --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
表示永不去除调试信息。如果 --compilation_mode
为 fastbuild
,则 --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-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 规范兼容的结构。
默认值为 8。--> 可能的值包括 8、9、10、11、14、15 和 21,并且可以通过使用 default_java_toolchain
注册自定义 Java 工具链来进行扩展。
--tool_java_language_version=version
用于构建在构建期间执行的工具的 Java 语言版本。默认值为 8。
--java_runtime_version=version
此选项指定用于执行代码和运行测试的 JVM 版本。例如:
% bazel run --java_runtime_version=remotejdk_11 java/com/example/common/foo:java_application
从远程代码库下载 JDK 11,并使用它运行 Java 应用。
默认值为 local_jdk
。
可能的值包括 local_jdk
、local_jdk_version
、remotejdk_11
和 remotejdk_17
。您可以使用 local_java_repository
或 remote_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。
此选项会依次传递给 javac、javac 的 Bazel 内置默认选项、per-rule 选项。javac 任意选项的最后一个规范胜出。javac 的默认选项包括:
-source 8 -target 8 -encoding UTF-8
--strict_java_deps (default|strict|off|warn|error)
此选项用于控制 javac 是否检查是否存在直接依赖项。Java 目标必须将所有直接使用的目标明确声明为依赖项。此标志指示 javac 确定实际用于类型检查每个 java 文件的 jar 文件,并在它们不是当前目标的直接依赖项的输出时警告/错误。
off
表示已停用检查功能。warn
表示 javac 将为每个缺少的直接依赖项生成[strict]
类型的标准 Java 警告。default
、strict
和error
都意味着 javac 将生成错误而不是警告,导致在找到任何缺失的直接依赖项的情况下无法构建当前目标。未指定标志时,这也是默认行为。
构建语义
这些选项会影响构建命令和/或输出文件内容。
--compilation_mode (fastbuild|opt|dbg)
(-c)
--compilation_mode
选项(通常简写为 -c
,尤其是 -c opt
)采用 fastbuild
、dbg
或 opt
的参数,并影响各种 C/C++ 代码生成选项,例如优化级别和调试表的完整性。Bazel 会针对每个不同的编译模式使用不同的输出目录,因此您可以在模式之间切换,而无需每次都进行全面重新构建。
fastbuild
表示尽可能快速构建:仅生成最少量的调试信息 (-gmlt -Wl,-S
),并且不进行优化。这是默认值。注意:不会设置-DNDEBUG
。dbg
表示在构建时启用了调试功能 (-g
),这样您就可以使用 gdb(或其他调试程序)。opt
表示 build 启用了优化功能并停用了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
标志结合使用。
默认情况下,已请求的“target-to-build”的传递闭包中的所有 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
指定的每个平台,在 APK 中创建并打包一个 .so
文件。.so
文件的名称会在 android_binary
规则名称的前面加上“lib”。例如,如果 android_binary
的名称为“foo”,则文件为 libfoo.so
。
--per_file_copt=[+-]regex[,[+-]regex]...@option[,option]...
如果存在,则任何 C++ 文件的标签或执行路径与其中一个包含正则表达式匹配,但不与任何排除表达式匹配,都将使用给定的选项构建。标签匹配使用标签的规范形式(即 //package
:label_name
)。
执行路径是工作区目录的相对路径,包括 C++ 文件的基础名称(包括扩展名)。它还包含任何依赖于平台的前缀。
为了匹配生成的文件(例如 Genrule 输出),Bazel 只能使用执行路径。在这种情况下,正则表达式不应以“//”开头,因为它与任何执行路径都不匹配。您可按如下方式使用软件包名称:--per_file_copt=base/.*\.pb\.cc@-g0
。这将匹配名为 base
的目录下的每个 .pb.cc
文件。
此选项可多次使用。
无论使用何种编译模式,都会应用此选项。例如,可以使用 --compilation_mode=opt
进行编译,并在启用或停用优化功能的情况下选择性地编译某些文件。
注意事项:如果某些文件是选择性地使用调试符号进行编译的,那么这些符号可能会在链接期间被移除。可以通过设置 --strip=never
防止发生这种情况。
语法:[+-]regex[,[+-]regex]...@option[,option]...
其中 regex
代表正则表达式,该表达式可以带有一个前缀 +
(用于标识包含模式)和 -
(用来标识排除模式)。option
表示传递给 C++ 编译器的任意选项。如果某个选项包含 ,
,则必须像 \,
这样引用它。选项也可以包含 @
,因为只有第一个 @
用于分隔正则表达式与选项。
示例:--per_file_copt=//foo:.*\.cc,-//foo:file\.cc@-O0,-fprofile-arcs
针对 //foo/
中的所有 .cc
文件(file.cc
除外),将 -O0
和 -fprofile-arcs
选项添加到 C++ 编译器的命令行中。
--dynamic_mode=mode
用于确定是否动态关联 C++ 二进制文件,以便与构建规则中的 linkstatic 属性进行交互。
模式:
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 文件的 linkopt 中的任何 -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
。
--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
的值编译 exec 配置中的代码,例如针对在构建期间运行的工具进行编译。此标记的主要用途是启用交叉编译。
--javabase=(label)
此选项可设置基本 Java 安装的标签,用于 bazel run、bazel 测试以及通过 java_binary
和 java_test
规则构建的 Java 二进制文件。JAVABASE
和 JAVA
“Make”变量派生自此选项。
--host_javabase=label
此选项可设置要在 exec 配置中使用的基本 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_strategy 的助记符)。如需了解支持的策略及其影响,请参阅 --spawn_strategy。
--strategy_regexp=<filter,filter,...>=<strategy>
此选项指定应使用哪种策略执行说明与特定 regex_filter
匹配的命令。如需详细了解 regex_filter 匹配,请参阅 --per_file_copt。如需了解支持的策略及其影响,请参阅 --spawn_strategy。
系统会使用与说明匹配的最后一个 regex_filter
。此选项将替换用于指定策略的其他标志。
- 示例:
--strategy_regexp=//foo.*\\.cc,-//foo/bar=local
表示如果操作的说明与 //foo.*.cc 而非 //foo/bar 匹配,则使用local
策略执行操作。 - 示例:
--strategy_regexp='Compiling.*/bar=local' --strategy_regexp=Compiling=sandboxed
会按照sandboxed
策略运行“Compiling //foo/bar/baz”,但是如果颠倒顺序,则会使用local
运行该命令。 - 示例:
--strategy_regexp='Compiling.*/bar=local,sandboxed'
会使用local
策略运行“Compiling //foo/bar/baz”,如果失败,则回退到sandboxed
。
--genrule_strategy=strategy
这是一个已废弃的 --strategy=Genrule=strategy
简写形式,
--jobs=n
(-j)
此选项采用整数参数,用于指定在构建的执行阶段应并发执行的作业数量限制。
--progress_report_interval=n
Bazel 会定期针对尚未完成的作业(例如长时间运行的测试)输出进度报告。此选项会设置报告频率,每 n
秒输出一次进度。
默认值为 0,这意味着增量算法:系统将在 10 秒后输出第一份报告,然后在 30 秒后输出第一份报告,之后每分钟报告一次该进度。
当 bazel 使用光标控件(通过 --curses
指定)时,每秒报告一次进度。
--local_{ram,cpu}_resources resources or resource expression
这些选项指定了 Bazel 在本地安排构建和测试活动时可以考虑的本地资源量(RAM 以 MB 为单位以及 CPU 逻辑核心的数量)。这些标记可以是整数,也可以是关键字(HOST_RAM 或 HOST_CPUS),后面可以跟 [-|*
float]
(例如 --local_cpu_resources=2
、--local_ram_resources=HOST_RAM*.5
和 --local_cpu_resources=HOST_CPUS-1
)。这些标志是独立的;可以设置其中之一或同时设置两者。默认情况下,Bazel 会直接根据本地系统的配置来估算 RAM 和 CPU 核心的数量。
--[no]build_runfile_links
此选项默认处于启用状态,用于指定是否应在输出目录中构建测试和二进制文件的 runfiles 符号链接。若要验证所有目标是否都能编译,而不会产生构建 runfile 树的开销,使用 --nobuild_runfile_links
非常有用。
执行测试(或应用)时,其运行时数据依赖项会收集到一个位置。在 Bazel 的输出树中,此“runfiles”树通常作为对应二进制文件或测试的同级拥有 root 权限。在测试执行期间,可使用 $TEST_SRCDIR/workspace/packagename/filename
形式的路径访问 Runfile。runfiles 树可确保测试能够访问已声明依赖项的所有文件,而仅此而已。默认情况下,Runfiles 树通过构建一组指向所需文件的符号链接来实现。随着链接集的不断增加,此操作的成本也会增加,并且对于某些大型 build,它对总构建时间的影响会显著增加,特别是因为每个测试(或应用)都需要有自己的 runfiles 树。
--[no]build_runfile_manifests
此选项默认处于启用状态,用于指定是否应将 runfiles 清单写入输出树。停用它意味着 --nobuild_runfile_links
。
您可以在远程执行测试时停用该功能,因为系统将通过内存清单远程创建 runfile 树。
--[no]discard_analysis_cache
启用此选项后,Bazel 会在执行开始前舍弃分析缓存,从而在执行阶段释放额外的内存(大约 10%)。缺点是,进一步的增量构建速度会减慢。另请参阅内存节省模式。
--[no]keep_going
(-k)
与在 GNU Make 中一样,遇到第一个错误时,构建的执行阶段会停止。有时,即使在面对错误时也尝试尽可能多地构建非常有用。此选项会启用该行为;如果指定此选项,构建将尝试构建所有已构建前提条件的目标,但会忽略错误。
虽然此选项通常与构建的执行阶段相关联,但也会影响分析阶段:如果在构建命令中指定了多个目标,但只有部分目标可以成功分析,那么除非指定了 --keep_going
,否则构建将会停止并报错。在这种情况下,构建将进入执行阶段,但仅针对成功分析的目标。
--[no]use_ijars
此选项会更改 Bazel 编译 java_library
目标的方式。Bazel 会创建仅包含非私有成员(公共、受保护和默认(软件包)访问方法和字段)签名的接口 jar 文件,并使用接口 JAR 编译相关目标,而不是将 java_library
的输出用于编译相关 java_library
目标。这样,在只对类的方法体或私有成员进行更改时,就可以避免重新编译。
--[no]interface_shared_objects
此选项会启用接口共享对象,这会使二进制文件和其他共享库依赖于共享对象的接口,而不是其实现。当只有实现发生变化时,Bazel 可以避免不必要地重新构建依赖于更改后的共享库的目标。
输出选择
这些选项决定了要构建或测试的内容。
--[no]build
此选项会导致构建执行阶段;默认处于开启状态。关闭后,系统会跳过执行阶段,仅发生前两个阶段,即加载和分析。
此选项可用于验证 build 文件并检测输入中的错误,而无需实际构建任何内容。
--[no]build_tests_only
如果指定,Bazel 将仅构建运行因大小、超时、标记或语言而未被滤除的 *_test
和 test_suite
规则所需的内容。如果指定,Bazel 将忽略命令行中指定的其他目标。
默认情况下,此选项处于停用状态,并且 Bazel 将构建请求的所有内容,包括从测试中滤除的 *_test
和 test_suite
规则。这很有用,因为运行 bazel test --build_tests_only foo/...
可能不会检测到 foo
树中的所有 build 破坏情况。
--[no]check_up_to_date
此选项会导致 Bazel 不执行构建,而只是检查所有指定的目标是否都是最新的。如果这样,构建会像往常一样成功完成。不过,如有任何文件已过期,那么系统会报告错误且构建失败,而不会进行构建。此选项可能有助于确定 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 将仅构建符合以下条件的目标:至少包含一个必需标记(如果指定了其中任何标记)且不包含任何已排除的标记。构建标记过滤条件被指定为标记关键字的逗号分隔列表,可以选择在前面加上“-”符号(用于表示排除的标记)。必需的标记也可以带有“+”号。
在运行测试时,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=string[,string]*
以逗号分隔列表的形式指定引用测试规则类名称的字符串。如需引用规则类 foo_test
,请使用字符串“foo”。Bazel 将仅测试所引用的规则类的目标(如果还指定了 --build_tests_only
,则进行构建)。如需排除这些目标,请使用字符串“-foo”。例如,
% bazel test --test_lang_filters=foo,bar //baz/...
将仅测试 //baz/...
中 foo_test
或 bar_test
的实例,而
% bazel test --test_lang_filters=-foo,-bar //baz/...
将测试 //baz/...
中的所有目标(foo_test
和 bar_test
实例除外)。
--test_filter=filter-expression
指定测试运行程序可用于选择要运行的部分测试的过滤条件。调用中指定的所有目标都已构建,但根据表达式,只有部分目标可以执行;在某些情况下,仅运行某些测试方法。
filter-expression 的具体解释由负责运行测试的测试框架决定。它可以是 glob、子字符串或正则表达式。--test_filter
可以简化传递不同的 --test_arg
过滤器参数,但并非所有框架都支持它。
详细程度
这些选项可以控制 Bazel 输出(包括终端或其他日志文件)的详细程度。
--explain=logfile
此选项需要文件名参数,会使 bazel build
执行阶段的依赖项检查工具针对每个构建步骤说明执行该构建步骤的原因或最新的构建步骤。说明会写入 logfile。
如果出现意外的重新构建,此选项可帮助您了解原因。将其添加到 .bazelrc
,以便对所有后续构建进行日志记录,然后在看到意外执行步骤时检查日志。此选项可能会造成较小的性能损失,因此当不再需要此选项时,建议您将其移除。
--verbose_explanations
此选项可提高在启用 --explain 选项时生成的说明的详细程度。
特别是,如果启用了详细说明,并且由于用于构建输出文件的命令已更改而重新构建了输出文件,则说明文件中的输出将包含新命令的完整详细信息(至少对大多数命令而言都如此)。
使用此选项可能会显著增加生成的说明文件的长度以及使用 --explain
的性能损失。
如果未启用 --explain
,则 --verbose_explanations
将不起作用。
--profile=file
此选项采用文件名参数,会使 Bazel 将性能分析数据写入文件。然后,您可以使用 bazel analyze-profile
命令分析或解析这些数据。构建配置文件对于了解 Bazel 的 build
命令将时间花在了何处非常有用。
--[no]show_loading_progress
此选项会使 Bazel 输出软件包加载进度消息。如果停用此设置,系统将不会显示消息。
--[no]show_progress
此选项会使系统显示进度消息;默认情况下处于开启状态。停用后,系统将禁止显示进度消息。
--show_progress_rate_limit=n
此选项会使 bazel 每 n
秒最多显示一条进度消息,其中 n 是实数。此选项的默认值为 0.02,这意味着 bazel 会将进度消息限制为每 0.02 秒一条进度消息。
--show_result=n
此选项用于控制 bazel build
命令末尾的结果信息输出。默认情况下,如果指定了单个构建目标,Bazel 会输出一条消息,说明目标是否已成功更新为最新版本;如果是,则会显示目标所创建的输出文件列表。如果指定了多个目标,则不会显示结果信息。
虽然结果信息可能对单个目标或几个目标的 build 非常有用,但对于大型 build(例如整个顶级项目树),此信息可能会非常压抑和分心;通过此选项,您可以对其进行控制。--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 免受 cd
和 exec
调用的影响;请务必复制这些圆括号!)
不过,有些命令是在 Bazel 内部实现的,例如创建符号链接树。对于这些函数,没有可显示的命令行。
可以传递 --subcommands=pretty_print
,以便将命令的参数输出为列表而不是单行。这有助于提高长命令行的可读性。
另请参阅下文的 --verbose_failures。
如需将子命令以适合工具的格式记录到文件中,请参阅 --execution_log_json_file 和 --execution_log_binary_file。
--verbose_failures
此选项会使 Bazel 的执行阶段输出失败的命令的完整命令行。这对于调试失败的构建非常有用。
失败的命令会以与 Bourne shell 兼容的语法输出,适合复制并粘贴到 shell 提示符中。
工作区状态
使用这些选项为由 Bazel 构建的二进制文件“加盖”:向二进制文件中嵌入其他信息,例如源代码控制修订版本或其他与工作区相关的信息。您可以将此机制与支持 stamp
属性的规则(例如 genrule
、cc_binary
等)结合使用。
--workspace_status_command=program
通过此标志,您可以指定 Bazel 在每次构建之前运行的二进制文件。该程序可以报告有关工作区状态的信息,如当前源代码控制修订版本。
该标志的值必须是指向原生程序的路径。在 Linux/macOS 上,这可以是任何可执行文件。在 Windows 上,此文件必须是原生二进制文件,通常为“.exe”“.bat”或“.cmd”文件。
程序应输出零个或多个键值对到标准输出,每行一个条目,然后退出零(否则构建会失败)。键名称可以是任何内容,但只能使用大写字母和下划线。键名后面的第一个空格将键名与值分隔开来。该值是该行的其余部分(包括额外的空格)。键和值都不能跨多行。键不能重复。
Bazel 将密钥划分为两个存储分区:“stable”和“volatile”。(“稳定”和“易失性”这两个名称有点违背常理,因此不用考虑太多。)
然后,Bazel 会将键值对写入两个文件:
bazel-out/stable-status.txt
包含键名以STABLE_
开头的所有键和值bazel-out/volatile-status.txt
包含其余键及其值
合同如下:
如果可能,“稳定”键的值应很少更改。如果
bazel-out/stable-status.txt
的内容发生变化,Bazel 会使依赖于它们的操作失效。换句话说,如果稳定键的值发生变化,Bazel 将重新运行印花操作。因此,稳定状态不应包含时间戳等内容,因为它们随时都会发生变化,并会导致 Bazel 在每次构建时重新运行印花操作。Bazel 始终会输出以下稳定的键:
BUILD_EMBED_LABEL
:值--embed_label
BUILD_HOST
:运行 Bazel 的主机的名称BUILD_USER
:运行 Bazel 的用户的名称
“volatile”键的值可能会经常变化。Bazel 希望它们像时间戳一样始终发生变化,并及时更新
bazel-out/volatile-status.txt
文件。不过,为了避免总是重新运行已标记的操作,Bazel 会假设 volatile 文件从未更改。换言之,如果 volatile 状态文件是唯一内容发生了更改的文件,Bazel 不会使依赖于该文件的操作失效。如果操作的其他输入已更改,则 Bazel 会重新运行该操作,并且该操作会看到更新后的 volatile 状态,但只有 volatile 状态发生变化不会让该操作失效。Bazel 始终会输出以下易失性键:
BUILD_TIMESTAMP
:自 Unix Epoch 以来的构建时间,以秒为单位(System.currentTimeMillis()
的值除以 1000)FORMATTED_DATE
:采用世界协调时间(UTC) 的yyyy MMM d HH mm ss EEE
格式的 build 时间(例如 2023 年 6 月 2 日 44 日 29 日星期五)。
在 Linux/macOS 上,您可以传递 --workspace_status_command=/bin/true
以停用工作区状态检索功能,因为 true
不会执行任何操作,也会成功执行(退出时为零)且不输出任何输出。在 Windows 上,您可以传递 MSYS 的 true.exe
的路径以实现同样的效果。
如果工作区状态命令出于任何原因失败(退出非零值),构建将失败。
在 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 行,而 volatile 状态文件将包含其余行。
--[no]stamp
此选项与 stamp
规则属性结合使用,可控制是否在二进制文件中嵌入 build 信息。
您可以使用 stamp
属性,按规则明确启用或停用印章。如需了解详情,请参阅“Build 百科全书”。当规则设置 stamp = -1
(*_binary
规则的默认值)时,此选项决定了是否启用标记。
无论此选项或 stamp
属性如何,Bazel 绝不会对针对 exec 配置构建的二进制文件进行标记。对于设置了 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 build 设置绑定到较短的名称。如需了解详情,请参阅 Starlark 配置。
--symlink_prefix=string
更改生成的便捷符号链接的前缀。符号链接前缀的默认值为 bazel-
,将创建符号链接 bazel-bin
、bazel-testlogs
和 bazel-genfiles
。
如果由于任何原因无法创建符号链接,系统会发出警告,但 build 仍会被视为成功。具体来说,这允许您在只读目录中或您无权写入的目录中进行构建。build 结束时,信息类消息中输出的任何路径都将仅在符号链接指向预期位置时使用符号链接相对短形式;换言之,即使您不能依赖所创建的符号链接,也可以依赖于这些路径的正确性。
此选项的一些常见值:
禁止创建符号链接:
--symlink_prefix=/
会导致 Bazel 无法创建或更新任何符号链接,包括bazel-out
和bazel-<workspace>
符号链接。使用此选项可完全禁止创建符号链接。减少混乱:
--symlink_prefix=.bazel/
会导致 Bazel 在隐藏目录.bazel
内创建名为bin
等的符号链接。
--platform_suffix=string
为配置简称添加后缀,用于确定输出目录。将此选项设置为不同的值会将文件放在不同的目录中,例如,为了提高会破坏其他输出文件的 build 的缓存命中率,或者保留输出文件以进行比较。
--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
命令 svg
、web
和 list
。
使用 Bazel 进行发布
软件工程师会在开发周期中使用 Bazel,而发布工程师在准备要部署到生产环境的二进制文件时使用 Bazel。本部分提供了一系列使用 Bazel 的发布工程师的提示。
重要选项
使用 Bazel 进行发布 build 时,会出现相同的问题,包括执行构建的其他脚本。如需了解详情,请参阅从脚本调用 Bazel。具体而言,强烈建议使用以下选项:
这些选项也很重要:
--package_path
--symlink_prefix
:如需管理针对多种配置的 build,使用不同标识符(例如“64bit”与“32bit”)区分每个 build 可能会比较方便。此选项可区分bazel-bin
(等)符号链接。
运行测试
如需使用 bazel 构建和运行测试,请输入 bazel test
,后跟测试目标的名称。
默认情况下,此命令会同时执行构建和测试 activity,构建所有指定目标(包括在命令行中指定的任何非测试目标),并在构建前提条件后立即测试 *_test
和 test_suite
目标,这意味着测试作业与构建交错进行。这样做通常可以显著提升速度。
“bazel test
”的选项
--cache_test_results=(yes|no|auto)
(-t
)
如果此选项设置为“自动”(默认设置),则 Bazel 只会在以下任何条件适用时重新运行测试:
- Bazel 检测到测试或其依赖项中的更改
- 该测试被标记为
external
- 使用
--runs_per_test
请求了多次测试运行 - 测试失败。
如果为“no”,将无条件执行所有测试。
如果选择“yes”,则缓存行为将与自动相同,只是它可以缓存测试失败并使用 --runs_per_test
进行测试。
在 .bazelrc
文件中默认启用了此选项的用户可能会发现 -t
(开启)或 -t-
(关闭)缩写很方便来替换特定运行中的默认值。
--check_tests_up_to_date
此选项会告知 Bazel 不要运行测试,而只是检查和报告缓存的测试结果。如果有任何测试之前尚未构建和运行,或者其测试结果已过时(例如,由于源代码或构建选项已更改),则 Bazel 会报告错误消息(“测试结果不是最新”),会将测试的状态记录为“NO STATUS”(如果已启用颜色输出,则为红色),并返回非零代码。
此选项还意味着 --check_up_to_date
行为。
此选项可能对提交前检查很有用。
--test_verbose_timeout_warnings
此选项会告知 Bazel,如果测试的超时远远长于测试的实际执行时间,则向用户明确发出警告。虽然应该对测试的超时进行设置,以确保其不会不稳定,但对于超时设置过于宽松的测试,可能会隐藏意外出现的真实问题。
例如,正常情况下在一两分钟内执行的测试不应超时为 ETERNAL 或 LONG,因为其值过大。
此选项有助于用户确定合适的超时值或对现有超时值进行健全性检查。
--[no]test_keep_going
默认情况下,所有测试都会运行完毕。但是,如果此标志被停用,任何未通过的测试都会中止构建。系统不会运行后续构建步骤和测试调用,并且会取消正在进行的调用。请勿同时指定 --notest_keep_going
和 --keep_going
。
--flaky_test_attempts=attempts
此选项用于指定测试因任何原因而失败时应尝试的最大次数。如果某个测试最初失败但最终成功,则会在测试摘要中报告为 FLAKY
。不过,在确定 Bazel 退出代码或通过测试的总数时,测试会被视为已通过。如果测试未通过所有允许的尝试,将被视为失败。
默认情况下(未指定此选项或此选项设置为默认值时),常规测试只允许进行 1 次尝试,对于设置了 flaky
属性的测试规则,则仅允许进行 3 次尝试。您可以指定整数值来覆盖测试尝试次数上限。为防止系统滥用,Bazel 最多允许进行 10 次测试。
--runs_per_test=[regex@]number
此选项指定每个测试的执行次数。所有测试作业都被视为单独的测试(回退功能将独立应用于每个测试)。
运行失败的目标的状态取决于 --runs_per_test_detects_flakes
标志的值:
- 如果不存在,则任何失败的运行都会导致整个测试失败。
- 如果存在且来自同一分片的两次运行返回 PASS 和 FAIL,测试将收到“不稳定”状态(除非其他失败的运行导致它失败)。
如果指定单个数字,所有测试都将运行这么多次。或者,也可以使用语法 regex@number 指定正则表达式。这会将 --runs_per_test
的效果限制为匹配正则表达式的目标(--runs_per_test=^//pizza:.*@4
会在 //pizza/
下运行所有测试 4 次)。您可以多次指定这种形式的 --runs_per_test
。
--[no]runs_per_test_detects_flakes
如果指定此选项(默认情况下不指定),Bazel 会通过 --runs_per_test
检测不稳定的测试分片。如果单个分片的一次或多次运行失败,并且同一分片通过的一次或多次运行失败,则目标将被视为不稳定,具有该标志。如果未指定,目标将报告失败状态。
--test_summary=output_style
指定测试结果摘要的显示方式。
- 如果测试失败,
short
会输出每个测试的结果,以及包含测试输出的文件的名称。此设置为默认值。 terse
与short
类似,但更小:仅输出有关未通过测试的信息。detailed
会输出失败的每个测试用例,而不仅仅是每个测试。测试输出文件的名称已省略。none
不输出测试摘要。
--test_output=output_style
指定测试输出的显示方式:
summary
会显示每项测试是通过还是失败的摘要。还会显示失败测试的输出日志文件名。摘要将在构建结束时输出(在构建期间,当测试开始、通过或失败时,用户只会看到简单的进度消息)。这是默认行为。errors
仅在测试完成后立即将失败测试的组合 stdout/stderr 输出发送到 stdout,确保同时测试的测试输出不会彼此交错。根据上面的摘要输出,在构建时输出摘要。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
。
请注意,与 bazel run
命令不同,您不能像在 bazel test -- target --logtostderr --v=3
中那样直接传递测试参数。这是因为,传递给 bazel test
的无关参数会被解释为其他测试目标。也就是说,--logtostderr
和 --v=3
都会解读为测试目标。bazel run
命令没有这种歧义,因为命令只接受一个目标。
可以将 --test_arg
传递给 bazel run
命令,但该命令会被忽略,除非正在运行的目标是测试目标。(与任何其他标志一样,如果在 --
令牌之后在 bazel run
命令中传递该标志,Bazel 不会对其进行处理,而是会一字不差地转发到已执行的目标。)
--test_env=variable=_value_
或 --test_env=variable
指定必须为每个测试注入测试环境的其他变量。如果未指定 value,系统将从用于启动 bazel test
命令的 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
类似,不同之处在于该命令用于构建和运行单个目标。以下是一个典型的会话(//java/myapp:myapp
会说“hello”并输出其参数):
% bazel run java/myapp:myapp -- --arg1 --arg2 INFO: Analyzed target //java/myapp:myapp (13 packages loaded, 27 targets configured). INFO: Found 1 target... Target //java/myapp:myapp up-to-date: bazel-bin/java/myapp/myapp INFO: Elapsed time: 14.290s, Critical Path: 5.54s, ... INFO: Build completed successfully, 4 total actions INFO: Running command line: bazel-bin/java/myapp/myapp <args omitted> Hello there $EXEC_ROOT/java/myapp/myapp --arg1 --arg2
bazel run
与直接调用由 Bazel 构建的二进制文件类似但并不完全相同,其行为有所不同,具体取决于要调用的二进制文件是否为测试。
如果二进制文件不是测试,当前工作目录将是二进制文件的 runfiles 树。
当二进制文件是测试时,当前工作目录将是 exec 根目录,并且我们会本着善意的原则尝试复制通常运行测试的环境。不过,模拟并不完美,具有多个分片的测试无法以这种方式运行(可以使用 --test_sharding_strategy=disabled
命令行选项来解决此问题)
以下额外的环境变量也适用于二进制文件:
BUILD_WORKSPACE_DIRECTORY
:运行构建的工作区的根目录。BUILD_WORKING_DIRECTORY
:运行 Bazel 的当前工作目录。
例如,这些文件可用于在命令行上以易于理解的方式解释文件名。
“bazel run
”的选项
--run_under=command-prefix
这与 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 实例执行的所有构建配置的输出目录,或此 Bazel 实例创建的整个工作树的输出目录,并重置内部缓存。如果在没有任何命令行选项的情况下执行,则所有配置的输出目录都将被清理。
回想一下,每个 Bazel 实例都与一个工作区相关联,因此 clean
命令会删除您在该工作区中对该 Bazel 实例完成的所有构建的所有输出。
如需完全移除 Bazel 实例创建的整个工作树,您可以指定 --expunge
选项。使用 --expunge
执行干净命令时,只会移除整个输出基树。除了 build 输出之外,该基树还会包含由 Bazel 创建的所有临时文件。此外,它还会在清理后停止 Bazel 服务器,相当于 shutdown
命令。例如,如需清理 Bazel 实例的所有磁盘和内存跟踪记录,您可以指定:
% bazel clean --expunge
或者,您也可以使用 --expunge_async
在后台清除数据。在异步清除数据继续运行时,您可以放心地在同一客户端中调用 Bazel 命令。
clean
命令主要用作为不再需要的工作区回收磁盘空间的方法。Bazel 的增量重新构建可能不完美,因此出现问题时,可以使用 clean
来恢复一致的状态。
在 Bazel 的设计中,这些问题是可以修复的,因此修复这些 bug 是首要任务。如果您发现错误的增量 build,请提交 bug 报告并在工具中报告 bug,而不要使用 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
命令,您可以在 build 图中查询操作。它在分析后配置的目标图上运行,并公开有关操作、工件及其关系的信息。
该工具接受多个命令行选项。
--output
选择输出格式。默认输出格式 (text
) 为人类可读懂的格式,proto
或 textproto
为机器可读的格式。值得注意的是,aquery 命令在常规 Bazel 构建之上运行,并继承了构建期间可用的一组选项。
它支持的函数集与传统 query
提供的函数集相同,但支持 siblings
、buildfiles
和 tests
。
如需了解详情,请参阅操作图表查询。
其他命令和选项
help
help
命令可提供在线帮助。默认情况下,它会显示可用命令和帮助主题的摘要,如使用 Bazel 构建中所示。指定参数会显示有关特定主题的详细帮助。大多数主题都是 Bazel 命令(例如 build
或 query
),但还有一些其他帮助主题与命令并不对应。
--[no]long
(-l
)
默认情况下,bazel help [topic]
仅输出主题相关选项的摘要。如果指定了 --long
选项,系统还会输出每个选项的类型、默认值和完整说明。
shutdown
您可以使用 shutdown
命令停止 Bazel 服务器进程。此命令会导致 Bazel 服务器在空闲时立即退出(例如,在完成任何构建或当前正在进行的其他命令后)。如需了解详情,请参阅客户端/服务器实现。
Bazel 服务器会在空闲超时后自行停止,因此很少需要运行此命令;不过,如果已知指定工作区中不会再发生任何构建操作,则此命令在脚本中很有用。
shutdown
接受一个选项 --iff_heap_size_greater_than _n_
,该选项需要一个整数参数(以 MB 为单位)。如果指定此参数,则关停操作将以已消耗的内存量为条件。这对于启动大量构建的脚本非常有用,因为 Bazel 服务器中的任何内存泄漏都可能会导致 Bazel 服务器偶尔意外崩溃;执行条件重启会抢占此情况。
info
info
命令会输出与 Bazel 服务器实例或特定 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
构建命令行参数相同。
示例: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 会尝试逐步安装应用,即仅安装自上次构建以来发生了更改的部分。此方法无法更新从 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 服务器内部状态的转储输出到 stdout。此命令主要供 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 签入到 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
命令可分析之前在 Bazel 调用期间收集的 JSON 跟踪配置文件。
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 &
运算符),每个命令使用不同的 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
运行还是从命令行运行),您应使用所有 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
可用于选择明确的 JRE 来运行 Bazel。
--batch
批处理模式会导致 Bazel 不使用标准客户端/服务器模式,而是为单个命令运行 bazel java 进程,该进程已用于信号处理、作业控制和环境变量继承方面更具可预测性的语义,并且在 chroot 监狱中运行 bazel 是必要的。
批处理模式会在同一 output_base 中保留适当的队列语义。 也就是说,并发调用将按顺序处理,不会重叠。如果在运行服务器的客户端上运行批处理模式 Bazel,它会先终止服务器,然后再处理命令。
在批处理模式下或采用上述替代方案时,Bazel 的运行速度会变慢。这是因为,除了其他原因之外,build 文件缓存是内存常驻的,因此它不会在顺序批量调用之间保留。因此,在性能不太重要的情况下(例如持续构建),使用批处理模式通常更有意义。
--max_idle_secs=n
此选项指定 Bazel 服务器进程在上一个客户端请求之后应等待多长时间(以秒为单位)之后才会退出。默认值为 10800(3 小时)。--max_idle_secs=0
将导致 Bazel 服务器进程无限期存在。
调用 Bazel 的脚本可以使用此选项,以确保在用户计算机上不会离开 Bazel 服务器进程,否则这些进程不会留在用户计算机上。例如,提交前脚本可能希望调用 bazel query
,以确保用户的待处理更改不会引入不必要的依赖项。但是,如果用户没有在该工作区中完成最近的构建,则不利于提交前脚本启动 Bazel 服务器,只是为了让该服务器在当天的剩余时间中保持空闲状态。通过在查询请求中指定较小的 --max_idle_secs
值,脚本可以确保在if当它导致新服务器启动时,该服务器将立即退出,但如果已有服务器正在运行,该服务器将继续运行,直到它在通常的空闲时间内处于空闲状态。当然,现有服务器的空闲计时器将会重置。
--[no]shutdown_on_low_sys_mem
如果此政策已启用且 --max_idle_secs
设为正数,在构建服务器空闲一段时间后,当系统内存不足时,会关闭服务器。仅 Linux。
除了运行对应于 max_idle_secs 的空闲检查之外,构建服务器还会在服务器闲置一段时间后开始监控可用的系统内存。如果可用的系统内存严重不足,服务器将退出。
--[no]block_for_lock
启用后,Bazel 会等待其他持有服务器锁的 Bazel 命令完成,然后再执行后续操作。停用后,如果 Bazel 无法立即获取锁并继续处理,则会错误退出。
开发者可以在提交前检查中使用此属性,以避免因同一客户端中的其他 Bazel 命令而导致等待时间过长。
--io_nice_level=n
设置一个 0 到 7 之间的等级,以尽量进行 IO 调度。0 是优先级最高,7 是优先级最低。预期调度程序可能最多只遵循优先级 4。系统会忽略负值。
--batch_cpu_scheduling
为 Bazel 使用 batch
CPU 调度。此政策适用于非交互式工作负载,但不想降低其 good 值。
请参阅“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 生成的每条消息都会添加一个时间戳,用于指定相应消息的显示时间。