操作
在 build 期间运行的命令,例如,对以 制品为输入并生成其他制品作为输出的编译器进行的调用。 包括命令行实参、操作键、环境变量和声明的输入/输出制品等元数据。
另请参阅: 规则文档
操作缓存
一种磁盘缓存,用于存储已执行的操作与其创建的输出之间的映射。缓存键称为操作键。Bazel 增量模型的核心组件。缓存存储在输出基本目录中,因此在 Bazel 服务器重启后仍会保留。
动作图
一个内存图,其中包含操作以及这些操作读取和生成的制品。该图可能包含以源文件形式(例如在文件系统中)存在的制品,以及未在 BUILD 文件中提及的生成的中间/最终制品。在分析阶段生成,在执行阶段使用。
操作图查询 (aquery)
一种可查询 build 操作的查询工具。 这样一来,您就可以分析构建规则如何转化为实际的构建工作。
快捷操作按键
操作的缓存键。根据操作元数据计算得出,可能包括要在操作中执行的命令、编译器标志、库位置或系统头(具体取决于操作)。使 Bazel 能够确定性地缓存或使单个操作失效。
分析阶段
构建的第二阶段。处理 BUILD 文件中指定的目标图,以生成内存中的操作图,该图确定在执行阶段要运行的操作顺序。在此阶段,系统会评估规则实现。
制品
源文件或生成的文件。也可以是文件目录,称为树状制品。
一个制品可以作为多个操作的输入,但最多只能由一个操作生成。
与文件目标对应的制品可通过标签寻址。
方面
一种机制,用于让规则在其依赖项中创建额外的操作。例如,如果目标 A 依赖于 B,则可以在 A 上应用一个遍历依赖项边(从 A 到 B)的方面,并在 B 中运行其他操作来生成和收集其他输出文件。这些额外操作会被缓存,并在需要相同宽高比的目标之间重复使用。使用 aspect() Starlark Build API 函数创建。例如,可用于为 IDE 生成元数据,以及创建用于执行 Lint 的操作。
另请参阅: 方面文档
方面到方面
一种组合机制,通过该机制,可以将方面应用于其他方面的结果。例如,生成供 IDE 使用的信息的方面可以应用于从 proto 生成 .java 文件的方面之上。
为了使方面 A 应用于方面 B 之上,B 在其 provides 属性中宣传的 提供程序必须与 A 在其 required_aspect_providers 属性中声明的所需提供程序相匹配。
属性
规则的形参,用于表示每个目标 build 信息。
例如,srcs、deps 和 copts 分别用于声明目标的源文件、依赖项和自定义编译器选项。特定目标可用的属性取决于其规则类型。
.bazelrc
Bazel 的配置文件,用于更改启动标志和命令标志的默认值,以及定义可使用 --config 标志在 Bazel 命令行中一起设置的常见选项组。Bazel 可以合并来自多个 bazelrc 文件(系统级、工作区级、用户级或来自自定义位置)的设置,并且 bazelrc 文件还可以从其他 bazelrc 文件导入设置。
Blaze
Google 内部版本的 Bazel。Google 用于其单体代码库的主要构建系统。
BUILD 文件
BUILD 文件是主要配置文件,用于告知 Bazel 要构建哪些软件输出、这些输出的依赖项是什么以及如何构建它们。Bazel 会将 BUILD 文件作为输入,并使用该文件创建依赖关系图,以及推导必须完成的操作,以构建中间和最终软件输出。BUILD 文件会将目录和任何不包含 BUILD 文件的子目录标记为软件包,并且可以包含由规则创建的目标。该文件也可以命名为 BUILD.bazel。
BUILD.bazel 文件
请参阅BUILD 文件。优先于同一目录中的 BUILD 文件。
.bzl 文件
一种文件,用于定义以 Starlark 编写的规则、宏和常量。然后,可以使用 load() 函数将这些文件导入到 BUILD 文件中。
构建图表
Bazel 构建并遍历以执行构建的依赖关系图。包括目标、配置的目标、操作和制品等节点。当一组请求的目标所依赖的所有 制品都经过验证为最新状态时,即表示 build 已完成。
build 设置
Starlark 定义的配置。过渡可以设置 build 设置来更改子图的配置。如果作为命令行标志(也称为 build 标志)向用户公开。
干净 build
不使用之前构建的结果的构建。这通常比增量 build 慢,但通常被认为更正确。Bazel 可保证整洁 build 和增量 build 始终正确无误。
客户端-服务器模型
bazel 命令行客户端会自动在本地机器上启动一个后台服务器,以执行 Bazel 命令。服务器在命令之间保持运行,但在一段时间不活动后会自动停止(或通过 bazel 关闭命令显式停止)。将 Bazel 拆分为服务器和客户端有助于分摊 JVM 启动时间,并支持更快的增量构建,因为操作图在命令之间会保留在内存中。
命令
在命令行中使用,用于调用不同的 Bazel 函数,例如 bazel
build、bazel test、bazel run 和 bazel query。
命令标志
一组特定于命令的标志。命令标志指定在命令 (bazel build <command flags>) 之后。标志可适用于一个或多个命令。例如,--configure 是 bazel sync 命令专用的标志,但 --keep_going 适用于 sync、build、test 等。标志通常用于配置目的,因此标志值的更改可能会导致 Bazel 使内存中的图失效并重新启动分析阶段。
配置
规则定义之外的信息,会影响规则生成操作的方式。每个 build 至少有一个配置,用于指定目标平台、操作环境变量和命令行 build 标志。过渡可能会创建额外的配置,例如用于宿主工具或交叉编译的配置。
另请参阅: 配置
配置精简
仅包含目标实际需要的配置的过程。例如,如果您使用 C++ 依赖项 //:c 构建 Java 二进制文件 //:j,那么在 //:c 的配置中包含 --javacopt 的值是浪费的,因为更改 --javacopt 会不必要地破坏 C++ 构建缓存能力。
已配置的查询 (cquery)
一种查询工具,用于查询已配置的目标(在分析阶段完成后)。这意味着 select() 和 build 标志(例如 --platforms)会准确反映在结果中。
另请参阅: cquery 文档
配置的目标
使用配置评估目标的结果。分析阶段通过将 build 的选项与需要构建的目标相结合来生成此文件。例如,如果 //:foo 在同一 build 中为两种不同的架构构建,则它具有两个已配置的目标:<//:foo, x86> 和 <//:foo, arm>。
正确性
如果 build 的输出忠实地反映了其传递输入的状况,则该 build 是正确的。为了实现正确的 build,Bazel 努力做到封闭、可重现,并使build 分析和操作执行具有确定性。
依赖项
两个目标之间的有向边。如果目标 //:foo 的属性值包含对目标 //:bar 的引用,则目标 //:foo 对目标 //:bar 具有目标依赖关系。如果 //:foo 中的某项操作依赖于 //:bar 中的某项操作创建的输入制品,则 //:foo 对 //:bar 具有操作依赖项。
在某些情况下,它也可能指外部依赖项;请参阅模块。
Depset
用于收集有关传递依赖项的数据的数据结构。经过优化,合并 depsets 在时间和空间上都很高效,因为通常会有非常大的 depsets(数十万个文件)。实现为以递归方式引用其他依赖项集,以提高空间效率。除非规则位于 build 图的顶层,否则规则实现不应通过将 depsets 转换为列表来“扁平化”它们。扁平化大型 depset 会导致内存消耗巨大。在 Bazel 的内部实现中也称为嵌套集。
另请参阅: Depset 文档
磁盘缓存
用于远程缓存功能的本地磁盘上 blob 存储区。可与实际的远程 blob 存储区结合使用。
distdir
一个只读目录,其中包含 Bazel 否则会使用代码库规则从互联网上提取的文件。使 build 能够完全离线运行。
动态执行
一种执行策略,可根据各种启发式方法在本地执行和远程执行之间进行选择,并使用较快成功方法的执行结果。某些操作在本地执行速度更快(例如关联),而其他操作在远程执行速度更快(例如高度并行化的编译)。动态执行策略可以提供尽可能最佳的增量和干净的 build 时间。
执行阶段
构建的第三个阶段。执行在分析阶段创建的操作图中的操作。这些操作会调用可执行文件(编译器、脚本)来读取和写入制品。派生策略用于控制这些操作的执行方式:本地、远程、动态、沙盒、Docker 等。
执行根
工作区的输出库目录中的一个目录,用于在非沙盒构建中执行本地操作。目录内容大多是工作区中输入制品的符号链接。执行根目录还包含指向外部代码库的符号链接(作为其他输入)以及用于存储输出的 bazel-out 目录。在加载阶段准备,方法是创建目录的符号链接森林,这些目录表示 build 所依赖的软件包的传递闭包。可通过命令行中的 bazel info
execution_root 访问。
文件
请参阅制品。
Hermeticity
如果构建和测试操作不受任何外部因素影响,则该构建是密封的,这有助于确保结果是确定性的且正确的。例如,封闭式 build 通常会禁止操作访问网络、限制对已声明输入的访问、使用固定的时间戳和时区、限制对环境变量的访问,以及使用固定的随机数生成器种子
增量 build
增量 build 会重复使用之前 build 的结果,以缩短 build 时间并减少资源用量。依赖项检查和缓存旨在为此类 build 生成正确的结果。增量 build 与 clean build 相反。
标签
目标的标识符。通常采用 @repo//path/to/package:target 形式,其中 repo 是包含目标的代码库的(显式)名称,path/to/package 是包含声明目标的 BUILD 文件的目录的路径(此目录也称为软件包),而 target 是目标本身的名称。根据具体情况,此语法的某些部分可能会被省略。
另请参阅:标签
加载阶段
构建的第一阶段,在此阶段,Bazel 会执行 BUILD 文件以创建软件包。在此阶段,系统会评估宏和某些函数(例如 glob())。与构建的第二阶段(即分析阶段)交织在一起,以构建目标图。
宏
一种用于在单个 Starlark 函数下将多个 rule 目标声明组合在一起的机制。支持在多个 BUILD 文件中重复使用通用规则声明模式。在加载阶段扩展为底层规则目标声明。
另请参阅: 宏文档
助记符
规则作者选择的简短且直观易懂的字符串,用于快速了解规则中操作的作用。助记符可用作派生策略选择的标识符。操作助记符的一些示例包括 Java 规则中的 Javac、C++ 规则中的 CppCompile 和 Android 规则中的 AndroidManifestMerger。
模块
一个可以有多个版本的 Bazel 项目,每个版本都可以依赖于其他模块。这类似于其他依赖项管理系统中的熟悉概念,例如 Maven 工件、npm 软件包、Go 模块或 Cargo 箱。模块是 Bazel 外部依赖项管理系统的核心。
每个模块都由一个 repo 提供支持,该 repo 的根目录中包含一个 MODULE.bazel 文件。此文件包含有关模块本身的元数据(例如其名称和版本)、其直接依赖项以及各种其他数据,包括工具链注册和模块扩展输入。
模块元数据托管在 Bazel 注册表中。
另请参阅: Bazel 模块
模块扩展
一种逻辑,可通过读取整个模块依赖关系图中的输入并调用仓库规则来运行,以生成仓库。模块扩展程序具有与代码库规则类似的功能,允许它们访问互联网、执行文件 I/O 等操作。
另请参阅: 模块扩展程序
原生规则
内置到 Bazel 中并以 Java 实现的规则。此类规则在 .bzl 文件中显示为原生模块中的函数(例如 native.cc_library 或 native.java_library)。用户定义的规则(非原生)是使用 Starlark 创建的。
输出基础
用于存储 Bazel 输出文件的特定于工作区的目录。用于将输出与工作区的源代码树(即主代码库)分开。位于输出用户根目录中。
输出组
一组文件,当 Bazel 完成目标构建时,这些文件应会被构建。规则将其常规输出放入“默认输出组”(例如,java_library、.a 和 .so 的 .jar 文件,适用于 cc_library 目标)。默认输出组是指在命令行中请求目标时构建其制品的输出组。规则可以定义更多可在 BUILD 文件(filegroup 规则)或命令行(--output_groups 标志)中明确指定的命名输出组。
输出用户 root
用于存储 Bazel 输出的用户专用目录。目录名称派生自用户的系统用户名。如果多个用户同时在系统上构建同一项目,可防止输出文件发生冲突。 包含与各个工作区的 build 输出对应的子目录,也称为输出库。
软件包
由 BUILD 文件定义的一组目标。软件包的名称是 BUILD 文件相对于 repo 根目录的路径。一个软件包可以包含子软件包或包含 BUILD 文件的子目录,从而形成软件包层次结构。
软件包组
表示一组软件包的目标。通常用于 visibility 属性值中。
平台
build 中涉及的“机器类型”。这包括运行 Bazel 的机器(“宿主”平台)、执行构建工具的机器(“执行”平台)以及构建目标所面向的机器(“目标平台”)。
提供商
一种用于描述在规则目标之间沿依赖关系传递的信息单元的架构。它通常包含编译器选项、传递性源文件或输出文件以及 build 元数据等信息。经常与 depset 结合使用,以高效存储累积的传递数据。内置提供程序的示例是 DefaultInfo。
另请参阅: 提供程序文档
查询(概念)
分析构建图以了解目标属性和依赖项结构的过程。Bazel 支持三种查询变体:query、cquery 和 aquery。
查询(命令)
一种在 build 的后加载阶段 目标图上运行的查询工具。这种方式相对较快,但无法分析 select()、build 标志、制品或 build 操作的效果。
代码库
根目录中包含边界标记文件的目录树,其中包含可在 Bazel build 中使用的源文件。通常简称为 repo。
库边界标记文件可以是 MODULE.bazel(表示相应库是 Bazel 模块)、REPO.bazel,或者在旧版环境中可以是 WORKSPACE 或 WORKSPACE.bazel。任何代码库边界标记文件都将表示代码库的边界;一个目录中可以同时存在多个此类文件。
主代码库是指当前 Bazel 命令正在运行的代码库。
外部代码库通过在 MODULE.bazel 文件中指定模块或在模块扩展程序中调用代码库规则来定义。它们可以按需提取到磁盘上预定的“神奇”位置。
每个代码库都有一个唯一的常量规范名称,并且从其他代码库查看时可能会有不同的表观名称。
另请参阅:外部依赖项概览
代码库缓存
由 Bazel 下载的用于构建的文件(可跨工作区共享)的共享内容可寻址缓存。在初始下载后启用离线 build。通常用于缓存通过存储库规则(如 http_archive)和存储库规则 API(如 repository_ctx.download)下载的文件。仅当为下载指定了文件的 SHA-256 校验和时,文件才会缓存。
代码库规则
用于存储库定义的架构,用于告知 Bazel 如何实现(或“提取”)存储库。通常简称为 repo 规则。
Repo 规则由 Bazel 在内部调用,用于定义由模块支持的 repo,也可以由模块扩展程序调用。Repo 规则可以访问互联网或执行文件 I/O;最常见的 repo 规则是 http_archive,用于从互联网下载包含源文件的归档。
另请参阅: 代码库规则文档
可再现性
一种构建或测试属性,指无论时间、方法或环境如何,一组构建或测试输入始终会生成相同的一组输出。请注意,这并不一定意味着输出是正确的或所需的输出。
规则
用于在 BUILD 文件(例如 cc_library)中定义规则目标的架构。从 BUILD 文件作者的角度来看,规则由一组属性和黑盒逻辑组成。该逻辑会告知规则目标如何生成输出制品并将信息传递给其他规则目标。从 .bzl 作者的角度来看,规则是扩展 Bazel 以支持新的编程语言和环境的主要方式。
规则在加载阶段实例化,以生成规则目标。在分析阶段,规则目标会以提供程序的形式向其下游依赖项传递信息,并注册描述如何生成其输出制品的操作。这些操作在执行阶段运行。
另请参阅: 规则文档
规则目标
作为规则实例的目标。与文件目标和软件包组形成对比。请勿与规则混淆。
Runfiles
可执行目标的运行时依赖项。最常见的情况是,可执行文件是测试规则的可执行输出,而 runfile 是测试的运行时数据依赖项。在调用可执行文件之前(在 bazel 测试期间),Bazel 会根据运行文件的源目录结构,在测试可执行文件旁边准备运行文件树。
另请参阅: Runfiles 文档
沙盒
一种用于在受限的临时执行根中隔离正在运行的操作的技术,有助于确保该操作不会读取未声明的输入或写入未声明的输出。沙盒化可大幅提升封闭性,但通常会牺牲性能,并且需要操作系统提供支持。性能开销取决于平台。在 Linux 上,这并不重要,但在 macOS 上,这可能会导致沙盒无法使用。
Skyframe
Skyframe 是 Bazel 的核心并行、功能性和增量评估框架。
冲压
用于将其他信息嵌入到 Bazel 构建的制品中。例如,这可用于发布 build 的源代码控制、build 时间以及其他工作区或环境相关信息。通过 --workspace_status_command 标志和支持邮票属性的规则启用。
Starlark
用于编写规则和宏的扩展语言。一种受限的 Python 子集(在语法和文法上),旨在用于配置,并实现更好的性能。使用 .bzl 文件扩展名。BUILD 文件使用更受限的 Starlark 版本(例如没有 def 函数定义),以前称为 Skylark。
另请参阅: Starlark 语言文档
启动标志
bazel 和命令之间指定的一组标志,例如 bazel --host_jvm_debug build。这些标志会修改 Bazel 服务器的配置,因此对启动标志的任何修改都会导致服务器重启。启动标志不特定于任何命令。
目标
在 BUILD 文件中定义并由标签标识的对象。从最终用户的角度来看,target 表示工作区的可构建单元。
通过实例化规则声明的目标称为规则目标。根据规则的不同,这些目标可能可运行(如 cc_binary)或可测试(如 cc_test)。规则目标通常通过其属性(如 deps)依赖于其他目标;这些依赖关系构成了目标图的基础。
除了规则目标之外,还有文件目标和软件包组目标。文件目标对应于 BUILD 文件中引用的制品。作为一种特殊情况,任何软件包的 BUILD 文件始终被视为该软件包中的源文件目标。
目标是在加载阶段发现的。在分析阶段,目标会与build 配置相关联,从而形成配置的目标。
目标图
目标及其依赖项的内存中图。在加载阶段生成,并用作分析阶段的输入。
目标模式
在命令行中指定一组目标的方法。常用的模式包括 :all(所有规则目标)、:*(所有规则目标和文件目标)、...(当前软件包和所有子软件包 [递归])。可以组合使用,例如 //...:* 表示从工作区的根目录开始,递归地查找所有软件包中的所有规则和文件目标。
测试
从测试规则实例化的规则目标,因此包含测试可执行文件。可执行文件完成时返回代码为零,表示测试成功。Bazel 与测试之间的确切合约(例如测试环境变量、测试结果收集方法)在测试百科全书中指定。
工具链
用于为某种语言构建输出的一组工具。通常,工具链包括编译器、链接器、解释器和/或代码检查器。工具链也可能因平台而异,也就是说,即使工具链是针对同一种语言的,Unix 编译器工具链的组件也可能与 Windows 变体不同。为平台选择合适的工具链称为工具链解析。
顶级目标
如果构建目标是在 Bazel 命令行中请求的,则该目标为顶级目标。例如,如果 //:foo 依赖于 //:bar,并且调用了 bazel build //:foo,那么对于此 build,//:foo 是顶级目标,而 //:bar 不是顶级目标,尽管这两个目标都需要构建。顶级目标与非顶级目标之间的一个重要区别是,在 Bazel 命令行中(或通过 .bazelrc)设置的命令标志将为顶级目标设置配置,但可能会被非顶级目标的转换修改。
过渡
从一个值到另一个值的配置状态的映射。 使build 图中的目标具有不同的配置,即使它们是从同一规则实例化的也是如此。过渡的常见用法是使用拆分过渡,其中目标图的某些部分会分叉,每个分叉都有不同的配置。例如,您可以在一次构建中,使用拆分过渡来构建包含针对 ARM 和 x86 编译的原生二进制文件的 Android APK。
另请参阅: 用户定义的过渡
树状制品
表示文件集合的制品。由于这些文件本身不是制品,因此对它们进行操作的 action 必须改为将树形制品注册为输入或输出。
公开范围
用于防止 build 系统中出现不必要依赖项的两种机制之一:目标可见性,用于控制其他目标是否可以依赖某个目标;以及加载可见性,用于控制 BUILD 或 .bzl 文件是否可以加载给定的 .bzl 文件。在没有上下文的情况下,“可见性”通常是指目标可见性。
另请参阅: 可见性文档
工作区
从同一主代码库运行的所有 Bazel 命令共享的环境。
请注意,从历史上看,“代码库”和“工作区”的概念一直混为一谈;“工作区”一词通常用于指代主代码库,有时甚至用作“代码库”的同义词。为清楚起见,应避免使用此类用法。