Trang này giả định rằng bạn đã quen thuộc với Bazel và hướng dẫn cũng như đưa ra cấu trúc cho các dự án để tận dụng tối đa các tính năng của Bazel.
Mục tiêu tổng thể là:
- Sử dụng các phần phụ thuộc chi tiết để cho phép sử dụng song song và mức độ gia tăng.
- Để đảm bảo các phần phụ thuộc được đóng gói kỹ lưỡng.
- Để mã có cấu trúc rõ ràng và có thể kiểm thử được.
- Tạo một cấu hình xây dựng dễ hiểu và dễ duy trì.
Những nguyên tắc này không bắt buộc: một số dự án có thể tuân thủ tất cả nguyên tắc này. Như trang người đàn ông cho tìm lỗi mã nguồn, "Một phần thưởng đặc biệt sẽ được trao cho người đầu tiên tạo ra một chương trình thực sự không gây ra lỗi khi kiểm tra nghiêm ngặt". Tuy nhiên, việc áp dụng nhiều nguyên tắc nhất có thể sẽ giúp dự án dễ đọc hơn, ít xảy ra lỗi và xây dựng nhanh hơn.
Trang này sử dụng các cấp độ yêu cầu được mô tả trong RFC này.
Chạy bản dựng và kiểm thử
Một dự án phải luôn có thể chạy thành công bazel build //... và bazel test //... trên nhánh ổn định của dự án đó. Bạn nên gắn thẻ mục tiêu cần thiết
nhưng không xây dựng trong một số trường hợp nhất định (chẳng hạn như yêu cầu cờ bản dựng cụ thể, không tạo trên một nền tảng nhất định, yêu cầu thỏa thuận cấp phép)
chẳng hạn (ví dụ: "requires-osx"). Thẻ
này cho phép lọc các mục tiêu ở cấp chi tiết hơn so với
thẻ "thủ công" và cho phép người dùng kiểm tra tệp BUILD để hiểu rõ các quy định hạn chế của
mục tiêu.
Phần phụ thuộc của bên thứ ba
Bạn có thể khai báo các phần phụ thuộc của bên thứ ba:
- Hãy khai báo các tệp này là kho lưu trữ từ xa trong tệp
WORKSPACE. - Bạn cũng có thể đặt các tệp này vào một thư mục có tên
third_party/trong thư mục Workspace của bạn.
Tuỳ thuộc vào tệp nhị phân
Mọi thứ phải được xây dựng từ nguồn bất cứ khi nào có thể. Nhìn chung, điều này có nghĩa là, thay vì phụ thuộc vào một thư viện some-library.so, bạn sẽ tạo tệp BUILD và tạo some-library.so từ các nguồn của thư viện, sau đó phụ thuộc vào mục tiêu đó.
Việc luôn tạo từ nguồn sẽ đảm bảo bản dựng không sử dụng thư viện được tạo bằng các cờ không tương thích hoặc có cấu trúc khác. Ngoài ra, còn có một số tính năng như phạm vi bao phủ, phân tích tĩnh hoặc phân tích động chỉ hoạt động trên nguồn.
Lập phiên bản.
Ưu tiên xây dựng tất cả mã từ đầu bất cứ khi nào có thể. Khi phải sử dụng các phiên bản, hãy tránh đưa phiên bản vào tên mục tiêu (ví dụ: //guava chứ không phải //guava-20.0). Cách đặt tên này giúp thư viện dễ cập nhật hơn (chỉ cần cập nhật một mục tiêu). Ngoài ra còn linh hoạt hơn về các vấn đề phụ thuộc kim cương: nếu một thư viện phụ thuộc vào guava-19.0 và một thư viện phụ thuộc vào guava-20.0, thì bạn có thể gặp phải thư viện cố gắng phụ thuộc vào hai phiên bản khác nhau.
Nếu bạn đã tạo một bí danh gây hiểu lầm để trỏ cả hai mục tiêu đến một thư viện guava, thì các tệp BUILD sẽ gây hiểu lầm.
Sử dụng tệp .bazelrc
Để biết các tùy chọn dành riêng cho dự án, hãy sử dụng tệp cấu hình workspace/.bazelrc của bạn (xem định dạng Brazil).
Nếu bạn muốn hỗ trợ các tuỳ chọn cho mỗi người dùng cho dự án mà bạn không muốn kiểm tra mã nguồn, hãy thêm dòng sau:
try-import %workspace%/user.bazelrc
(hoặc tên tệp khác) trong workspace/.bazelrc
và thêm user.bazelrc vào .gitignore.
Gói
Mọi thư mục chứa tệp có thể tạo phải là một gói. Nếu tệp BUILD đề cập đến các tệp trong thư mục con (chẳng hạn như srcs = ["a/b/C.java"]), thì đó là dấu hiệu cho thấy bạn nên thêm tệp BUILD vào thư mục con đó. Cấu trúc này càng tồn tại lâu thì càng có nhiều khả năng tạo ra các phần phụ thuộc hình tròn vô tình, phạm vi của mục tiêu sẽ tăng lên, và số lượng phần phụ thuộc đảo ngược ngày càng tăng sẽ phải được cập nhật.