本教程介绍了如何使用 Bazel，通过预制的 Bazel 项目跟踪代码中的依赖项。
如需详细了解语言和 --output 标志，请参阅 Bazel 查询参考文档和 Bazel Cquery 参考文档手册。在命令行中输入 bazel help query 或 bazel 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
└── WORKSPACE
在整个教程中，除非另有说明，否则请尽量不要通过查看 BUILD 文件来查找所需信息，而应仅使用查询函数。
一个项目包含一些不同的软件包，这些软件包构成了 Cafe。它们分为 restaurant、ingredients、dishes、customers 和 reviews。这些软件包中的规则通过各种标记和依赖项定义 Cafe 的不同组件。
运行 build
此项目在 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。除了名字之外，对他们一无所知。幸运的是，他们在“客户”的 BUILD 文件中对订单进行了标记。如何访问此代码？
开发者可以使用不同的标识符标记 Bazel 目标，通常用于测试目的。例如，测试上的标记可以注释某个测试在调试和发布过程中的作用，尤其是对于缺少任何运行时注释功能的 C++ 和 Python 测试。使用标记和大小元素可让您根据代码库的签入政策灵活地组合测试套件。
在此示例中，标记可以是 pizza 或 macAndCheese 之一，用于表示菜单项。此命令会在特定软件包中查询具有与您的标识符匹配的标记的目标。
bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)'
该查询返回“customers”包中包含标签“pizza”的所有目标。
测试自己
使用此查询了解 Jenny 想要点什么。
答案
芝士通心粉
添加新的依赖项
Cafe Bazel 菜单扩展了，客户现在可以订购冰沙！这种奶昔由 Strawberry 和 Banana 原料构成。
首先，添加冰沙需要的食材：Strawberry.java 和 Banana.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.in 和 graph2.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 之间的路径。
通过观察“厨师”和“奶酪”目标之间的关系，了解这两个功能之间的差异。从一个目标到另一个目标的可能路径不尽相同：
- 厨师 → 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 是唯一点过披萨的客户，也是为我们提供答案的评价者。
总结
恭喜！现在，您已经运行了几个基本查询，可以在自己的项目中试用这些查询。如需详细了解查询语言语法，请参阅查询参考页面。想要更多高级查询？查询指南展示了一个详尽的用例列表，其中包括本指南中未涵盖的用例。