Hướng dẫn này trình bày cách làm việc với Bazel để theo dõi các phần phụ thuộc trong mã bằng cách sử dụng một dự án Bazel tạo sẵn.
Để biết thông tin chi tiết về ngôn ngữ và cờ --output, hãy xem hướng dẫn Tài liệu tham khảo truy vấn Bazel và Tài liệu tham khảo truy vấn c của Bazel. Nhận trợ giúp trong IDE bằng cách nhập bazel help query hoặc bazel help cquery trên dòng lệnh.
Mục tiêu
Hướng dẫn này sẽ hướng dẫn bạn thực hiện một loạt truy vấn cơ bản mà bạn có thể sử dụng để tìm hiểu thêm về các phần phụ thuộc tệp của dự án. Tài liệu này dành cho các nhà phát triển Bazel mới có kiến thức cơ bản về cách hoạt động của các tệp Bazel và BUILD.
Điều kiện tiên quyết
Bắt đầu bằng cách cài đặt Bazel nếu bạn chưa cài đặt. Hướng dẫn này sử dụng Git để kiểm soát nguồn, vì vậy, để có kết quả tốt nhất, hãy cài đặt cả Git.
Để trực quan hoá biểu đồ phần phụ thuộc, bạn có thể tải xuống công cụ có tên Graphviz để làm theo.
Tải dự án mẫu
Tiếp theo, hãy truy xuất ứng dụng mẫu từ Kho lưu trữ ví dụ của Bazel bằng cách chạy nội dung sau trong công cụ dòng lệnh mà bạn chọn:
git clone https://github.com/bazelbuild/examples.git
Dự án mẫu cho hướng dẫn này nằm trong thư mục examples/query-quickstart.
Bắt đầu
Truy vấn Bazel là gì?
Truy vấn giúp bạn tìm hiểu về cơ sở mã Bazel bằng cách phân tích mối quan hệ giữa các tệp BUILD và kiểm tra kết quả đầu ra để biết thông tin hữu ích. Hướng dẫn này xem trước một số hàm truy vấn cơ bản, nhưng để biết thêm lựa chọn, hãy xem hướng dẫn về truy vấn. Truy vấn giúp bạn tìm hiểu về các phần phụ thuộc trong các dự án quy mô lớn mà không cần phải điều hướng theo cách thủ công qua các tệp BUILD.
Để chạy truy vấn, hãy mở cửa sổ dòng lệnh và nhập:
bazel query 'query_function'
Trường hợp
Hãy tưởng tượng một tình huống đi sâu vào mối quan hệ giữa Cafe Bazel và đầu bếp tương ứng. Quán cà phê này chỉ bán pizza và mì ống với phô mai. Hãy xem cấu trúc của dự án ở bên dưới:
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
Trong suốt hướng dẫn này, trừ phi được hướng dẫn khác, hãy cố gắng không tìm trong các tệp BUILD để tìm thông tin bạn cần mà chỉ sử dụng hàm truy vấn.
Một dự án bao gồm nhiều gói tạo nên một Cafe. Các lớp này được phân tách thành: restaurant, ingredients, dishes, customers và reviews. Các quy tắc trong các gói này xác định các thành phần khác nhau của Cafe bằng nhiều thẻ và phần phụ thuộc.
Chạy bản dựng
Dự án này chứa một phương thức chính bên trong Runner.java mà bạn có thể thực thi để in thực đơn của Quán cà phê. Tạo dự án bằng Bazel với lệnh bazel build và sử dụng : để báo hiệu rằng mục tiêu có tên là runner. Xem phần tên mục tiêu để tìm hiểu cách tham chiếu mục tiêu.
Để tạo dự án này, hãy dán lệnh sau vào một thiết bị đầu cuối:
bazel build :runner
Kết quả của bạn sẽ có dạng như sau nếu bản dựng thành công.
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
Sau khi tạo thành công, hãy chạy ứng dụng bằng cách dán lệnh sau:
bazel-bin/runner
--------------------- MENU -------------------------
Pizza - Cheesy Delicious Goodness
Macaroni & Cheese - Kid-approved Dinner
----------------------------------------------------
Thao tác này sẽ cung cấp cho bạn danh sách các mục trong trình đơn cùng với nội dung mô tả ngắn.
Khám phá mục tiêu
Dự án liệt kê các nguyên liệu và món ăn trong các gói riêng. Để sử dụng truy vấn nhằm xem các quy tắc của một gói, hãy chạy lệnh bazel query package/…
Trong trường hợp này, bạn có thể sử dụng hàm này để xem qua các nguyên liệu và món ăn mà quán cà phê này có bằng cách chạy:
bazel query //src/main/java/com/example/dishes/...
bazel query //src/main/java/com/example/ingredients/...
Nếu bạn truy vấn các mục tiêu của gói thành phần, kết quả sẽ có dạng như sau:
//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
Tìm phần phụ thuộc
Trình chạy của bạn dựa vào những mục tiêu nào để chạy?
Giả sử bạn muốn tìm hiểu sâu hơn về cấu trúc của dự án mà không cần tìm hiểu hệ thống tệp (điều này có thể không phù hợp với các dự án lớn). Cafe Bazel sử dụng những quy tắc nào?
Nếu như trong ví dụ này, mục tiêu cho trình chạy là runner, hãy khám phá các phần phụ thuộc cơ bản của mục tiêu bằng cách chạy lệnh:
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
Trong hầu hết các trường hợp, hãy sử dụng hàm truy vấn deps() để xem các phần phụ thuộc đầu ra riêng lẻ của một mục tiêu cụ thể.
Hình ảnh hoá biểu đồ phần phụ thuộc (không bắt buộc)
Phần này mô tả cách bạn có thể trực quan hoá các đường dẫn phần phụ thuộc cho một truy vấn cụ thể. Graphviz giúp xem đường dẫn dưới dạng hình ảnh biểu đồ không tuần hoàn có hướng thay vì danh sách được làm phẳng. Bạn có thể thay đổi chế độ hiển thị biểu đồ truy vấn Bazel bằng cách sử dụng nhiều tuỳ chọn dòng lệnh --output. Hãy xem phần Định dạng đầu ra để biết các tuỳ chọn.
Bắt đầu bằng cách chạy truy vấn mong muốn và thêm cờ --noimplicit_deps để xoá các phần phụ thuộc công cụ thừa. Sau đó, hãy làm theo truy vấn bằng cờ đầu ra và lưu trữ biểu đồ vào một tệp có tên là graph.in để tạo bản trình bày văn bản của biểu đồ.
Để tìm kiếm tất cả phần phụ thuộc của mục tiêu :runner và định dạng đầu ra dưới dạng biểu đồ:
bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph.in
Thao tác này sẽ tạo một tệp có tên graph.in, là một bản trình bày văn bản của biểu đồ bản dựng. Graphviz sử dụng dot – một công cụ xử lý văn bản thành hình ảnh trực quan – để tạo tệp png:
dot -Tpng < graph.in > graph.png
Nếu mở graph.png, bạn sẽ thấy nội dung như sau. Biểu đồ bên dưới đã được đơn giản hoá để làm rõ hơn thông tin chi tiết về đường dẫn thiết yếu trong hướng dẫn này.
Điều này sẽ hữu ích khi bạn muốn xem kết quả của các hàm truy vấn khác nhau trong suốt hướng dẫn này.
Tìm phần phụ thuộc ngược
Nếu muốn phân tích mục tiêu nào khác sử dụng một mục tiêu, bạn có thể sử dụng truy vấn để kiểm tra mục tiêu nào phụ thuộc vào một quy tắc nhất định. Đây được gọi là "phần phụ thuộc ngược". Việc sử dụng rdeps() có thể hữu ích khi chỉnh sửa một tệp trong cơ sở mã mà bạn không quen thuộc, đồng thời có thể giúp bạn tránh vô tình làm hỏng các tệp khác phụ thuộc vào tệp đó.
Ví dụ: bạn muốn chỉnh sửa một số thành phần của cheese. Để tránh gây ra vấn đề cho Cafe Bazel, bạn cần kiểm tra những món ăn nào phụ thuộc vào cheese.
Để xem những mục tiêu nào phụ thuộc vào một mục tiêu/gói cụ thể, bạn có thể sử dụng rdeps(universe_scope, target). Hàm truy vấn rdeps() nhận ít nhất hai đối số: universe_scope – thư mục có liên quan – và target. Bazel tìm kiếm các phần phụ thuộc ngược của mục tiêu trong universe_scope được cung cấp. Toán tử rdeps() chấp nhận đối số thứ ba không bắt buộc: một số nguyên cố định chỉ định giới hạn trên về độ sâu của lượt tìm kiếm.
Để tìm các phần phụ thuộc ngược của mục tiêu cheese trong phạm vi toàn bộ dự án "//…", hãy chạy lệnh:
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
Kết quả trả về của truy vấn cho thấy cả pizza và macAndCheese đều sử dụng phô mai. Thật bất ngờ!
Tìm mục tiêu dựa trên thẻ
Hai khách hàng bước vào quán cà phê Bazel: Amir và Jenny. Không có thông tin nào về các thành phần này ngoại trừ tên. May mắn thay, các đơn đặt hàng của họ được gắn thẻ trong tệp BUILD "khách hàng". Làm cách nào để truy cập vào thẻ này?
Nhà phát triển có thể gắn thẻ các mục tiêu Bazel bằng nhiều giá trị nhận dạng, thường là cho mục đích kiểm thử. Ví dụ: thẻ trên kiểm thử có thể chú thích vai trò của kiểm thử trong quá trình gỡ lỗi và phát hành, đặc biệt là đối với kiểm thử C++ và Python, các kiểm thử này không có khả năng chú thích thời gian chạy. Việc sử dụng thẻ và phần tử kích thước giúp bạn linh hoạt trong việc tập hợp các bộ kiểm thử dựa trên chính sách kiểm tra của cơ sở mã.
Trong ví dụ này, các thẻ là một trong hai pizza hoặc macAndCheese để đại diện cho các mục trong trình đơn. Lệnh này truy vấn các mục tiêu có thẻ khớp với giá trị nhận dạng của bạn trong một gói nhất định.
bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)'
Truy vấn này trả về tất cả các mục tiêu trong gói "khách hàng" có thẻ "pizza".
Tự kiểm tra
Sử dụng truy vấn này để tìm hiểu xem Jenny muốn đặt món gì.
Trả lời
Nui phô mai
Thêm phần phụ thuộc mới
Cafe Bazel đã mở rộng thực đơn — giờ đây, khách hàng có thể gọi món Sinh tố! Sinh tố cụ thể này bao gồm các thành phần Strawberry và Banana.
Trước tiên, hãy thêm các thành phần mà món sinh tố phụ thuộc vào: Strawberry.java và Banana.java. Thêm các lớp Java trống.
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 {
}
Tiếp theo, hãy thêm Smoothie.java vào thư mục thích hợp: 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";
}
Cuối cùng, hãy thêm các tệp này dưới dạng quy tắc trong các tệp BUILD thích hợp. Tạo một thư viện java mới cho mỗi thành phần mới, bao gồm tên, chế độ hiển thị công khai và tệp "src" mới tạo. Bạn sẽ có tệp BUILD mới cập nhật như sau:
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"],
)
Trong tệp BUILD cho các món ăn, bạn muốn thêm một quy tắc mới cho Smoothie. Thao tác này bao gồm tệp Java được tạo cho Smoothie dưới dạng tệp "src" và các quy tắc mới mà bạn đã tạo cho từng thành phần của món sinh tố.
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",
],
)
Cuối cùng, bạn muốn thêm món sinh tố làm phần phụ thuộc trong tệp BUILD của Chef.
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",
],
)
Tạo lại cafe để xác nhận rằng không có lỗi nào. Nếu bản dựng thành công, xin chúc mừng! Bạn đã thêm một phần phụ thuộc mới cho "Cafe". Nếu không, hãy chú ý đến lỗi chính tả và cách đặt tên gói. Để biết thêm thông tin về cách viết tệp BUILD, hãy xem Hướng dẫn về kiểu BUILD.
Bây giờ, hãy trực quan hoá biểu đồ phần phụ thuộc mới bằng cách thêm Smoothie để so sánh với biểu đồ trước đó. Để rõ ràng, hãy đặt tên đầu vào biểu đồ là graph2.in và graph2.png.
bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph2.in
dot -Tpng < graph2.in > graph2.png
Khi xem graph2.png, bạn có thể thấy Smoothie không có phần phụ thuộc dùng chung với các món ăn khác mà chỉ là một mục tiêu khác mà Chef dựa vào.
somepath() và allpaths()
Nếu bạn muốn truy vấn lý do một gói phụ thuộc vào một gói khác thì sao? Việc hiển thị đường dẫn phần phụ thuộc giữa hai phần này sẽ cho bạn câu trả lời.
Hai hàm có thể giúp bạn tìm đường dẫn phần phụ thuộc: somepath() và allpaths(). Với mục tiêu bắt đầu là S và điểm cuối là E, hãy tìm đường dẫn giữa S và E bằng cách sử dụng somepath(S,E).
Khám phá sự khác biệt giữa hai hàm này bằng cách xem mối quan hệ giữa các mục tiêu "Chef" và "Cheese". Có nhiều đường dẫn có thể dẫn từ mục tiêu này đến mục tiêu khác:
- Chef → MacAndCheese → Cheese
- Đầu bếp → Pizza → Phô mai
somepath() cung cấp cho bạn một đường dẫn trong số hai tuỳ chọn, trong khi "allpaths()" xuất ra mọi đường dẫn có thể có.
Lấy Cafe Bazel làm ví dụ, hãy chạy lệnh sau:
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
Kết quả sẽ tuân theo đường dẫn đầu tiên là Cafe → Chef → MacAndCheese → Cheese. Nếu sử dụng allpaths(), bạn sẽ nhận được:
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
Kết quả của allpaths() khó đọc hơn một chút vì đây là danh sách các phần phụ thuộc được làm phẳng. Việc trực quan hoá biểu đồ này bằng Graphviz giúp bạn hiểu rõ hơn về mối quan hệ.
Tự kiểm tra
Một khách hàng của Cafe Bazel đã viết bài đánh giá đầu tiên cho nhà hàng! Rất tiếc, bài đánh giá này thiếu một số thông tin chi tiết như danh tính của người đánh giá và món ăn mà bài đánh giá đề cập đến. May mắn là bạn có thể truy cập vào thông tin này bằng Bazel. Gói reviews chứa một chương trình in bài đánh giá của một khách hàng bí ẩn. Tạo và chạy ứng dụng bằng:
bazel build //src/main/java/com/example/reviews:review
bazel-bin/src/main/java/com/example/reviews/review
Chỉ dựa vào các truy vấn Bazel, hãy cố gắng tìm hiểu xem ai đã viết bài đánh giá và họ đang mô tả món ăn nào.
Gợi ý
Kiểm tra các thẻ và phần phụ thuộc để biết thông tin hữu ích.
Trả lời
Bài đánh giá này mô tả về Pizza và Amir là người đánh giá. Nếu bạn xem xét các phần phụ thuộc mà quy tắc này có bằng cách sử dụng bazel query --noimplicit\_deps 'deps(//src/main/java/com/example/reviews:review)', kết quả của lệnh này sẽ cho thấy rằng Amir là người xem xét!
Tiếp theo, vì biết người đánh giá là Amir, bạn có thể sử dụng hàm truy vấn để tìm thẻ mà Amir có trong tệp `BUILD` để xem món ăn nào có trong đó.
Kết quả của lệnh bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)' cho thấy Amir là khách hàng duy nhất đã đặt pizza và là người đánh giá cho chúng ta câu trả lời.
Kết thúc
Xin chúc mừng! Giờ đây, bạn đã chạy một số truy vấn cơ bản mà bạn có thể thử trên các dự án của riêng mình. Để tìm hiểu thêm về cú pháp ngôn ngữ truy vấn, hãy tham khảo Trang tham khảo về truy vấn. Bạn muốn tìm hiểu thêm về các truy vấn nâng cao? Hướng dẫn về truy vấn trình bày danh sách chi tiết về nhiều trường hợp sử dụng hơn so với những trường hợp được đề cập trong hướng dẫn này.