编写 bazelrc 配置文件

报告问题 查看源代码

Bazel 接受许多选项。有些选项会经常变化(例如 --subcommands),而有些选项则会在多个 build(例如 --package_path)之间保持不变。为了避免为每个 build(以及其他命令)指定这些未更改的选项,您可以在一个名为 .bazelrc 的配置文件中指定选项。

.bazelrc 文件在哪里?

Bazel 会按以下顺序在以下位置查找可选的配置文件,这些选项会按照此顺序进行解释,因此如果后续文件出现了冲突,后续文件中的选项可能会替换早期文件中的值。用于控制加载哪些文件的所有选项都是启动选项,这意味着它们必须出现在 bazel 之后和命令之前(buildtest 等)。

  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.rcy.rc
    • 由于之前的 /dev/nullz.rc 会被忽略。

除了这个可选的配置文件之外,Bazel 还会查找一个全局 rc 文件。如需了解详情,请参阅全局 Bazelrc 部分

.bazelrc 语法和语义

与所有 UNIX“rc”文件一样,.bazelrc 文件是采用基于行的语法的文本文件。空行和以 # 开头的注释(注释)将被忽略。每行包含一系列字词,它们按照与 Bourne shell 相同的规则进行词元化处理。

导入

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

importtry-import 之间的区别在于,如果 import 的文件缺失(或无法读取),Bazel 会失败;但对于 try-import 的文件,则不会如此。

导入优先级:

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

选项默认值

Bazelrc 的大多数行都定义默认选项值。每行的第一个单词指定应用这些默认值的时间:

  • startup:启动选项,位于命令之前,在 bazel help startup_options 中描述。
  • common:应该应用于支持这些操作的所有 Bazel 命令的选项。如果某个命令不支持以这种方式指定的选项,系统会忽略该选项,只要它对某些其他 Bazel 命令有效即可。请注意,这仅适用于选项名称:如果当前命令接受具有指定名称的选项,但不支持指定的值,则该命令会失败。
  • always:适用于所有 Bazel 命令的选项。如果某个命令不支持以这种方式指定的选项,该命令将会失败。
  • command:应用选项的 Bazel 命令,例如 buildquery。这些选项也适用于从指定命令继承的所有命令。(例如,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_failuresbazel test //foo 将使用 --verbose_failures -c dbg --test_env=PATH

    继承(特异性)图表如下:

    • 每个命令继承自 common
    • 以下命令继承自 build(比后者更具体):testruncleanmobile-installinfoprint_actionconfigcqueryaquery
    • coverage 继承自 test
  • 为同一命令指定两个选项(具有相同优先级)时,系统会解析这两个行在文件中的显示顺序。

  • 由于此优先级规则与文件顺序不符,因此如果您遵循 rc 文件中的优先顺序,这有助于提高可读性:以顶部 common 选项开头,以文件底部最具体的命令结尾。这样,选项的读取顺序与其应用顺序相同,更为直观。

在 rc 文件行中指定的参数可以包括非选项参数,例如构建目标的名称等。与同一文件中指定的选项一样,它们的优先级也比命令行中同级要低,并且始终会附加到非选项参数的显式列表之前。

--config

除了设置选项默认设置外,rc 文件还可用于对选项进行分组,并提供常用分组的简写形式。为此,您可以在命令中添加 :name 后缀。默认情况下,这些选项会被忽略,但当包含在命令行中或 .bazelrc 文件中,选项以递归方式包含在 --config=name 中时,即使在另一个配置定义内也是如此。command:name 指定的选项将仅针对上述命令展开,且采用上述优先顺序。

--config=foo 将扩展为 rc 文件“就地”定义的选项,这样为配置指定的选项的优先级就与 --config=foo 选项相同。

此语法并未扩展到使用 startup 来设置启动选项的情况。.bazelrc 中的 startup:config-name --some_startup_option 设置将被忽略。

示例

以下是一个示例 ~/.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. 系统 rc-file,位于 etc/bazel.bazelrc
  2. 位于 $workspace/tools/bazel.rc 的 Workspace rc 文件。
  3. 主目录文件位于 $HOME/.bazelrc

此处列出的每个 bazelrc 文件都有一个对应的标志,可用于停用这些标志(例如 --nosystem_rc--noworkspace_rc--nohome_rc)。您还可以通过传递 --ignore_all_rc_files 启动选项让 Bazel 忽略所有 Bazelrcs。