相约 2023 年 BazelCon 将于 10 月 24 日至 25 日在 Google 慕尼黑举办!了解详情

Bazel 术语表

报告问题 查看源代码

操作

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

另请参阅规则文档

操作缓存

存储已执行的操作与其创建的输出的映射的磁盘缓存。缓存键称为操作键。是 Bazel 增量模型的核心组件。缓存存储在输出基目录中,因此在 Bazel 服务器重启后。

操作图表

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

操作图表查询 (aquery)

可以对构建操作执行查询的查询工具。 这样,您就可以分析构建规则在实际工作构建中的转换情况。

操作键

操作的缓存键。根据操作元数据计算得出,其中可能包括要在操作、命令、库位置或系统头文件中执行的命令,具体取决于操作。使 Bazel 能够明确地缓存单个操作或使它们失效。

分析阶段

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

工件

源文件或生成的文件。也可以是文件目录,称为“树工件”。

工件可能是多项操作的输入,但最多只能由一项操作生成。

文件目标对应的工件可以通过标签处理。

方面

一种规则,用于在其依赖项中创建其他操作的机制。例如,如果目标 A 依赖于 activity B,则可以将 activity 的某一项上移至依赖项边缘到 activity 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

Bazel 的 Google 内部版本。Google 用于单代码库的主要构建系统。

构建文件

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 保证干净构建和增量构建始终正确无误。

客户端-服务器模型

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

命令

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

命令标志

一组特定于命令的标志。命令标志在命令 (bazel build <command flags>) 之后指定。标志适用于一个或多个命令。例如,--configure 是仅适用于 bazel sync 命令的标志,但 --keep_going 适用于 syncbuildtest 等。标志通常用于配置用途,因此更改标志值可能会导致 Bazel 使内存中的图形失效,并重新开始分析阶段

配置

rule 定义以外的信息,会影响规则如何生成操作。每个 build 至少有一个配置指定目标平台、操作环境变量和命令行构建标志转换可能会创建其他配置,例如为主机工具或交叉编译创建配置。

另请参阅配置

配置剪辑

仅包含目标实际所需的部分配置的过程。例如,如果您使用 C++ 依赖项 //:c 构建 Java 二进制文件 //:j,在 //:c 的配置中包含 --javacopt 的值是一种浪费,因为更改 --javacopt 会不必要地破坏 C++ 构建。

配置的查询 (cquery)

查询工具,在分析阶段完成后查询配置的目标。这意味着,select()构建标志(例如 --platforms)会准确地反映在结果中。

另请参阅cquery 文档

配置的目标

使用配置评估目标的结果。分析阶段通过将 build 的选项与需要构建的目标相结合来生成此数量。例如,如果 //:foo 针对同一 build 中的两种不同架构进行构建,则它具有两个已配置的目标:<//:foo, x86><//:foo, arm>

正确性

当 build 的输出真实地反映其传递输入的状态时,build 就正确无误。为了实现正确的 build,Bazel 会尽力采用封闭、可重现性,并让构建分析操作执行变得具有确定性。

依赖项

两个目标之间的有向边缘。如果 //:foo 的属性值包含对 //:bar 的引用,则目标 //:foo 对目标 //:bar 具有目标依赖项。如果 //:foo 中的操作依赖于 //:bar 中的操作创建的输入工件,则 //:foo 依赖于 //:bar

利用

一种用于传递传递依赖项的数据的数据结构。经过优化,可以合并偏移并节省时间和空间,因为通常存在非常大的预设(数十万个文件)。为了实现空间效率的原因,实现了以递归方式引用其他依赖项。Rule 实现不应通过将依赖项转换为列表来“扁平化”依赖项,除非该规则位于 build 图的顶层。展平较大的依赖项会导致大量的内存消耗。在 Bazel 的内部实现中也称为嵌套集。

另请参阅Depset 文档

磁盘缓存

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

一个只读目录,其中包含 Bazel 会使用存储库规则从互联网中提取的文件。使构建完全离线运行。

动态执行

根据各种启发法在本地和远程执行之间进行选择的执行策略,并使用较快的方法的执行结果。某些操作的执行速度更快(例如,链接速度),而其他操作速度(例如高度并行的编译)速度也会更快。动态执行策略可以提供尽可能合理的增量和干净构建时间。

执行阶段

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

执行根

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

文件

请参阅工件

封闭

如果某个 build 对构建和测试操作没有外部影响,就说明它是封闭的,这有助于确保结果具有确定性和正确。例如,封闭构建通常不允许对操作进行网络访问、限制对声明的输入的访问权限、使用固定的时间戳和时区、限制对环境变量的访问权限,以及对随机数生成器使用固定种子

增量构建

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

标签

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

加载阶段

构建的第一阶段,Bazel 会解析 WORKSPACEBUILD.bzl 文件以创建软件包。在此阶段中,系统会对glob() 等特定函数进行评估。与构建流程的第二阶段(即分析阶段)交错,以便构建目标图

在单个 Starlark 函数下组合多个 rule 目标声明的机制。支持跨 BUILD 文件重复使用通用规则声明模式。在加载阶段扩展至底层规则目标声明。

另请参阅宏文档

助记符

由规则作者选择的简明易懂的字符串,用于快速了解规则中的操作。助记符可以用作生成衍生策略的标识符。一些操作助记符包括来自 Java 规则的 Javac、来自 C++ 规则的 CppCompile 以及来自 Android 规则的 AndroidManifestMerger

原生规则

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

输出基数

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

输出组

预计在 Bazel 完成目标构建后构建的一组文件。规则会将它们的常规输出放入“默认输出组”(例如,cc_library 目标的 java_library.a.jar 文件)中。默认输出组是在命令行中请求目标时构建工件的输出输出组。规则可以定义更多命名的输出组,这些输出组可以在 BUILD 文件filegroup 规则)或命令行(--output_groups 标志)中明确指定。

输出用户根

用于存储 Bazel 输出的用户专属目录。目录名称来自用户的系统用户名。如果多个用户在同一系统上同时构建同一项目,则防止输出文件冲突。包含与各个工作区的构建输出对应的子目录,也称为“输出基站”。

软件包

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

软件包组

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

平台

构建涉及的“机器类型”。这包括在 Bazel 上运行的机器(“主机”)、机器构建工具在(“执行”平台)以及机器目标构建(“目标平台”)上运行。

提供方

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

另请参阅提供商文档

查询(概念)

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

查询(命令)

一个查询工具,在 build 的加载后目标图上运行。虽然速度相对较快,但无法分析 select()build 标志工件或构建 action 的效果。

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

代码库缓存

由 Bazel 为构建文件下载的共享内容可寻址缓存,可跨工作区共享。允许在初始下载后启用离线 build。通常用于缓存通过代码库规则(例如 http_archive)和代码库规则 API(例如 repository_ctx.download)下载的文件。只有在为下载文件指定了 SHA-256 校验和时,系统才会缓存文件。

可再现性

build 或测试的属性,用于指示 build 或测试的一系列输入是否每次都会生成同一组输出,无论时间、方法或环境如何。请注意,这并不意味着输出正确或所需的输出。

规则

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

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

另请参阅规则文档

规则目标

目标实例,即规则的实例。与文件目标和软件包组相对。请勿与规则混淆。

运行文件

可执行目标的运行时依赖项。通常,可执行文件是测试规则的可执行输出,而运行文件是测试的运行时数据依赖项。在调用可执行文件(在 Bazel 测试期间)之前,Bazel 会根据其源目录结构准备运行文件树与测试可执行文件。

另请参阅Runfiles 文档

沙盒

一种技术,可在隔离的临时执行根中隔离正在运行的操作,有助于确保其不会读取未声明的输入或写入未声明的输出。沙盒可显著提高机密性,但通常会产生性能开销,并且需要操作系统提供支持。性能费用取决于平台。 在 Linux 上,文件不重要,但在 macOS 上,可能会无法使用沙盒。

天窗

Skyframe 是 Bazel 的核心并行、功能和增量评估框架。

冲压

一种可将额外信息嵌入 Bazel 构建的工件的功能。例如,这可用于发布控件的构建控制、构建时和其他工作区或环境相关信息。通过 --workspace_status_command 标志以及支持图章属性的规则启用。

斯塔拉克

用于编写规则的扩展程序语言。一个受限的 Python 子集(在语法和语法上),用于配置和实现更好的性能。使用 .bzl 文件扩展名。BUILD 文件使用更严格的 Starlark 版本(例如没有 def 函数定义),之前称为 Skylark。

另请参阅Starlark 语言文档

启动标志

bazel命令之间指定的标志集,例如 bazel --host_jvm_debug build。这些标志修改 Bazel 服务器的配置,因此对启动标志的任何修改都会导致服务器重启。启动标志并不特定于任何命令。

目标

一个在 BUILD 文件中定义并通过标签标识的对象。目标从最终用户的角度代表工作区的可构建单元。

通过实例化规则声明的目标称为规则目标。根据规则,这些规则可能是可运行(如 cc_binary)或可测试(如 cc_test)。规则目标通常通过其属性(如 deps)依赖于其他目标;这些依赖项构成目标图的基础。

除了规则目标之外,还有文件目标和软件包组目标。文件目标与 BUILD 文件中引用的工件相对应。一种特殊情况是,任何软件包的 BUILD 文件始终被视为该软件包中的源文件目标。

目标是在加载阶段发现的。分析阶段,目标会与构建配置相关联,从而形成配置的目标

目标图表

目标及其依赖项的内存图。在加载阶段生成并用作分析阶段的输入。

目标模式

一种在命令行上指定一组目标的方式。常用的模式包括 :all(所有规则目标)、:*(所有规则和文件目标)、...(当前软件包和递归的所有子软件包)。例如,可以组合使用 //...:* 表示以递归方式从工作区的根目录下的所有软件包中的所有规则和文件目标。

测试

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

工具链

为语言构建输出的一组工具。通常,工具链包括编译器、链接器、解释器和/和 linter。工具链也可能因平台而异,也就是说,Windows 变体的 Unix 编译器工具链的组件可能有所不同,即使工具链针对同一语言也是如此。为平台选择合适的工具链称为工具链解析。

顶级目标值

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

转换

配置状态从一个值到另一个值的映射。使构建图中的目标具有不同的配置,即使它们是从同一规则进行实例化也是如此。过渡的常见用途是拆分拆分,其中目标图的某些部分具有针对每个分支的不同配置分支。例如,用户可以使用分屏转换在单个 build 中编译专为 ARM 和 x86 编译的原生二进制文件。

另请参阅用户定义的过渡

树工件

表示文件集合的工件。由于这些文件本身不是工件,因此对其执行操作的操作必须改为将树工件注册为其输入或输出。

公开范围

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

另请参阅公开范围文档

工作区

一个目录,其中包含了 WORKSPACE 文件以及您要构建的软件的源代码。以 // 开头的标签相对于工作区目录。

WORKSPACE 文件

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