2022 年 BazelCon 将于 11 月 16 日至 17 日在纽约和线上举办。
立即报名!

编写 bazelrc 配置文件

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Bazel 接受许多选项。某些选项频繁更改(例如 --subcommands),另一些则在多个构建中保持不变(例如 --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 调用的文件就不会失败文件中。

导入优先级:

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

选项默认值

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

  • startup:启动选项,该选项在命令前面,在 bazel help startup_options 中进行了介绍。
  • common:适用于所有 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_failures,而 bazel test //foo 将使用 --verbose_failures -c dbg --test_env=PATH

    继承(特异性)图表:

    • 每个命令都继承自 common
    • 以下命令继承自(并且更具体) buildtestruncleanmobile-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 文件: - 位于 etc/bazel.bazelrc 的系统 rc-文件。 - 位于 $workspace/tools/bazel.rc 的工作区 rc-文件。 - 已本地化为 $HOME/.bazelrc 的 rc 文件

此处列出的每个 Bazelrc 文件都有一个可用于停用的相应标志,例如 --nosystem_rc--noworkspace_rc--nohome_rc。您也可以传递 --ignore_all_rc_files 启动选项,让 Bazel 忽略所有 Bazelrc。