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 để khai thác 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 nhằm cho phép tính song song và tăng dần.
- Để đóng gói các phần phụ thuộc một cách hiệu quả.
- Để tạo mã có cấu trúc hợp lý và có thể kiểm thử.
- Để tạo một cấu hình bản dựng dễ hiểu và dễ duy trì.
Đây không phải là các yêu cầu: rất ít dự án có thể tuân thủ tất cả các nguyên tắc này. Như trang man cho trình tìm lỗi mã nguồn cho biết, "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 tạo ra lỗi nào 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 thành công bazel build //... và bazel test //... trên nhánh ổn định. Các mục tiêu cần thiết nhưng không tạo được trong một số trường hợp (chẳng hạn như yêu cầu cờ bản dựng cụ thể, không tạo được trên một nền tảng cụ thể, yêu cầu thoả thuận cấp phép) phải được gắn thẻ càng cụ thể càng tốt (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 nào đó kiểm tra tệp BUILD để hiểu các quy tắ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 kho lưu trữ này dưới dạng kho lưu trữ từ xa trong tệp
MODULE.bazel. - Hoặc đặt các tệp đó vào thư mục có tên
third_party/trong thư mục không gian làm việc.
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ể. Nói chung, điều này có nghĩa là thay vì phụ thuộc vào thư viện some-library.so, bạn sẽ tạo một tệp BUILD và tạo some-library.so từ các nguồn của tệp đó, sau đó phụ thuộc vào mục tiêu đó.
Luôn tạo bản dựng từ nguồn đảm bảo rằng 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ấu trúc khác. Ngoài ra, một số tính năng như mức độ sử dụng, 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 tạo tất cả mã từ đầu bất cứ khi nào có thể. Khi phải sử dụng 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). 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, thư viện này cũng có khả năng thích ứng tốt hơn trước các vấn đề về phầ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ì cuối cùng bạn có thể sẽ có 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 workspace/.bazelrc (xem định dạng bazelrc).
Nếu 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 phần 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) 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 bản dựng đều phải là một gói. Nếu tệp BUILD 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 càng tồn tại 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 vô tình, phạm vi của mục tiêu sẽ tăng dần và số lượng phần phụ thuộc đảo ngược sẽ phải được cập nhật ngày càng nhiều.