查詢快速入門導覽課程

本教學課程說明如何使用 Bazel，使用預先建立的 Bazel 專案追蹤程式碼中的依附元件。

如需語言和 --output 旗標的詳細資料，請參閱 Bazel 查詢參考資料和 Bazel cquery 參考資料手冊。在指令列中輸入 bazel help query 或 bazel help cquery，即可在 IDE 中取得說明。

目標

本指南會介紹一系列基本查詢，協助您進一步瞭解專案的檔案依附元件。適用對象為具備 Bazel 和 BUILD 檔案運作方式基本知識的 Bazel 開發人員。

必要條件

如果您尚未安裝 Bazel，請先安裝。本教學課程使用 Git 進行原始碼控管，因此為獲得最佳效果，請一併安裝 Git。

為了以視覺化方式呈現依附元件圖表，系統會使用 Graphviz 工具，您可以下載這項工具，以便按照步驟操作。

取得範例專案

接著，在您選擇的指令列工具中執行下列指令，從 Bazel 的 Example 存放區擷取範例應用程式：

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 檔案，以便找到所需資訊，而是只使用查詢函式。

專案包含構成咖啡廳的不同套件。分別分為：restaurant、ingredients、dishes、customers 和 reviews。這些套件中的規則可透過各種標記和依附元件定義 Cafe 的不同元件。

執行版本

這項專案包含 Runner.java 中的主要方法，您可以執行以列印咖啡廳的選單。請搭配 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 的檔案，這是建構圖表的文字表示法。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

查詢傳回顯示披薩和馬安加西斯都仰賴起司。真了不起！

根據標記尋找目標

兩位客戶走進 Bazel Cafe：Amir 和 Jenny。除了姓名外，目前還沒有人瞭解他們。幸好，他們在「客戶」的 BUILD 檔案中標記了自家訂單。如何存取這個代碼？

開發人員可使用不同 ID 標記 Bazel 目標，通常用於測試。舉例來說，測試中的標記可以在偵錯和發布程序中為測試的角色加上註解，尤其是針對缺少任何執行階段註解功能的 C++ 和 Python 測試。使用標記和大小元素，可讓您根據程式碼集的簽入政策，靈活組合測試套件。

在這個範例中，標記是 pizza 或 macAndCheese 的其中一個，用來代表選單項目。這個指令會查詢特定套件中 ID 與 ID 相符的目標。

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

這項查詢會傳回「customers」套件中，含有「pizza」標記的所有目標。

自我測試

使用這個查詢瞭解小珍想要訂購的產品。

新增依附元件

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 之間的路徑。

查看「牛肉」和「起司」目標間的關係，探索這兩項功能之間的差異。從一個目標到另一個目標的方式有很多種：

• Chef → 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 → 起司。如果改用 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 查詢，找出評論撰寫者及其描述的內容。

總結

恭喜！您現在已執行幾項基本查詢，這些查詢可在自己的專案中試用。如要進一步瞭解查詢語言語法，請參閱查詢參考頁面。想取得更多進階查詢嗎？查詢指南提供許多用途深入清單，其中並未涵蓋在本指南涵蓋範圍內。