Bazel 术语表

报告问题 查看来源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

操作

在 build 期间运行的命令,例如,对以 制品为输入并生成其他制品作为输出的编译器的调用。 包括命令行实参、操作键、环境变量和声明的输入/输出制品等元数据。

另请参阅规则文档

操作缓存

一种磁盘缓存,用于存储已执行的操作与其创建的输出之间的映射。缓存键称为“操作键”。Bazel 增量模型的核心组件。缓存存储在输出基本目录中,因此在 Bazel 服务器重启后仍会保留。

动作图

一个内存图,其中包含操作以及这些操作读取和生成的制品。该图可能包含以源文件形式(例如在文件系统中)存在的制品,以及未在 BUILD 文件中提及的生成的中间/最终制品。在分析阶段生成,在执行阶段使用。

操作图查询 (aquery)

一种可查询 build 操作查询工具。 这样,您就可以分析构建规则如何转化为实际的构建工作。

快捷操作按键

操作的缓存键。根据操作元数据计算得出,可能包括要在操作中执行的命令、编译器标志、库位置或系统标头,具体取决于操作。使 Bazel 能够确定性地缓存或使各个操作失效。

分析阶段

构建的第二阶段。处理 BUILD 文件中指定的目标图,以生成内存中的操作图,该图确定在执行阶段运行操作的顺序。在此阶段,系统会评估规则的实现情况。

制品

源文件或生成的文件。也可以是文件目录,称为树状制品

一个制品可以作为多个操作的输入,但最多只能由一个操作生成。

文件目标对应的制品可通过标签寻址。

方面

一种机制,用于让规则在其依赖项中创建额外的操作。例如,如果目标 A 依赖于 B,则可以在 A 上应用一个方面,该方面会向上遍历依赖项边缘到达 B,并在 B 中运行其他操作以生成和收集其他输出文件。这些额外操作会被缓存,并在需要相同宽高比的目标之间重复使用。使用 aspect() Starlark Build API 函数创建。例如,可用于为 IDE 生成元数据,以及创建用于执行 Lint 的操作。

另请参阅方面文档

方面到方面

一种组合机制,通过该机制,可以将方面应用于其他方面的结果。例如,生成供 IDE 使用的信息的方面可以应用于从 proto 生成 .java 文件的方面之上。

为了使方面 A 应用于方面 B 之上,B 在其 provides 属性中宣传的提供程序必须与 A 在其 required_aspect_providers 属性中声明的所需提供程序相匹配。

属性

规则的参数,用于表示每个目标 build 信息。 例如,srcsdepscopts 分别用于声明目标的源文件、依赖项和自定义编译器选项。特定目标可用的属性取决于其规则类型。

.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 已完成。

build 设置

Starlark 定义的配置片段。 过渡可以设置 build 设置来更改子图的配置。如果作为命令行标志(也称为 build 标志)向用户公开。

全新 build

不使用之前构建的结果的构建。这通常比增量 build 慢,但通常被认为更正确。Bazel 可保证整洁 build 和增量 build 始终正确无误。

客户端-服务器模型

bazel 命令行客户端会自动在本地机器上启动一个后台服务器,以执行 Bazel 命令。服务器在命令之间保持运行,但在一段时间不活动后会自动停止(或通过 bazel 关闭命令显式停止)。将 Bazel 拆分为服务器和客户端有助于分摊 JVM 启动时间,并支持更快的增量构建,因为操作图在命令之间会保留在内存中。

命令

在命令行中使用,用于调用不同的 Bazel 函数,例如 bazel buildbazel testbazel runbazel query

命令标志

一组特定于命令的标志。命令标志在命令 (bazel build <command flags>) 之后指定。标志可适用于一个或多个命令。例如,--configurebazel sync 命令专用的标志,但 --keep_going 适用于 syncbuildtest 等。标志通常用于配置,因此标志值的更改可能会导致 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(数十万个文件)。实现为以递归方式引用其他 depsets,以提高空间效率。除非规则位于 build 图的顶层,否则规则实现不应通过将 depset 转换为列表来“扁平化”depset。扁平化大型 depset 会导致巨大的内存消耗。在 Bazel 的内部实现中也称为嵌套集

另请参阅Depset 文档

磁盘缓存

用于远程缓存功能的本地磁盘上 blob 存储区。可与实际的远程 blob 存储区结合使用。

Distdir

一个只读目录,其中包含 Bazel 否则会使用代码库规则从互联网上提取的文件。使 build 能够完全离线运行。

动态执行

一种执行策略,可根据各种启发式方法在本地执行和远程执行之间进行选择,并使用较快成功方法的执行结果。某些操作在本地执行速度更快(例如关联),而其他操作在远程执行速度更快(例如高度并行化的编译)。动态执行策略可以尽可能缩短增量构建时间和干净构建时间。

执行阶段

构建的第三个阶段。执行在分析阶段创建的操作图中的操作。这些操作会调用可执行文件(编译器、脚本)来读取和写入制品生成策略用于控制这些操作的执行方式:本地、远程、动态、沙盒、Docker 等。

执行根

工作区输出库目录中的一个目录,用于在非沙盒构建中执行本地操作。目录内容大多是工作区中输入制品的符号链接。执行根目录还包含指向外部代码库的符号链接(作为其他输入)以及用于存储输出的 bazel-out 目录。在加载阶段通过创建目录的符号链接森林来准备,这些目录表示 build 所依赖的软件包的传递闭包。可通过命令行中的 bazel info execution_root 进行访问。

文件

请参阅制品

密封性

如果构建和测试操作不受任何外部因素的影响,则该构建是密封的,这有助于确保结果是确定性的且正确的。例如,封闭式 build 通常会禁止操作访问网络、限制对已声明输入的访问、使用固定的时间戳和时区、限制对环境变量的访问,并使用固定的随机数生成器种子

增量 build

增量 build 会重复使用之前 build 的结果,以缩短 build 时间并减少资源用量。依赖项检查和缓存旨在为此类 build 生成正确的结果。增量 build 与干净 build 相反。

标签

目标的标识符。完全限定标签(例如 //path/to/package:target)由以下部分组成://(用于标记工作区根目录)、path/to/package(作为包含声明目标的 BUILD 文件的目录)和 :target(作为上述 BUILD 文件中声明的目标的名称)。还可以添加 @my_repository//<..> 前缀,以表明目标是在名为 my_repository外部代码库中声明的。

加载阶段

构建的第一阶段,在此阶段,Bazel 会解析 WORKSPACEBUILD.bzl 文件以创建软件包。在此阶段,系统会评估和某些函数(例如 glob())。与 build 的第二阶段(即分析阶段)交织在一起,以构建目标图

一种机制,用于将多个 rule 目标声明组合在一起,放在单个 Starlark 函数下。支持在多个 BUILD 文件中重复使用通用规则声明模式。在加载阶段扩展到基础规则目标声明。

另请参阅宏文档

助记符

规则作者选择的简短且直观易懂的字符串,用于快速了解规则中操作的作用。助记符可用作派生策略选择的标识符。操作助记符的一些示例包括 Java 规则中的 Javac、C++ 规则中的 CppCompile 和 Android 规则中的 AndroidManifestMerger

原生规则

内置到 Bazel 中并以 Java 实现的规则。此类规则在 .bzl 文件中显示为原生模块中的函数(例如 native.cc_librarynative.java_library)。用户定义的规则(非原生)是使用 Starlark 创建的。

输出基础

用于存储 Bazel 输出文件的特定于工作区的目录。用于将输出与工作区的源代码树分开。位于输出用户根目录中。

输出组

一组文件,当 Bazel 完成目标构建时,这些文件应会被构建。规则将其常规输出放入“默认输出组”(例如,java_library.a.so.jar 文件,适用于 cc_library 目标)。默认输出组是指在命令行中请求目标时构建其 制品的输出组。规则可以定义更多可在 BUILD 文件filegroup 规则)或命令行(--output_groups 标志)中明确指定的命名输出组。

输出用户根

用于存储 Bazel 输出的用户专用目录。目录名称派生自用户的系统用户名。如果多个用户同时在系统上构建同一项目,可防止输出文件发生冲突。 包含与各个工作区的 build 输出对应的子目录,也称为输出库

软件包

BUILD 文件定义的一组目标。软件包的名称是 BUILD 文件相对于工作区根目录的路径。一个软件包可以包含子软件包,也可以包含包含 BUILD 文件的子目录,从而形成软件包层次结构。

软件包组

表示一组软件包的目标。通常用于 visibility 属性值中。

平台

build 中涉及的“机器类型”。这包括运行 Bazel 的机器(“宿主”平台)、执行构建工具的机器(“执行”平台)以及构建目标所面向的机器(“目标平台”)。

提供商

一种用于描述在规则目标之间沿依赖关系传递的信息单元的架构。它通常包含编译器选项、传递性源文件或输出文件以及 build 元数据等信息。经常与 depset 结合使用,以高效存储累积的传递数据。内置提供程序的示例是 DefaultInfo

另请参阅提供程序文档

查询(概念)

分析构建图以了解目标属性和依赖关系结构的过程。Bazel 支持三种查询变体:querycqueryaquery

查询(命令)

一种在 build 的后加载阶段 目标图上运行的查询工具。这相对较快,但无法分析 select()build 标志制品或 build 操作的效果。

另请参阅查询方法指南查询参考文档

代码库缓存

由 Bazel 为 build 下载的文件组成的共享内容可寻址缓存,可在多个工作区之间共享。在初始下载后启用离线 build。通常用于缓存通过 http_archive 等存储库规则和 repository_ctx.download 等存储库规则 API 下载的文件。仅当为下载指定了文件的 SHA-256 校验和时,文件才会缓存。

可再现性

一种构建或测试属性,指无论时间、方法或环境如何,一组构建或测试输入始终会生成相同的一组输出。请注意,这并不一定意味着输出是正确或所需的输出。

规则

用于在 BUILD 文件(例如 cc_library)中定义规则目标的架构。从 BUILD 文件作者的角度来看,规则由一组属性和黑盒逻辑组成。该逻辑会告知规则目标如何生成输出制品并将信息传递给其他规则目标。从 .bzl 作者的角度来看,规则是扩展 Bazel 以支持新的编程语言和环境的主要方式。

规则在加载阶段实例化,以生成规则目标。在分析阶段,规则目标会以提供程序的形式向其下游依赖项传递信息,并注册描述如何生成其输出制品的操作。这些操作在执行阶段运行。

另请参阅规则文档

规则目标

作为规则实例的目标。与文件目标和软件包组形成对比。请勿与规则混淆。

Runfiles

可执行目标的运行时依赖项。最常见的情况是,可执行文件是测试规则的可执行输出,而 runfiles 是测试的运行时数据依赖项。在调用可执行文件之前(在 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(所有规则目标)、:*(所有规则目标和文件目标)、...(当前软件包和所有子软件包 [递归])。可以组合使用,例如,//...:* 表示从工作区的根目录开始,递归地查找所有软件包中的所有规则和文件目标。

测试

从测试规则实例化的规则目标,因此包含测试可执行文件。可执行文件完成时返回代码 0 表示测试成功。Bazel 与测试之间的确切合约(例如测试环境变量、测试结果收集方法)在测试百科全书中指定。

工具链

一组用于为某种语言构建输出的工具。通常,工具链包括编译器、链接器、解释器和/或代码检查器。工具链也可能因平台而异,也就是说,即使工具链适用于同一种语言,Unix 编译器工具链的组件也可能与 Windows 变体不同。为平台选择合适的工具链称为工具链解析。

顶级目标

如果构建目标是在 Bazel 命令行中请求的,则该目标为顶级目标。例如,如果 //:foo 依赖于 //:bar,并且调用了 bazel build //:foo,那么对于此 build,//:foo 是顶级目标,而 //:bar 不是顶级目标,尽管这两个目标都需要构建。顶级目标与非顶级目标之间的一个重要区别是,在 Bazel 命令行中(或通过 .bazelrc)设置的命令标志将为顶级目标设置配置,但可能会被非顶级目标的转换修改。

过渡

从一个值到另一个值的配置状态的映射。 使build 图中的目标具有不同的配置,即使它们是从同一规则实例化的也是如此。过渡的常见用法是使用拆分过渡,其中目标图的某些部分会分叉,每个分叉都有不同的配置。例如,可以在一次构建中使用拆分转换来构建包含针对 ARM 和 x86 编译的原生二进制文件的 Android APK。

另请参阅用户定义的过渡

树状制品

表示文件集合的制品。由于这些文件本身不是制品,因此对它们进行操作的 action 必须改为将树形制品注册为输入或输出。

公开范围

用于防止 build 系统中出现不必要依赖项的两种机制之一:目标可见性,用于控制其他目标是否可以依赖某个目标;以及加载可见性,用于控制 BUILD.bzl 文件是否可以加载给定的 .bzl 文件。在没有上下文的情况下,“可见性”通常是指目标可见性。

另请参阅可见性文档

工作区

包含 WORKSPACE 文件和您要构建的软件的源代码的目录。以 // 开头的标签相对于工作区目录。

WORKSPACE 文件

将目录定义为工作区。该文件可以为空,但通常包含用于从网络或本地文件系统提取其他依赖项的外部代码库声明。