Trang này giả định rằng bạn đã quen thuộc với Bazel và cung cấp các nguyên tắc cũng như lời khuyên về cách cấu trúc dự án để tận dụng tối đa các tính năng của Bazel.
Các mục tiêu tổng thể là:
- Sử dụng các phần phụ thuộc chi tiết để cho phép tính song song và tính tăng dần.
- Giữ các phần phụ thuộc được đóng gói kỹ.
- Giúp mã có cấu trúc rõ ràng và có thể kiểm thử.
- Tạo cấu hình bản dựng dễ hiểu và duy trì.
Đây không phải là các nguyên tắc bắt buộc: ít dự án có thể tuân thủ tất cả các nguyên tắc này. Như trang hướng dẫn sử dụng cho lint có nói: "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 tế không có lỗi khi kiểm tra nghiêm ngặt". Tuy nhiên, việc kết hợp càng nhiều nguyên tắc này càng tốt sẽ giúp dự án dễ đọc hơn, ít gặp lỗi hơn 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 bazel build //... và bazel test //... thành công trên nhánh ổn định của dự án. Các mục tiêu cần thiết nhưng không xây dựng được trong một số trường hợp (chẳng hạn như yêu cầu các cờ bản dựng cụ thể, không xây dựng trên một nền tảng nhất định, yêu cầu thoả thuận cấp phép) phải được gắn thẻ cụ thể nhất có thể (ví dụ: "requires-osx"). Việc gắn 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 kiểm tra tệp BUILD hiểu được các 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:
- Khai báo các phần phụ thuộc này dưới dạng kho lưu trữ từ xa trong tệp
MODULE.bazel. - Hoặc đặt các phần phụ thuộc này vào một thư mục có tên là
third_party/trong thư mục không gian làm việc.
Phụ thuộc vào tệp nhị phân
Bạn nên xây dựng mọi thứ từ nguồn bất cứ khi nào có thể. Thông thường, đ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 một tệp BUILD và xây dựng some-library.so từ các nguồn của tệp đó, sau đó phụ thuộc vào mục tiêu đó.
Việc luôn xây dựng từ nguồn đảm bảo rằng bản dựng không sử dụng một thư viện được xây dựng bằng các cờ không tương thích hoặc một kiến trúc khác. Ngoài ra, có một số tính năng như mức độ 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
Bạn nê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, không phải //guava-20.0). Việc đặt tên này giúp bạn dễ dàng cập nhật thư viện hơn (chỉ cần cập nhật một mục tiêu). Việc này cũng giúp khắc phục tốt hơn các vấn đề về phần phụ thuộc hình 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ể kết thúc bằng một 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
Đối với các tuỳ chọn dành riêng cho dự án, hãy sử dụng tệp cấu hình your
workspace/.bazelrc (xem định dạng bazelrc).
Nếu bạn muốn hỗ trợ các tuỳ chọn cho mỗi người dùng đối với dự án mà bạn không muốn kiểm tra vào hệ thống kiểm soát nguồn, hãy thêm dòng:
try-import %workspace%/user.bazelrc
(hoặc bất kỳ tên tệp nào khác) vào workspace/.bazelrc
và thêm user.bazelrc vào .gitignore.
tạo một tệp bazelrc tuỳ chỉnh khớp với phiên bản Bazel của bạn và cung cấp một bộ cờ được đề xuất đặt sẵn.
Gói
Mọi thư mục chứa các tệp có thể xây dựng đều phải là một gói. Nếu một BUILD
tệp tham chiếu đế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 tồn tại càng lâu thì càng có nhiều khả năng các phần phụ thuộc vòng tròn sẽ được tạo ra một cách vô tình, phạm vi của mục tiêu sẽ tăng lên và ngày càng có nhiều phần phụ thuộc ngược phải được cập nhật.