Bazel 标志备忘单

浏览 Bazel 的庞大命令行标志列表可能很有挑战性。本页重点介绍您需要了解的最重要的标志。

提示：选择表格中的标志名称可前往命令行参考文档中的相应条目。

实用的常规选项

以下标志应在命令行中明确设置。

标志	说明
--config	您可以将 .bazelrc 文件中的标志整理成配置，例如用于调试或发布 build 的标志。您可以使用 --config=<group> 选择其他配置组。
--keep_going	Bazel 应尽可能尝试继续执行构建和测试。默认情况下，Bazel 会立即失败。
--remote_download_outputs	使用远程执行或缓存（磁盘和远程）时，您可以向 Bazel 发出信号，指明您要下载所有（中间）构建工件，如下所示： --remote_download_outputs=all 默认情况下，Bazel 只会下载顶级工件（例如最终二进制文件）以及本地操作所需的中间工件。
--stamp	向二进制文件添加 build 信息（用户、时间戳）。 注意：由于这会增加构建时间，因此仅适用于发布 build。

发现构建和测试问题

以下标志可帮助您更好地了解 Bazel 构建或测试错误。

标志	说明
--announce_rc	显示通过用户定义、机器定义或项目定义的 .bazelrc 文件隐式设置的标志。
--auto_output_filter	默认情况下，Bazel 会尝试防止日志垃圾，并且仅会针对命令行中请求的软件包和子软件包输出编译器警告和 Starlark 调试输出。如需停用所有过滤功能，请设置 --auto_output_filter=none。
--sandbox_debug	让您深入了解沙盒化错误。如需详细了解 Bazel 为何默认对 build 进行沙盒化处理以及哪些内容会被沙盒化，请参阅我们的沙盒化文档。 提示：如果您认为错误可能是由沙盒化导致的，请尝试暂时关闭沙盒化。 为此，请将 --spawn_strategy=standalone 添加到您的命令中。
--subcommands (-s)	显示 Bazel 在构建期间运行的每个命令的详细列表，无论其是成功还是失败

启动

注意 ：启动标志需要在该命令之前传递，并会导致服务器重启。请谨慎切换这些标志。

标志	说明
--bazelrc	您可以在 .bazelrc 文件中指定默认 Bazel 选项。如果存在多个 .bazelrc 文件，您可以通过添加 --bazelrc=<path to the .bazelrc file> 来选择要使用的 .bazelrc 文件。 提示：--bazelrc=dev/null 会停用对 .bazelrc 文件的搜索。 这非常适合您想要确保干净的构建环境（例如发布 build）并防止 .bazelrc 文件发生任何意外配置更改的情况
--host_jvm_args	限制 Bazel 服务器使用的 RAM 量。 例如，以下命令会将 Bazel 堆大小限制为 3GB： --host_jvm_args=-Xmx3g 注意： -Xmx 用于设置 Java 虚拟机 (JVM) 的堆大小上限。堆是分配对象的内存区域。此选项的正确格式为 -Xmx<size>，其中 <size> 是最大堆大小，使用单位指定，例如： m 表示兆字节 g 表示 GB k 表示千字节
--output_base	控制 Bazel 的输出树。Bazel 不会在源代码树本身中存储构建输出（包括日志）。而是使用一个单独的输出树来实现此目的。 提示：在一个 Bazel 工作区中使用多个输出基础可让您同时运行多个 Bazel 服务器。在尝试避免分析过载时，这可能会很有用。如需了解详情，请参阅选择输出基准。

Bazel 测试

以下标志与 Bazel 测试相关

标志	说明
--java_debug	会导致 Java 测试在执行前等待调试程序连接。
--runs_per_test	运行测试的次数。例如，如需运行测试 N 次，请添加 --runs_per_test=N。这对于调试不稳定的测试和查看修复程序是否会导致测试始终通过非常有用。
--test_filter	在迭代单个测试方法时，此标志特别有用，例如当您所做的更改破坏了测试时。您可以专注于失败的特定测试，而不必重新运行测试套件中的所有测试方法。这样可以更快地获得反馈，并更高效地进行调试。此标志通常与 --test_output=streamed 结合使用，以实现实时测试输出。
--test_output	指定输出模式。默认情况下，Bazel 会在本地日志文件中捕获测试输出。迭代失败的测试时，您通常需要使用 --test_output=streamed 实时查看测试输出。

Bazel run

以下标志与 Bazel 运行相关。

标志	说明
--run_under	更改了调用可执行文件的方式。例如，--run_under="strace -c" 通常用于调试。

用户专用 bazelrc 选项

以下标志与用户专用 .bazelrc 选项相关。

标志	说明
--disk_cache	指向 Bazel 可以读取和写入操作和操作输出的目录的路径。如果目录不存在，系统将会创建目录。 您可以通过向命令中添加 --disk_cache=<path>，在多个分支或工作区之间共享构建工件，并加快 Bazel 构建速度。
--jobs	要运行的并发作业数。 通常，只有在使用远程执行时才需要这样做，因为在这种情况下，远程 build 集群执行的作业数量会超过您本地的核心数量。
--local_resources	限制本地运行的操作所消耗的 CPU 或 RAM 用量。 注意：这不会影响 Bazel 服务器本身为分析和构建编排等任务而消耗的 CPU 或 RAM 量。
--sandbox_base	允许沙盒在此路径下创建沙盒目录。默认情况下，Bazel 会在沙盒中执行本地操作，这会给构建带来一些开销。 提示：如果您的 build 或测试包含许多输入文件，请在 tmpfs 上指定一个路径（例如 /run/shm），以便可能大幅提升性能。

项目专用 bazelrc 选项

以下标志与项目专用 .bazelrc 选项相关。

标志	说明
--flaky_test_attempts	如果任何测试失败，最多可重试指定次数。这对于持续集成特别有用。需要多次尝试才能通过的测试会在测试摘要中标记为FLAKY。
--remote_cache	缓存端点的 URI。设置远程缓存是加快 Bazel 构建速度的绝佳方式。它可以与本地磁盘缓存结合使用。
--remote_download_regex	强制下载路径与此模式匹配的远程 build 输出，无论 --remote_download_outputs 设置如何。您可以通过重复使用此标志来指定多个模式。
--remote_executor	远程执行端点的 HOST 或 HOST:PORT。如果您使用的是远程执行服务，请传递此参数。您通常需要添加 --remote_instance_name=<name>。
--remote_instance_name	要在远程执行 API 中作为 instance_name 传递的值。
--show-timestamps	如果指定，系统会向 Bazel 生成的每条消息添加时间戳，以指明消息显示的时间。这对于 CI 系统非常有用，可让您快速了解哪个步骤花了多长时间。
--spawn_strategy	即使使用远程执行，在本地运行某些构建操作可能更快。这取决于 build 集群的容量、网络速度和网络延迟等因素。 提示：如需同时在本地和远程运行操作并接受更快的结果，请将 --spawn_strategy=dynamic 添加到构建命令。