Theo thiết kế, các tệp Android.bp rất đơn giản. Các tệp này không chứa câu lệnh có điều kiện hoặc câu lệnh luồng điều khiển; tất cả độ phức tạp đều do logic bản dựng được viết bằng Go xử lý.
Mô-đun
Một mô-đun trong tệp Android.bp bắt đầu bằng một loại mô-đun, tiếp theo là một tập hợp các
thuộc tính ở định dạng name: "value",:
cc_binary {
name: "gzip",
srcs: ["src/test/minigzip.c"],
shared_libs: ["libz"],
stl: "none",
}
Mỗi mô-đun phải có một thuộc tính name và giá trị phải là duy nhất trên tất cả các tệp Android.bp, ngoại trừ các giá trị thuộc tính name trong không gian tên và mô-đun tạo sẵn, có thể lặp lại.
Thuộc tính srcs chỉ định các tệp nguồn dùng để tạo mô-đun, dưới dạng danh sách chuỗi. Bạn có thể tham chiếu đầu ra của các mô-đun khác tạo ra
tệp nguồn, chẳng hạn như genrule hoặc filegroup, bằng cách sử dụng cú pháp tham chiếu mô-đun
":<module-name>".
Để xem danh sách các loại mô-đun hợp lệ và thuộc tính của chúng, hãy xem Tài liệu tham khảo về mô-đun Soong được tạo bằng cách chạy m soong_docs. Đầu ra sẽ ở trong out/soong/docs/soong_build.html.
Loại
Các biến và thuộc tính được nhập mạnh, với các biến được nhập động dựa trên lần gán đầu tiên và các thuộc tính được đặt tĩnh theo loại mô-đun. Các loại được hỗ trợ là:
- Boolean (
truehoặcfalse) - Số nguyên (
int) - Chuỗi (
"string") - Danh sách chuỗi (
["string1", "string2"]) - Bản đồ (
{key1: "value1", key2: ["value2"]})
Bản đồ có thể chứa các giá trị thuộc bất kỳ loại nào, bao gồm cả bản đồ lồng nhau. Danh sách và bản đồ có thể có dấu phẩy ở cuối sau giá trị cuối cùng.
Glob
Các thuộc tính lấy danh sách tệp, chẳng hạn như srcs, cũng có thể lấy các mẫu glob. Các mẫu glob có thể chứa ký tự đại diện UNIX thông thường *, ví dụ
*.java. Các mẫu glob cũng có thể chứa một ký tự đại diện ** duy nhất làm phần tử đường dẫn, khớp với 0 hoặc nhiều phần tử đường dẫn. Ví dụ: java/**/*.java khớp với cả mẫu java/Main.java và java/com/android/Main.java.
Biến
Tệp Android.bp có thể chứa các phép gán biến cấp cao nhất:
gzip_srcs = ["src/test/minigzip.c"],
cc_binary {
name: "gzip",
srcs: gzip_srcs,
shared_libs: ["libz"],
stl: "none",
}
Các biến được giới hạn trong phần còn lại của tệp mà chúng được khai báo, cũng như mọi tệp Blueprint con. Các biến là bất biến với một ngoại lệ: chúng có thể được thêm vào bằng phép gán +=, nhưng chỉ trước khi chúng được tham chiếu.
Bình luận
Các tệp Android.bp có thể chứa nhận xét nhiều dòng theo kiểu C /* */ và nhận xét một dòng theo kiểu C++ //.
Toán tử
Bạn có thể thêm chuỗi, danh sách chuỗi và bản đồ bằng toán tử +.
Bạn có thể cộng các số nguyên bằng toán tử +. Việc thêm bản đồ sẽ tạo ra hợp nhất các khoá trong cả hai bản đồ, thêm các giá trị của mọi khoá có trong cả hai bản đồ.
Mô-đun mặc định
Nhà phát triển có thể sử dụng mô-đun mặc định để lặp lại các thuộc tính giống nhau trong nhiều mô-đun. Ví dụ:
cc_defaults {
name: "gzip_defaults",
shared_libs: ["libz"],
stl: "none",
}
cc_binary {
name: "gzip",
defaults: ["gzip_defaults"],
srcs: ["src/test/minigzip.c"],
}
Mô-đun tạo sẵn
Một số loại mô-đun tạo sẵn cho phép mô-đun có cùng tên với các đối tượng dựa trên nguồn. Ví dụ: có thể có một cc_prebuilt_binary có tên là foo khi đã có một cc_binary có cùng tên. Điều này giúp nhà phát triển linh hoạt chọn phiên bản để đưa vào sản phẩm cuối cùng của họ. Nếu cấu hình bản dựng chứa cả hai phiên bản, thì giá trị cờ prefer trong định nghĩa mô-đun tạo sẵn sẽ quyết định phiên bản nào được ưu tiên.
Xin lưu ý rằng một số mô-đun tạo sẵn có tên không bắt đầu bằng prebuilt, chẳng hạn như android_app_import.
Mô-đun không gian tên
Cho đến khi Android chuyển đổi hoàn toàn từ Make sang Soong, cấu hình sản phẩm Make phải chỉ định giá trị PRODUCT_SOONG_NAMESPACES. Giá trị của nó phải là danh sách các không gian tên được phân tách bằng dấu cách mà Soong xuất sang Make để được tạo bằng lệnh m. Sau khi quá trình chuyển đổi của Android sang Soong hoàn tất, thông tin chi tiết về việc bật không gian tên có thể thay đổi.
Soong cung cấp khả năng cho các mô-đun trong các thư mục khác nhau chỉ định cùng một tên, miễn là mỗi mô-đun được khai báo trong một không gian tên riêng biệt. Nhà phát triển có thể khai báo không gian tên:
soong_namespace {
imports: ["path/to/otherNamespace1", "path/to/otherNamespace2"],
}
Xin lưu ý rằng không gian tên không có thuộc tính name; đường dẫn của nó sẽ tự động được gán làm tên.
Mỗi mô-đun Soong được gán một không gian tên dựa trên vị trí của nó trong cây.
Mỗi mô-đun Soong được coi là nằm trong không gian tên do soong_namespace xác định trong tệp Android.bp trong thư mục hiện tại hoặc thư mục tổ tiên gần nhất. Nếu không tìm thấy mô-đun soong_namespace nào như vậy, thì mô-đun đó được coi là nằm trong không gian tên gốc ngầm ẩn.
Sau đây là một ví dụ: Soong cố gắng phân giải phần phụ thuộc D do mô-đun M khai báo trong không gian tên N nhập các không gian tên I1, I2, I3…
- Sau đó, nếu D là tên đủ điều kiện của biểu mẫu
//namespace:module, thì chỉ không gian tên được chỉ định mới được tìm kiếm tên mô-đun được chỉ định. - Nếu không, Soong sẽ tìm một mô-đun có tên là D được khai báo trong không gian tên N.
- Nếu mô-đun đó không tồn tại, Soong sẽ tìm một mô-đun có tên là D trong các không gian tên I1, I2, I3…
- Soong tìm trong không gian tên gốc.
Điều kiện
Soong không hỗ trợ các điều kiện trong tệp Android.bp. Thay vào đó, độ phức tạp trong các quy tắc bản dựng yêu cầu các điều kiện được xử lý trong Go, nơi có thể sử dụng các tính năng ngôn ngữ cấp cao và có thể theo dõi các phần phụ thuộc ngầm ẩn do các điều kiện đưa ra. Hầu hết các điều kiện được chuyển đổi thành thuộc tính bản đồ, trong đó một trong các giá trị trong bản đồ được chọn và thêm vào các thuộc tính cấp cao nhất.
Ví dụ: để hỗ trợ các tệp dành riêng cho cấu trúc:
cc_library {
...
srcs: ["generic.cpp"],
arch: {
arm: {
srcs: ["arm.cpp"],
},
x86: {
srcs: ["x86.cpp"],
},
},
}
Trình định dạng
Soong bao gồm một trình định dạng chính tắc cho các tệp Blueprint, tương tự như
gofmt. Để định dạng lại đệ quy tất cả các tệp Android.bp trong thư mục hiện tại, hãy chạy:
bpfmt -w .
Định dạng chính tắc bao gồm thụt lề 4 dấu cách, dòng mới sau mỗi phần tử của danh sách nhiều phần tử và dấu phẩy ở cuối trong danh sách và bản đồ.