编写 bazelrc 配置文件

报告问题 查看源代码

Bazel 接受许多选项。一些选项经常变化（例如，--subcommands），而另一些选项在多个 build 中保持不变（如 --package_path）。为了避免为每个 build（和其他命令）指定这些未更改的选项，您可以在名为 .bazelrc 的配置文件中指定选项。

.bazelrc 文件在哪里？

Bazel 会按以下顺序在以下位置查找可选的配置文件。这些选项按此顺序进行解释，因此如果发生冲突，后续文件中的选项可以替换先前文件中的值。所有用于控制加载哪些文件的选项都是启动选项，这意味着它们必须位于 bazel 之后、相应命令（build、test 等）之前。

  1. 系统 RC 文件（除非存在 --nosystem_rc）。

    路径：

    • 在 Linux/macOS/Unixes 上：/etc/bazel.bazelrc
    • 在 Windows 上：%ProgramData%\bazel.bazelrc

    如果此文件不存在，则不会报错。

    如果需要其他系统指定的位置，您必须构建自定义 Bazel 二进制文件，并替换 //src/main/cpp:option_processor 中的 BAZEL_SYSTEM_BAZELRC_PATH 值。系统指定的位置可能包含环境变量引用，例如 Unix 的 ${VAR_NAME} 或 Windows 上的 %VAR_NAME%。

  2. 工作区 RC 文件，除非存在 --noworkspace_rc。

    路径：工作区目录中的 .bazelrc（主 WORKSPACE 文件旁边）。

    如果此文件不存在，则不会报错。

  3. 主 RC 文件（除非存在 --nohome_rc）。

    路径：

    • 在 Linux/macOS/Unixes 上：$HOME/.bazelrc
    • 在 Windows 上：%USERPROFILE%\.bazelrc（如果存在），或 %HOME%/.bazelrc

    如果此文件不存在，则不会报错。

  4. 用户指定的 RC 文件（如果使用 --bazelrc=file 指定）

    此标志是可选的，但也可以多次指定。

    /dev/null 表示之后的所有 --bazelrc 都将被忽略，这对于停用用户 rc 文件的搜索非常有用（例如在发布 build 中）。

    例如：

    --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
    • 读取了 x.rc 和 y.rc。
    • 由于先前的 /dev/null，z.rc 被忽略。

除了此可选配置文件之外，Bazel 还会查找全局 rc 文件。如需了解详情，请参阅全局 bazelrc 部分。

.bazelrc 语法和语义

与所有 UNIX“rc”文件一样，.bazelrc 文件是采用基于行的语法的文本文件。空行和以 # 开头的行（注释）会被忽略。每一行都包含一系列单词，这些单词根据与 Bourne shell 相同的规则进行词元化处理。

导入

以 import 或 try-import 开头的行是特殊的代码行：使用这些行加载其他“rc”文件。如需指定相对于工作区根目录的路径，请写入 import %workspace%/path/to/bazelrc。

import 和 try-import 之间的区别在于，如果缺少（或无法读取）由 import 调用的文件，Bazel 会失败；而对于 try-import 的文件，则会失败。

导入优先级：

  • 导入文件中的选项优先于 import 语句之前指定的选项。
  • 在 import 语句后指定的选项优先于导入文件中的选项。
  • 稍后导入的文件中的选项优先于之前导入的文件。

选项默认值

bazelrc 的大多数行都定义了默认选项值。每行的第一个单词指定何时应用这些默认值：

  • startup：启动选项，位于命令之前，详细说明请参见 bazel help startup_options。
  • common：应应用于支持它们的所有 Bazel 命令的选项。如果某个命令不支持以这种方式指定的选项，那么只要它对某个其他 Bazel 命令有效，此选项就会被忽略。 请注意，这仅适用于选项名称：如果当前命令接受具有指定名称的选项，但不支持指定的值，则会失败。
  • always：适用于所有 Bazel 命令的选项。如果命令不支持以这种方式指定的选项，则会失败。
  • command：应用选项的 Bazel 命令，例如 build 或 query。这些选项也适用于从指定命令继承的所有命令。（例如，test 继承自 build。）

这行代码中的每一行都可以多次使用，并且第一个单词后面的参数会被组合起来，就像它们出现在一行中一样。（CVS 是另一个具有“瑞士军刀”命令行界面的工具，它的用户会发现与 .cvsrc 类似的语法。）例如，以下代码行：

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

合并为：

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

因此有效标志是 --verbose_failures 和 --test_tmpdir=/tmp/bar。

选项优先级：

  • 命令行中的选项始终优先于 rc 文件中的选项。例如，如果 rc 文件中显示 build -c opt，但命令行标志为 -c dbg，则命令行标志优先。

  • 在 rc 文件中，优先级受特异性约束：较具体命令的行优先于不太具体的命令行。

    特异性由继承定义。某些命令会继承其他命令的选项，因此继承命令比基本命令更具体。例如，test 继承自 build 命令，因此所有 bazel build 标志对 bazel test 均有效，并且所有 build 行也适用于 bazel test，除非同一选项存在 test 行。如果 rc 文件中显示：

    test -c dbg --test_env=PATH
build -c opt --verbose_failures

    则 bazel build //foo 将使用 -c opt --verbose_failures，bazel test //foo 将使用 --verbose_failures -c dbg --test_env=PATH。

    遗传（特异性）图如下：

    • 每个命令都继承自 common
    • 以下命令继承自 build（而且比 build 更具体）：test、run、clean、mobile-install、info、print_action、config、cquery 和 aquery
    • coverage 继承自 test

  • 有两行指定相同特异性同一命令的选项，会按它们在文件中出现的顺序进行解析。

  • 由于此优先规则与文件顺序不匹配，因此如果您遵循 rc 文件中的优先顺序，将有助于提高可读性：在顶部以 common 选项开头，在文件底部以最具体的命令结束。这样，读取选项的顺序与应用选项的顺序相同，因而更直观。

在 rc 文件的行中指定的参数可能包含并非选项的参数，例如构建目标的名称等。与相同文件中指定的选项一样，这些选项的优先级低于命令行上的同级项，并且始终附加到非选项参数的明确列表中。

--config

除了设置选项默认值之外，rc 文件还可用于对选项进行分组，并为常用分组提供简写形式。可以通过向命令中添加 :name 后缀来实现这一点。这些选项默认被忽略，但当 --config=name 选项存在于命令行或 .bazelrc 文件中时（以递归方式存在，甚至在另一个配置定义中时），也会包含这些选项。系统仅会按上述优先顺序针对适用命令扩展 command:name 指定的选项。

--config=foo 会“就地”扩展为 rc 文件中定义的选项，以便为配置指定的选项的优先级与 --config=foo 选项相同。

此语法不会扩展到使用 startup 设置启动选项。系统会忽略 .bazelrc 中的 startup:config-name --some_startup_option 设置。

--enable_platform_specific_config

您可以使用 --enable_platform_specific_config 自动启用 .bazelrc 中的平台专用配置。例如，如果主机操作系统是 Linux 并运行 build 命令，则 build:linux 配置将自动启用。支持的操作系统标识符包括 linux、macos、windows、freebsd 和 openbsd。启用此标志等同于在 Linux 上使用 --config=linux，在 Windows 上使用 --config=windows，依此类推。

请参阅 --enable_platform_specific_config。

示例

以下是一个示例 ~/.bazelrc 文件：

# Bob's Bazel option defaults

startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

控制 Bazel 行为的其他文件

.bazelignore

您可以在工作区中指定希望 Bazel 忽略的目录，例如使用其他构建系统的相关项目。将名为 .bazelignore 的文件放在工作区的根目录中，然后添加您希望 Bazel 忽略的目录，每行一个。条目相对于工作区根目录。

全局 bazelrc 文件

Bazel 会按以下顺序读取可选的 bazelrc 文件：

  1. 位于 etc/bazel.bazelrc 的系统 rc 文件。
  2. 工作区 rc 文件，位于 $workspace/tools/bazel.rc。
  3. 主页 rc 文件位于 $HOME/.bazelrc

此处列出的每个 bazelrc 文件都有一个相应的标志，可用于停用它们（例如 --nosystem_rc、--noworkspace_rc、--nohome_rc）。您还可以通过传递 --ignore_all_rc_files 启动选项，让 Bazel 忽略所有 bazelrcs。