查询快速入门

本教程介绍了如何使用 Bazel,通过预制的 Bazel 项目跟踪代码中的依赖项。

如需详细了解语言和 --output 标志,请参阅 Bazel 查询参考文档Bazel Cquery 参考文档手册。在命令行中输入 bazel help querybazel help cquery,即可在您的 IDE 中获取帮助。

目标

本指南将引导您完成一组基本查询,您可以使用这些查询来详细了解项目的文件依赖项。本课程面向的是对 Bazel 和 BUILD 文件工作原理有基本了解的 Bazel 开发者。

前提条件

首先安装 Bazel(如果尚未安装)。本教程使用 Git 进行源代码控制,因此为了获得最佳效果,也请安装 Git

为了直观呈现依存关系图,我们使用了 Graphviz 工具,您可以下载该工具,以便后续操作。

获取示例项目

接下来,在您选择的命令行工具中运行以下命令,从 Bazel 的示例代码库中检索示例应用:

git clone https://github.com/bazelbuild/examples.git

本教程的示例项目位于 examples/query-quickstart 目录中。

开始使用

什么是 Bazel 查询?

查询通过分析 BUILD 文件之间的关系并查看生成的输出以获得实用信息,帮助您了解 Bazel 代码库。本指南预览了一些基本查询函数,但如需了解更多选项,请参阅查询指南。借助查询,您无需手动浏览 BUILD 文件,即可了解大型项目中的依赖项。

如需运行查询,请打开命令行终端并输入以下命令:

bazel query 'query_function'

场景

设想一个场景,深入探究 Cafe Bazel 及其各自的厨师之间的关系。这家咖啡馆专营披萨、通心粉和奶酪。下面来看一下该项目的结构:

bazelqueryguide
├── BUILD
├── src
│   └── main
│       └── java
│           └── com
│               └── example
│                   ├── customers
│                   │   ├── Jenny.java
│                   │   ├── Amir.java
│                   │   └── BUILD
│                   ├── dishes
│                   │   ├── Pizza.java
│                   │   ├── MacAndCheese.java
│                   │   └── BUILD
│                   ├── ingredients
│                   │   ├── Cheese.java
│                   │   ├── Tomatoes.java
│                   │   ├── Dough.java
│                   │   ├── Macaroni.java
│                   │   └── BUILD
│                   ├── restaurant
│                   │   ├── Cafe.java
│                   │   ├── Chef.java
│                   │   └── BUILD
│                   ├── reviews
│                   │   ├── Review.java
│                   │   └── BUILD
│                   └── Runner.java
└── MODULE.bazel

除非另有说明,否则在本教程中,请尽量不要通过查找 BUILD 文件来查找所需信息,而应仅使用查询函数。

一个项目包含一些不同的软件包,这些软件包构成了一个咖啡馆。它们分为:restaurantingredientsdishescustomersreviews。这些软件包中的规则通过各种标记和依赖项定义 Cafe 的不同组件。

运行构建

此项目在 Runner.java 中包含了一个主方法,您可以执行该方法来输出 Cafe 的菜单。使用 bazel build 命令使用 Bazel 构建项目,并使用 : 指示目标名为 runner。如需了解如何引用目标,请参阅目标名称

如需构建此项目,请将此命令粘贴到终端中:

bazel build :runner

如果构建成功,输出应如下所示。

INFO: Analyzed target //:runner (49 packages loaded, 784 targets configured).
INFO: Found 1 target...
Target //:runner up-to-date:
  bazel-bin/runner.jar
  bazel-bin/runner
INFO: Elapsed time: 16.593s, Critical Path: 4.32s
INFO: 23 processes: 4 internal, 10 darwin-sandbox, 9 worker.
INFO: Build completed successfully, 23 total actions

成功构建后,粘贴以下命令来运行该应用:

bazel-bin/runner
--------------------- MENU -------------------------

Pizza - Cheesy Delicious Goodness
Macaroni & Cheese - Kid-approved Dinner

----------------------------------------------------

系统随即会显示菜单项列表以及简短说明。

探索目标

这个项目将食材和菜肴制作在自己的包装盒中。如需使用查询查看软件包的规则,请运行命令 bazel query package/…

在本例中,您可以通过运行以下代码,查看这家咖啡馆提供的食材和菜肴:

bazel query //src/main/java/com/example/dishes/...
bazel query //src/main/java/com/example/ingredients/...

如果您查询配料包的目标,输出应如下所示:

//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/ingredients:dough
//src/main/java/com/example/ingredients:macaroni
//src/main/java/com/example/ingredients:tomato

查找依赖项

您的跑步者依赖哪些目标来运行?

假设您想深入了解项目的结构,而无需进入文件系统(大型项目可能很难接受)。Cafe Bazel 使用哪些规则?

在此示例中,如果运行程序的目标是 runner,请运行以下命令来发现目标的底层依赖项:

bazel query --noimplicit_deps "deps(target)"
bazel query --noimplicit_deps "deps(:runner)"
//:runner
//:src/main/java/com/example/Runner.java
//src/main/java/com/example/dishes:MacAndCheese.java
//src/main/java/com/example/dishes:Pizza.java
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:Cheese.java
//src/main/java/com/example/ingredients:Dough.java
//src/main/java/com/example/ingredients:Macaroni.java
//src/main/java/com/example/ingredients:Tomato.java
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/ingredients:dough
//src/main/java/com/example/ingredients:macaroni
//src/main/java/com/example/ingredients:tomato
//src/main/java/com/example/restaurant:Cafe.java
//src/main/java/com/example/restaurant:Chef.java
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

在大多数情况下,请使用查询函数 deps() 查看特定目标的各个输出依赖项。

直观呈现依赖关系图(可选)

本部分介绍如何直观呈现特定查询的依赖项路径。Graphviz 有助于将路径视为有向无环图图片,而不是扁平化列表。您可以使用各种 --output 命令行选项更改 Bazel 查询图表的显示方式。如需了解相关选项,请参阅输出格式

首先运行所需的查询,并添加 --noimplicit_deps 标志以移除过多的工具依赖项。然后,在查询后面添加输出标志,并将图表存储在名为 graph.in 的文件中,以创建该图表的文本表示形式。

如需搜索目标 :runner 的所有依赖项并将输出格式设置为图表,请执行以下操作:

bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph.in

这将创建一个名为 graph.in 的文件,该文件是 build 图的文本表示形式。Graphviz 使用 dot (一种可将文本处理为可视化图表的工具)来创建 png:

dot -Tpng < graph.in > graph.png

如果您打开 graph.png,应该会看到如下内容。下图经过简化,在本指南中更清晰地阐述了重要的路径详细信息。

示意图:从咖啡馆到厨师再到菜肴,披萨、通心粉和奶酪,分别调成不同的食材:奶酪、西红柿、面团和通心粉。

如果您想查看本指南中不同查询函数的输出,这会很有帮助。

查找反向依赖项

如果您想分析定位条件有哪些其他定位条件使用了该定位条件,则可以使用查询来检查哪些定位条件依赖于特定规则。这称为“反向依赖项”。在修改您不熟悉的代码库中的文件时,使用 rdeps() 很有用,并且可以避免在不知情的情况下破坏依赖于它的其他文件。

例如,您要对食材 cheese 做一些修改。为避免给 Cafe Bazel 带来问题,您需要检查哪些菜品依赖于 cheese

如需查看哪些目标依赖于特定目标/软件包,您可以使用 rdeps(universe_scope, target)rdeps() 查询函数至少接受两个参数:universe_scope(相关目录)和 target。Bazel 会在提供的 universe_scope 中搜索目标的反向依赖项。rdeps() 运算符接受可选的第三个参数:一个整数字面量,用于指定搜索深度的上限。

如需在整个项目“//...”的范围内查找目标 cheese 的反向依赖项,请运行以下命令:

bazel query "rdeps(universe_scope, target)"
ex) bazel query "rdeps(//... , //src/main/java/com/example/ingredients:cheese)"
//:runner
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

查询返回结果显示,pizza 和 macAndCheese 都依赖于奶酪。太不可思议了!

根据标记查找目标

两个客户走进 Bazel Cafe:Amir 和 Jenny。除了他们的名字之外,无人知晓。幸运的是,他们在“customers”BUILD 文件中标记了他们的订单。如何访问此代码?

开发者可以使用不同的标识符标记 Bazel 目标,通常用于测试目的。例如,测试上的标记可以在调试和发布流程中为测试的角色添加注解,尤其是对于缺乏任何运行时注解功能的 C++ 和 Python 测试。使用标记和大小元素可让您根据代码库的签入政策灵活地组合测试套件。

在此示例中,标记是 pizzamacAndCheese 之一,用于表示菜单项。此命令会查询特定软件包中具有与标识符匹配的标记的目标。

bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)'

该查询返回“customers”软件包中具有“pizza”标签的所有定位。

自我测试

使用此查询了解小珍想要点什么。

答案

芝士通心粉

添加新的依赖项

Cafe Bazel 扩充了菜单 - 客户现在可以订购冰沙!这种具体的冰沙由 StrawberryBanana 原料组成。

首先,添加冰沙所依赖的食材:Strawberry.javaBanana.java。添加空 Java 类。

src/main/java/com/example/ingredients/Strawberry.java

package com.example.ingredients;

public class Strawberry {

}

src/main/java/com/example/ingredients/Banana.java

package com.example.ingredients;

public class Banana {

}

接下来,将 Smoothie.java 添加到相应的目录:dishes

src/main/java/com/example/dishes/Smoothie.java

package com.example.dishes;

public class Smoothie {
    public static final String DISH_NAME = "Smoothie";
    public static final String DESCRIPTION = "Yummy and Refreshing";
}

最后,将这些文件作为规则添加到相应的 BUILD 文件中。为每种新成分创建一个新的 Java 库,包括其名称、公开可见性及其新创建的“src”文件。最后,您应该得到以下更新后的 BUILD 文件:

src/main/java/com/example/ingredients/BUILD

java_library(
    name = "cheese",
    visibility = ["//visibility:public"],
    srcs = ["Cheese.java"],
)

java_library(
    name = "dough",
    visibility = ["//visibility:public"],
    srcs = ["Dough.java"],
)

java_library(
    name = "macaroni",
    visibility = ["//visibility:public"],
    srcs = ["Macaroni.java"],
)

java_library(
    name = "tomato",
    visibility = ["//visibility:public"],
    srcs = ["Tomato.java"],
)

java_library(
    name = "strawberry",
    visibility = ["//visibility:public"],
    srcs = ["Strawberry.java"],
)

java_library(
    name = "banana",
    visibility = ["//visibility:public"],
    srcs = ["Banana.java"],
)

在菜品的 BUILD 文件中,您想要为 Smoothie 添加新规则。此操作包括为 Smoothie 创建的 Java 文件(作为“src”文件),以及您为冰沙每种原料制定的新规则。

src/main/java/com/example/dishes/BUILD

java_library(
    name = "macAndCheese",
    visibility = ["//visibility:public"],
    srcs = ["MacAndCheese.java"],
    deps = [
        "//src/main/java/com/example/ingredients:cheese",
        "//src/main/java/com/example/ingredients:macaroni",
    ],
)

java_library(
    name = "pizza",
    visibility = ["//visibility:public"],
    srcs = ["Pizza.java"],
    deps = [
        "//src/main/java/com/example/ingredients:cheese",
        "//src/main/java/com/example/ingredients:dough",
        "//src/main/java/com/example/ingredients:tomato",
    ],
)

java_library(
    name = "smoothie",
    visibility = ["//visibility:public"],
    srcs = ["Smoothie.java"],
    deps = [
        "//src/main/java/com/example/ingredients:strawberry",
        "//src/main/java/com/example/ingredients:banana",
    ],
)

最后,您要将冰沙作为依赖项添加到 Chef 的 BUILD 文件中。

src/main/java/com/example/restaurant/BUILD

java\_library(
    name = "chef",
    visibility = ["//visibility:public"],
    srcs = [
        "Chef.java",
    ],

    deps = [
        "//src/main/java/com/example/dishes:macAndCheese",
        "//src/main/java/com/example/dishes:pizza",
        "//src/main/java/com/example/dishes:smoothie",
    ],
)

java\_library(
    name = "cafe",
    visibility = ["//visibility:public"],
    srcs = [
        "Cafe.java",
    ],
    deps = [
        ":chef",
    ],
)

再次构建 cafe,以确认没有错误。如果它构建成功,那么恭喜您!您已为“Cafe”添加了一个新的依赖项。如果不是,请留意拼写错误和软件包命名。如需详细了解如何编写 BUILD 文件,请参阅构建样式指南

现在,通过添加 Smoothie 来直观呈现新的依赖关系图,以便与上一个图进行比较。为清楚起见,请将图表输入分别命名为 graph2.ingraph2.png

bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph2.in
dot -Tpng < graph2.in > graph2.png

与第一张图相同,但现在有一条发音,发自厨师目标,是奶昔,指向香蕉和草莓

通过查看 graph2.png,您可以看到 Smoothie 没有与其他菜品共享的依赖项,而只是 Chef 所依赖的另一个目标。

somepath() 和 allpaths()

如果您想查询为什么一个软件包依赖于另一个软件包,该怎么办?在两者之间显示依赖项路径即可找到答案。

somepath()allpaths() 这两个函数可帮助您查找依赖项路径。给定起始目标 S 和终点 E,使用 somepath(S,E) 找到 S 和 E 之间的路径。

通过观察“Chef”和“Cheese”目标之间的关系,探索这两个函数之间的区别。您可以采用多种不同方式从一个目标到达另一个目标:

  • 厨师 → MacAndCheese → 奶酪
  • 厨师 → 披萨 → 奶酪

somepath() 提供两个选项中的一条路径,而“allpaths()”会输出所有可能的路径。

以 Cafe Bazel 为例,运行以下命令:

bazel query "somepath(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)"
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/ingredients:cheese

输出遵循“Cafe”→“Chef”→“MacAndCheese → Cheese”中的第一个路径。如果您改用 allpaths(),会获得:

bazel query "allpaths(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)"
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

从咖啡馆到厨师再到披萨、通心粉、奶酪再到奶酪的输出路径

allpaths() 的输出有点难以读取,因为它是依赖项的扁平化列表。使用 Graphviz 呈现此图表,可以更清晰地理解关系。

自我测试

Cafe Bazel 的一位客户给出了这家餐厅的第一条评价!很抱歉,评价缺少一些详细信息,例如评价者的身份和所引用的菜品。幸运的是,您可以使用 Bazel 访问这些信息。reviews 软件包包含一个用于输出神秘客户所写评价的程序。使用以下命令构建并运行它:

bazel build //src/main/java/com/example/reviews:review
bazel-bin/src/main/java/com/example/reviews/review

仅通过 Bazel 查询,尝试找出撰写了评价的用户以及他们所描述的菜品。

提示

请检查标记和依赖项以获取实用信息。

答案

此评论描述的是披萨,而 Amir 是评论者。如果您使用 bazel query --noimplicit\_deps 'deps(//src/main/java/com/example/reviews:review)' 查看此规则具有的依赖项 此命令的结果显示,Amir 是审核者! 接下来,由于您知道评价者是 Amir,因此您可以使用查询函数查找 Amir 在 `BUILD` 文件中的哪个标记,以查看那里是什么菜品。 bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)' 命令输出表明,Amir 是唯一点过披萨的客户,也是为我们提供答案的评价者。

总结

恭喜!现在,您已经运行了几个基本查询,可以在自己的项目中试用这些查询。如需详细了解查询语言语法,请参阅查询参考页面。想要更多高级查询?查询指南提供了比本指南所介绍的用例的详尽列表。