Kể từ ngày 27 tháng 3 năm 2025, bạn nên sử dụng android-latest-release thay vì aosp-main để xây dựng và đóng góp cho AOSP. Để biết thêm thông tin, hãy xem phần Thay đổi đối với AOSP.

Trang này được dịch bởi Cloud Translation API.

Mô-đun Rust cho Android

Theo nguyên tắc chung, định nghĩa mô-đun rust_* tuân thủ chặt chẽ Mức sử dụng và kỳ vọng về cc_*. Sau đây là ví dụ về một mô-đun định nghĩa 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 trình bày các thuộc tính phổ biến nhất cho 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 phần 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_binary`	Tệp nhị phân Rust	Mô-đun nhị phân trang
`rust_library`	Tạo thư viện Rust và cung cấp cả biến thể `rlib` và `dylib`.	`rust_library`, Trang Mô-đun thư viện.
`rust_ffi`	Tạo thư viện Rust C để cc có thể sử dụng các mô-đun, đồng thời cung cấp cả biến thể tĩnh và biến thể dùng chung.	`rust_ffi`, Trang Mô-đun thư viện
`rust_proc_macro`	Tạo thư viện Rust `proc-macro`. (Đây là các trình bổ trợ tương tự như trình bổ trợ biên dịch.)	`rust_proc_macro`, Trang Mô-đun thư viện
`rust_test`	Tạ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 Test Modules (Kiểm thử mô-đun)
`rust_fuzz`	Tạo ra một tệp nhị phân kiểm thử mờ Rust `libfuzzer`.	Ví dụ về mô-đun `rust_fuzz`
`rust_protobuf`	Tạo nguồn và tạo thư viện Rust cung cấp giao diện cho một protobuf cụ thể.	Các trang Protobufs Modules (Mô-đun Protobuf) và Source Generators (Trình tạo nguồn)
`rust_bindgen`	Tạo nguồn và tạo thư viện Rust chứa các liên kết Rust đến thư viện C.	Trang Mô-đun liên kết Bindgen và Trình tạo nguồn

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

Những thuộc tính này phổ biến trên tất cả Android Rust Mô-đun. Mọi thuộc tính bổ sung (riêng biệt) 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 mô-đun của bạn. 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 dữ liệu đầu ra tên tệp. Nếu tên tệp đầu ra phải khác với tên mô-đun, hãy sử dụng thuộc tính stem để xác định tên tệp đó.

thân

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ụ: rust_library_rlib thư viện có giá trị gốc là libfoo sẽ tạo ra tệp libfoo.rlib. Nếu bạn không cung cấp giá trị cho thuộc tính stem, thì 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 vùng chứa log được đặt tên là liblog_rust, vì liblog cc_library đã tồn tại. Việc sử dụng thuộc tính stem trong trường hợp này đảm bảo rằng tệp đầu ra được đặt tên là liblog.* thay vì liblog_rust.*.

src

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 (thường là main.rs hoặc lib.rs). rustc xử lý độ 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, và các tệp này được liệt kê trong tệp deps được tạo.

Lưu ý: srcs cũng xử lý nguồn được tạo được tham chiếu bởi macro include!. Các nguồn này phải do một mô-đun khác cung cấp (chẳng hạn như genrule hoặc rust_protobuf, v.v.). Để đưa nguồn vào, hãy thêm tên của mô-đun đang cung cấp nguồn đã tạo vào srcs và đặt tiền tố là :. (Ví dụ: ":libmyproto". Tệp nguồn chính phải là mục nhập đầu tiên trong mảng khi sử dụng chức năng.

Khi 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.

tên_ thùng

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

Thuộc tính này dùng chung cho tất cả mô-đun rust_*, nhưng lại bắt buộc đối với các mô-đun tạo ra các thư viện Rust (chẳng hạn như rust_library rust_ffi, rust_bindgen, rust_protobuf và rust_proc_macro). Các các mô-đun 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.

tìm lỗi mã nguồn

Trình tìm lỗi mã nguồn 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ố nhóm tìm lỗi mã nguồn được xác định và sử dụng để xác thực nguồn mô-đun. Các giá trị có thể có cho các nhóm tìm lỗi mã nguồn như sau:

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

clippy_lint

Trình tìm lỗi mã nguồn clippy cũng 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 lints đượ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ó:

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

ấn bản

edition xác định phiên bản Rust để sử dụng cho việc 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 và 2018 (mặc định).

flags

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

ld_flags

ld-flags chứa danh sách chuỗi cờ để truyền đến trình liên kết khi biên dịch nguồn. Các giá trị này được truyền bằng cờ rustc -C linker-args. clang được dùng làm giao diện người dùng của 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 các tính năng phải được bật trong quá trình biên dịch. Giá trị này được truyền đến rustc bằng --cfg 'feature="foo"'. 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, bộ tính năng này bao gồm toàn bộ các tính năng được yêu cầu bởi tất cả các mô-đun. Tuy nhiên, trong trường hợp các tính năng độc quyền với nhau, 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 được bật trong quá trình biên dịch. Dữ liệu này được --cfg foo và --cfg "fizz=buzz" truyền cho rustc.

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

Các mô-đun được tạo dưới dạng dylib sẽ có tập hợp cfg android_dylib.
Các mô-đun sử dụng VNDK sẽ có tập hợp CPG android_vndk. Đây là tương tự như __ANDROID_VNDK__ định nghĩa cho C++.

dải

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

máy chủ_hỗ trợ

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

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

Mô-đun Rust có thể phụ thuộc vào cả CC và Thư viện 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à phần phụ thuộc. Hãy sử 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 ưu tiên. (Xem phần Khi liên kết với 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 Khi liên kết dựa trên 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` nên ở dạng tĩnh được liên kết dưới dạng thư viện tĩnh và đưa toàn bộ vào thư viện thu được. Để `rust_ffi_static` biến thể, `whole_static_libraries` sẽ được đưa vào kết quả là tệp lưu trữ thư viện tĩnh. Đối với `rust_library_rlib` biến thể, Các thư viện `whole_static_libraries` sẽ được nhóm vào `rlib` thu được thư viện của bạn. Lưu ý: Điều này sẽ ngăn bạn khai báo lại phần phụ thuộc cho thư viện này. Tuy nhiên, trong một số trường hợp điều này có thể gây ra hiện tượng cồng kềnh nếu thư viện tĩnh bị trùng lặp trong một phần phụ thuộc cây xanh. Toàn bộ thư viện tĩnh trong "rlibs" sẽ được đưa vào hoàn toàn trong "dylibs" phụ thuộc, gây ra một nguồn tiềm ẩn khác.

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

Các tính năng xây dựng hỗ trợ không được hỗ trợ và bị hạn chế

Rust của Soong hỗ trợ hạn chế cho 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 mục tiêu bản dựng hình ảnh của nhà cung cấp, thuộc tính android_vndk cfg sẽ được đặt. Bạn có thể sử dụng thông số này trong mã nếu có sự khác biệt giữa mục tiêu của hệ thống và 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 các tệp này phụ thuộc vào nhau, hãy đảm bảo bạn kiểm soát phiên bản của các tệp đó một cách thích hợp.

Hình ảnh sản phẩm, VNDK và hình ảnh khôi phục không được hỗ trợ.

Bản dựng tăng dần

Nhà phát triển có thể cho phép quá trình biên dịch dần dần Nguồn Rust bằng cách đặt SOONG_RUSTC_INCREMENTAL biến môi trường thành true.

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