Mô-đun Rust cho Android

Theo nguyên tắc chung, các định nghĩa mô-đun rust_* tuân thủ chặt chẽ việc sử dụng và kỳ vọng cc_*. Sau đây là ví dụ về định nghĩa mô-đun cho tệp nhị phân Rust:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

Trang này đề cập đến các thuộc tính phổ biến nhất cho các mô-đun rust_*. Để biết thêm thông tin về các loại mô-đun cụ thể và định nghĩa mô-đun mẫu, hãy xem Mô-đun nhị phân, Mô-đun thư viện hoặc Mô-đun kiểm thử.

Các loại mô-đun cơ bản

LoạiĐịnh nghĩaĐể biết thêm thông tin
rust_binaryTệp nhị phân Rust Trang Mô-đun nhị phân
rust_libraryTạo một thư viện Rust và cung cấp cả biến thể rlib và dylib. rust_library, Trang Library Modules (Mô-đun thư viện).
rust_ffiTạo ra một thư viện C Rust mà các mô-đun cc có thể sử dụng, đồng thời cung cấp cả biến thể tĩnh và dùng chung. rust_ffi, Trang Mô-đun thư viện
rust_proc_macroTạo thư viện proc-macro Rust. (Các thành phần này tương tự như trình bổ trợ của trình biên dịch.) rust_proc_macro, Trang Mô-đun thư viện
rust_testTạo một tệp nhị phân kiểm thử Rust sử dụng bộ kiểm thử Rust tiêu chuẩn. Trang Mô-đun kiểm thử
rust_fuzzTạo ra một tệp nhị phân fuzz Rust tận dụng libfuzzer. Ví dụ về mô-đun rust_fuzz
rust_protobufTạo nguồn và tạo một thư viện Rust cung cấp giao diện cho một protobuf cụ thể. Trang Protobufs Modules và Source Generators
rust_bindgenTạo nguồn và tạo một thư viện Rust chứa các liên kết Rust đến các thư viện C. Các mô-đun liên kết Bindgen và các trang Trình tạo nguồn

Các thuộc tính chung quan trọng

Đây là những thuộc tính phổ biến trên tất cả các Mô-đun Rust của Android. Mọi thuộc tính bổ sung (riêng biệt) được liên kết với từng mô-đun Rust sẽ được liệt kê trên trang của mô-đun đó.

tên

name là tên của mô-đun. Giống như các mô-đun Soong khác, mô-đun này phải là duy nhất trên hầu hết các loại mô-đun Android.bp. Theo mặc định, name được dùng làm tên tệp đầu ra. Nếu tên tệp đầu ra phải khác với tên mô-đun, hãy dùng thuộc tính stem để xác định tên tệp đầu ra.

stem

stem (không bắt buộc) cung cấp quyền kiểm soát trực tiếp đối với tên tệp đầu ra (không bao gồm đuôi tệp và các hậu tố khác). Ví dụ: một thư viện rust_library_rlib có giá trị gốc là libfoo sẽ tạo ra một tệp libfoo.rlib. Nếu bạn không cung cấp giá trị cho thuộc tính stem, tên tệp đầu ra sẽ sử dụng tên mô-đun theo mặc định.

Sử dụng hàm stem khi bạn không thể đặt tên mô-đun thành tên tệp đầu ra mong muốn. Ví dụ: rust_library cho thùng log có tên là liblog_rust, vì liblog cc_library đã tồn tại. Trong trường hợp này, việc sử dụng thuộc tính stem đảm bảo rằng tệp đầu ra có tên là liblog.* thay vì liblog_rust.*.

srcs

srcs chứa một tệp nguồn duy nhất đại diện cho điểm truy cập vào mô-đun của bạn (thường là main.rs hoặc lib.rs). rustc xử lý việc phân giải và khám phá tất cả các tệp nguồn khác cần thiết để biên dịch, đồng thời các tệp này được liệt kê trong tệp deps được tạo ra.

Nếu có thể, hãy tránh sử dụng cách này cho mã nền tảng; hãy xem phần Trình tạo nguồn để biết thêm thông tin.

crate_name

crate_name đặt siêu dữ liệu tên thùng thông qua cờ rustc --crate_name. Đối với các mô-đun tạo ra thư viện, phải khớp với tên thùng dự kiến được dùng trong nguồn. Ví dụ: nếu mô-đun libfoo_bar được tham chiếu trong nguồn dưới dạng extern crate foo_bar, thì phải là crate_name: "foo_bar".

Thuộc tính này thường có trong tất cả các mô-đun rust_*, nhưng bắt buộc đối với các mô-đun tạo ra thư viện Rust (chẳng hạn như rust_library, rust_ffi, rust_bindgen, rust_protobuf và rust_proc_macro). Các mô-đun này thực thi các yêu cầu rustc về mối quan hệ giữa crate_name và tên tệp đầu ra. Để biết thêm thông tin, hãy xem phần Mô-đun thư viện.

lints

Trình kiểm tra cú pháp rustc được chạy theo mặc định cho tất cả các loại mô-đun, ngoại trừ trình tạo nguồn. Một số bộ lint được xác định và dùng để xác thực nguồn mô-đun. Các giá trị có thể có cho những bộ kiểm tra như vậy như sau:

  • default bộ lint mặc định, tuỳ thuộc vào vị trí của mô-đun
  • android bộ lint nghiêm ngặt nhất áp dụng cho tất cả mã nền tảng Android
  • vendor một tập hợp các lint được áp dụng cho mã nhà cung cấp
  • none để bỏ qua tất cả các cảnh báo và lỗi lint

clippy_lints

Trình kiểm tra clippy cũng được chạy theo mặc định cho tất cả các loại mô-đun, ngoại trừ trình tạo nguồn. Một số nhóm lint được xác định để dùng xác thực nguồn mô-đun. Dưới đây là một số giá trị có thể có:

  • default tập hợp mặc định các lint tuỳ thuộc vào vị trí của mô-đun
  • android bộ lint nghiêm ngặt nhất áp dụng cho tất cả mã nền tảng Android
  • vendor một tập hợp các lint được áp dụng cho mã nhà cung cấp
  • none để bỏ qua tất cả các cảnh báo và lỗi lint

ấn bản

edition xác định phiên bản Rust sẽ dùng để biên dịch mã này. Điều này tương tự như các phiên bản std cho C và C++. Các giá trị hợp lệ là 2015, 2018 và 2021 (mặc định).

flags

flags chứa danh sách chuỗi gồm các cờ để truyền đến rustc trong quá trình biên dịch.

ld_flags

ld-flags chứa danh sách chuỗi gồm các cờ để truyền đến trình liên kết khi biên dịch nguồn. Các cờ này được truyền bằng cờ -C linker-args rustc. clang được dùng làm giao diện người dùng trình liên kết, gọi lld để liên kết thực tế.

tính năng

features là danh sách chuỗi gồm các tính năng phải được bật trong quá trình biên dịch. Thông tin này được --cfg 'feature="foo"' truyền đến rustc. Hầu hết các tính năng đều mang tính bổ sung, vì vậy, trong nhiều trường hợp, điều này bao gồm toàn bộ bộ tính năng mà tất cả các mô-đun phụ thuộc đều yêu cầu. Tuy nhiên, trong trường hợp các tính năng loại trừ lẫn nhau, hãy xác định các mô-đun bổ sung trong mọi tệp bản dựng cung cấp các tính năng xung đột.

cfgs

cfgs chứa danh sách chuỗi gồm các cờ cfg sẽ được bật trong quá trình biên dịch. Tham số này được truyền đến rustc bằng --cfg foo và --cfg "fizz=buzz".

Hệ thống xây dựng sẽ tự động đặt một số cờ cfg trong một số trường hợp cụ thể, được liệt kê dưới đây:

  • Các mô-đun được tạo dưới dạng dylib sẽ có android_dylib cfg được đặt.

  • Các mô-đun sẽ sử dụng VNDK sẽ có cfg android_vndk được đặt. Điều này tương tự như định nghĩa __ANDROID_VNDK__ cho C++.

dải

strip kiểm soát việc tệp đầu ra có bị xoá hay không và cách xoá (nếu có). Nếu bạn không đặt giá trị này, các mô-đun thiết bị sẽ mặc định loại bỏ mọi thứ, ngoại trừ thông tin gỡ lỗi thu nhỏ. Theo mặc định, các mô-đun máy chủ lưu trữ không loại bỏ bất kỳ biểu tượng nào. Các giá trị hợp lệ bao gồm none để tắt tính năng loại bỏ và all để loại bỏ mọi thứ, kể cả mini debuginfo. Bạn có thể tìm thấy các giá trị bổ sung trong Tài liệu tham khảo về các mô-đun Soong.

host_supported

Đối với các mô-đun thiết bị, tham số host_supported cho biết liệu mô-đun cũng nên cung cấp một biến thể máy chủ hay không.

Xác định phần phụ thuộc của thư viện

Các mô-đun Rust có thể phụ thuộc vào cả thư viện CC và Rust thông qua các thuộc tính sau:

Tên thuộc tính Mô tả
rustlibs Danh sách các mô-đun rust_library cũng là các phần phụ thuộc. Hãy dùng phương thức này làm phương thức khai báo phần phụ thuộc mà bạn muốn, vì phương thức này cho phép hệ thống xây dựng chọn mối liên kết mà bạn muốn. (Xem phần Khi liên kết với các thư viện Rust bên dưới)
rlibs Danh sách các mô-đun rust_library phải được liên kết tĩnh dưới dạng rlibs. (Hãy thận trọng khi sử dụng; xem phần Khi liên kết với các thư viện Rust bên dưới.)
shared_libs Danh sách các mô-đun cc_library phải được liên kết động dưới dạng thư viện dùng chung.
static_libs Danh sách các mô-đun cc_library phải được liên kết tĩnh dưới dạng thư viện tĩnh.
whole_static_libs Danh sách các mô-đun cc_library phải được liên kết tĩnh dưới dạng thư viện tĩnh và được đưa toàn bộ vào thư viện thu được. Đối với các biến thể rust_ffi_static, whole_static_libraries sẽ được đưa vào kho lưu trữ thư viện tĩnh kết quả. Đối với các biến thể rust_library_rlib, các thư viện whole_static_libraries sẽ được kết hợp thành thư viện rlib thu được.

Khi liên kết với các thư viện Rust, theo phương pháp hay nhất, hãy thực hiện việc này bằng cách sử dụng thuộc tính rustlibs thay vì rlibs hoặc dylibs trừ phi bạn có lý do cụ thể để làm như vậy. Điều này cho phép hệ thống xây dựng chọn mối liên kết chính xác dựa trên yêu cầu của mô-đun gốc và giảm khả năng cây phần phụ thuộc chứa cả phiên bản rlib và dylib của một thư viện (điều này sẽ khiến quá trình biên dịch không thành công).

Các tính năng bản dựng không được hỗ trợ và được hỗ trợ có giới hạn

Rust của Soong chỉ hỗ trợ một số hình ảnh và ảnh chụp nhanh vendor và vendor_ramdisk. Tuy nhiên, staticlibs, cdylibs, rlibs và binaries được hỗ trợ. Đối với các mục tiêu tạo hình ảnh của nhà cung cấp, thuộc tính android_vndk cfg được đặt. Bạn có thể sử dụng tham số này trong mã nếu có sự khác biệt giữa mục tiêu hệ thống và mục tiêu của nhà cung cấp. rust_proc_macros không được ghi lại trong ảnh chụp nhanh của nhà cung cấp; nếu bạn phụ thuộc vào các tệp này, hãy đảm bảo bạn kiểm soát phiên bản một cách thích hợp.

Không hỗ trợ hình ảnh Sản phẩm, VNDK và Khôi phục.

Bản dựng gia tăng

Nhà phát triển có thể bật tính năng biên dịch gia tăng của nguồn Rust bằng cách đặt biến môi trường SOONG_RUSTC_INCREMENTAL thành true.

Cảnh báo: Không có gì đảm bảo rằng thao tác này sẽ tạo ra các tệp nhị phân giống hệt như các tệp nhị phân do buildbot tạo. Địa chỉ của các hàm hoặc dữ liệu có trong tệp đối tượng có thể khác nhau. Để đảm bảo rằng các cấu phần phần mềm được tạo giống hệt 100% với các cấu phần phần mềm do cơ sở hạ tầng EngProd tạo, hãy để giá trị này chưa được đặt.