本教學課程說明如何使用 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」標記的所有目標。
自我測試
使用這個查詢瞭解小珍想要訂購的產品。
解答
Mac 和起司
新增依附元件
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 查詢,找出評論撰寫者及其描述的內容。
提示
請查看標記和依附元件來取得實用資訊。
解答
這則評論提到「披薩」;阿米是評論者,當您查看這項規則使用 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 是唯一訂購披薩的客戶,也會提供答案。
總結
恭喜!您現在已執行幾項基本查詢,這些查詢可在自己的專案中試用。如要進一步瞭解查詢語言語法,請參閱查詢參考頁面。想取得更多進階查詢嗎?查詢指南提供許多用途深入清單,其中並未涵蓋在本指南涵蓋範圍內。