Trang này giả định rằng bạn đã quen thuộc với Bazel, đồng thời đưa ra các nguyên tắc và lời khuyên về cách xây dựng cấu trúc cho 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 nhằm cho phép áp dụng song song và gia tăng.
- Để các phần phụ thuộc được đóng gói hợp lý.
- Giúp 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ễ bảo trì.
Những nguyên tắc này không phải là yêu cầu bắt buộc: có một vài dự án có thể tuân thủ tất cả những nguyên tắc này. Như trang man cho lint (tìm lỗi mã nguồn) có nội dung: "Một phần thưởng đặc biệt sẽ được trao cho người đầu tiên sản xuất 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 nhiều nguyên tắc này nhất có thể sẽ giúp dự án dễ đọc hơn, ít xảy ra lỗi hơn và nhanh hơn khi xây dựng.
Trang này áp dụng các cấp yêu cầu như mô tả trong RFC này.
Chạy bản dựng và kiểm thử
Một dự án phải luôn chạy bazel build //... và bazel test //... thành công trên nhánh ổn định của nó. Các mục tiêu cần thiết nhưng không được tạo 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 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àng cụ thể càng tốt (ví dụ: "requires-osx"). Phương thức gắn thẻ này cho phép lọ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 nào đó kiểm tra tệp BUILD để nắm được các hạn chế của mục tiêu là gì.
Phần phụ thuộc 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 là kho lưu trữ từ xa trong tệp
WORKSPACE. - Hoặc đặt các tệp đó trong thư mục có tên là
third_party/trong thư mục không gian làm việc.
Tuỳ thuộc vào tệp nhị phân
Bạn phải xây dựng mọi thứ 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 thư viện some-library.so, bạn nên 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 bản dựng từ nguồn sẽ đả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òn có 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 dựa trên nguồn.
Lập phiên bản
Ưu tiên tạo toàn bộ 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). Thư viện này cũng thích ứng hơn với các vấn đề về phần phụ thuộc của 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ể tạo ra 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
Để biết 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 bạn muốn hỗ trợ các tuỳ chọn cho mỗi người dùng cho dự án của mình nhưng bạn không muốn kiểm tra quyề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 các tệp có thể tạo phải là một gói. Nếu một 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 vô tình tạo các phần phụ thuộc tuần hoàn, phạm vi của mục tiêu sẽ lớn dần và số lượng phần phụ thuộc đảo ngược tăng lên sẽ phải được cập nhật.