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 gia tăng.
- Để giữ các phần phụ thuộc được đóng gói đúng cách.
- Để 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 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, "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 xảy ra 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. Những mục tiêu cần thiết nhưng không được tạo trong một số trường hợp (chẳng hạn như yêu cầu các cờ tạo cụ thể, không tạo 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 ở mức độ 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:
- Hoặc khai báo chúng dưới dạng kho lưu trữ từ xa trong tệp
MODULE.bazel. - Hoặc đặt các tệp đó vào một thư mục có tên là
third_party/trong thư mục không gian làm việc của bạn.
Tuỳ thuộc vào các tệp nhị phân
Mọi thứ nên được tạo 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à tạo 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 tạo 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 một cấu trúc khác. Ngoài ra, có một số tính năng như mức độ phù hợp, 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 việc tạo tất cả mã từ phần đầu bất cứ khi nào có thể. Khi phải 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). Cách đặt tên này giúp bạn dễ dàng cập nhật thư viện (chỉ cần cập nhật một mục tiêu). Thư viện này cũng có khả năng phục hồi tốt hơn đối với 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ể gặp phải một thư viện cố gắng phụ thuộc vào 2 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 lựa 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 bạn muốn hỗ trợ các lựa chọn cho từng người dùng cho dự án mà bạn không muốn kiểm tra quyền kiểm soát nguồn, hãy thêm dòng sau:
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.
bazelrc-preset.bzl mã nguồn mở{: .external} sẽ tạo một tệp bazelrc tuỳ chỉnh phù hợp với phiên bản Bazel của bạn và cung cấp một nhóm cờ đặt sẵn được đề xuất.
Gói
Mỗi thư mục chứa các tệp có thể tạo đều phải là một gói. Nếu một 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 một 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 theo chu kỳ sẽ vô tình được tạo ra, 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 đảo ngược phải được cập nhật.