Bazel 接受许多选项。有些选项会经常变化(例如,
--subcommands
),而其他 build 在多个 build 中保持不变(例如
--package_path
)。为了避免为每个 build 指定这些未更改的选项
(以及其他命令),您可以在名为
.bazelrc
。
.bazelrc
文件在哪里?
Bazel 会在以下位置查找可选的配置文件
按下面所示的顺序排列。这些选项将按此顺序进行解释
如果
将引发冲突。用于控制加载上述哪些文件的所有选项
启动选项,这意味着它们必须在 bazel
和
命令之前(build
、test
等)。
系统 RC 文件(除非存在
--nosystem_rc
)。路径:
- 在 Linux/macOS/Unixes 上:
/etc/bazel.bazelrc
- 在 Windows 上:
%ProgramData%\bazel.bazelrc
如果此文件不存在,也不会发生错误。
如果需要其他系统指定的位置,您必须构建自定义 Bazel 二进制文件,替换
BAZEL_SYSTEM_BAZELRC_PATH
//src/main/cpp:option_processor
。 系统指定的位置可能包含环境变量引用, 例如 Unix 上的${VAR_NAME}
或 Windows 上的%VAR_NAME%
。- 在 Linux/macOS/Unixes 上:
工作区 RC 文件,除非存在
--noworkspace_rc
。路径:工作区目录中的
.bazelrc
(在主工作区旁边)WORKSPACE
文件)。如果此文件不存在,也不会发生错误。
主 RC 文件(除非存在
--nohome_rc
)。路径:
- 在 Linux/macOS/Unixes 上:
$HOME/.bazelrc
- 在 Windows 上:
%USERPROFILE%\.bazelrc
(如果存在)或%HOME%/.bazelrc
如果此文件不存在,也不会发生错误。
- 在 Linux/macOS/Unixes 上:
用户指定的 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
引用的文件(或无法读取),但对于 try-import
调用
文件。
导入优先级:
- 导入文件中的选项优先于之前指定的选项 import 语句。
- 在 import 语句后指定的选项优先于 选项。
- 稍后导入的文件中的选项优先于先前导入的文件。
选项默认值
bazelrc 的大多数行都会定义默认选项值。每个单词的第一个单词 行指定了应用这些默认值的时间:
startup
:启动选项,位于命令之前,描述 在bazel help startup_options
中。common
:适用于所有 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
,但命令行 flag 为-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
:test
、run
、clean
、mobile-install
、info
、print_action
、config
、cquery
和aquery
coverage
继承自test
- 每个命令均继承自
以下两行分别为每个命令指定了相同特异性的选项: 会按照它们在文件中的出现顺序进行解析。
由于此优先规则与文件顺序不匹配
common
选项位于顶部,并以最具体的命令(位于 文件底部这样,选项的读取顺序就是 与它们的应用顺序相同,这更直观。
在 rc 文件的某一行指定的参数可能包含 而非选项,例如构建目标的名称等例如 选项,其优先级低于其同级项 并且始终附加到非 option 参数。
--config
除了设置选项默认值之外,rc 文件还可用于对选项进行分组
并提供常用分组的简写形式。为此,需要添加一个 :name
为命令添加后缀。默认情况下,这些选项会被忽略,但会被
如果存在 --config=name
选项,则会包含该标头。
以递归方式在命令行或 .bazelrc
文件中运行,甚至可以在
另一个配置定义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 文件。
- 首页 rc 文件,本地化为 $HOME/.bazelrc
此处列出的每个 bazelrc 文件都有一个可用于停用它们的相应标志(例如 --nosystem_rc
、--noworkspace_rc
、--nohome_rc
)。您也可以传递 --ignore_all_rc_files
启动选项,让 Bazel 忽略所有 bazelrcs。