Bazel 术语表

报告问题 查看源代码

操作

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

另请参阅规则文档

操作缓存

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

操作图

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

操作图表查询 (aquery)

可以对构建操作进行查询的查询工具。通过这种方式,您可以分析构建规则如何转化为构建的实际工作。

操作键

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

分析阶段

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

制品

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

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

与文件目标对应的工件可以通过标签进行寻址。

切面

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

另请参阅切面文档

纵横比

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

若要在切面 B 之上应用切面 AB 在其 provides 属性中通告的提供程序必须与 A 在其 required_aspect_providers 属性中声明的提供程序一致。

属性

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

.bazelrc

Bazel 的配置文件,用于更改启动标志命令标志的默认值,以及定义随后可在 Bazel 命令行中使用 --config 标志一起设置的常见选项组。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 为执行构建而构建和遍历的依赖关系图。 包括目标已配置的目标操作工件等节点。当一组请求目标所依赖的所有工件都被验证为最新时,构建会被视为已完成。

构建设置

Starlark 定义的一段配置过渡可设置构建设置以更改子图的配置。如果以命令行标志(也称为构建标志)的形式向用户显示。

干净 build

不使用早期构建结果的构建。这通常比增量构建慢,但通常被认为更正确。Bazel 可保证干净构建和增量构建始终正确无误

客户端-服务器模式

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

命令

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

命令标志

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

配置

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

另请参阅配置

配置删减

仅包含目标实际需要的配置部分的过程。例如,如果您构建具有 C++ 依赖项 //:c 的 Java 二进制文件 //:j,在 //:c 的配置中添加 --javacopt 的值会造成浪费,因为更改 --javacopt 会不必要地破坏 C++ build 的可缓存性。

配置的查询 (cquery)

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

另请参阅cquery 文档

配置的目标

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

正确性

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

依赖项

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

取消设置

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

另请参阅设置文档

磁盘缓存

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

只读目录,包含 Bazel 会使用代码库规则从互联网提取的文件。使构建能够完全离线运行。

动态执行

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

执行阶段

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

执行根

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

文件

请参阅软件工件

封闭性

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

增量构建

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

标签

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

加载阶段

构建的第一阶段,在这个阶段中,Bazel 会解析 WORKSPACEBUILD.bzl 文件以创建软件包。在此阶段,系统会对和某些功能(如 glob())进行评估。与构建的第二阶段(分析阶段)交错,以构建目标图

一种在单个 Starlark 函数下将多个规则目标声明组合在一起的机制。允许在 BUILD 文件中重复使用常见的规则声明格式。在加载阶段扩展为基础规则目标声明。

另请参阅宏文档

助记符

由规则作者选择的人类可读简短字符串,用于快速了解规则中的操作正在执行的操作。助记符可用作生成策略选择的标识符。操作助记符的一些示例包括 Java 规则中的 Javac、C++ 规则中的 CppCompile 和 Android 规则中的 AndroidManifestMerger

原生规则

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

基本输出

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

输出组

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

输出用户根目录

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

软件包

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

软件包组

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

平台

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

提供方

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

另请参阅提供程序文档

查询(概念)

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

query(命令)

对 build 的加载后阶段 目标图执行的查询工具。速度相对较快,但无法分析 select()构建标志工件或构建操作的效果。

另请参阅查询方法查询参考

代码库缓存

Bazel 为 build 下载的文件的共享内容可寻址缓存,可在工作区之间共享。允许在初始下载后离线构建。通常用于缓存通过 http_archive 等仓库规则和 repository_ctx.download 等仓库规则 API 下载的文件。仅当为下载指定了文件的 SHA-256 校验和时,系统才会缓存相应文件。

可再现性

build 或测试的属性:无论何时、方法或环境如何,用于构建或测试的一组输入将始终生成同一组输出。请注意,这并不一定意味着输出正确或期望的输出。

规则

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

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

另请参阅规则文档

规则目标

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

Runfile

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

另请参阅Runfiles 文档

沙盒

一种将正在运行的操作隔离在受限和临时执行根内的技术,有助于确保该操作不会读取未声明的输入或写入未声明的输出。沙盒可大幅提高封闭性,但通常会降低性能,并且需要操作系统的支持。性能成本取决于平台。在 Linux 上,这不重要,但在 macOS 上可能会导致沙盒无法使用。

SkyFrame

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

冲压

用于将额外信息嵌入到 Bazel 构建的工件中的功能。例如,此信息可用于提供源代码控制、构建时间,以及与发布 build 的其他工作区或环境相关的信息。通过 --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 文件始终会被视为该软件包中的源文件目标。

目标是在加载阶段发现的。在分析阶段,目标与 build 配置相关联以形成配置的目标

目标图表

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

目标模式

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

测试

根据测试规则实例化的规则 targets,因此包含一个测试可执行文件。可执行文件完成后,返回代码为零表示测试成功。Bazel 和测试之间的确切约定(例如测试环境变量、测试结果收集方法)在测试百科全书中指定。

工具链

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

顶级目标

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

转换

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

另请参阅用户定义的转换

树制品

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

可见性

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

另请参阅“公开范围”文档

Workspace

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

WORKSPACE 文件

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