Có 2 loại mô-đun thư viện Rust, một loại tạo ra các thư viện Rust và một loại tạo ra các thư viện tương thích với C. Ngoài ra, vì mục đích của hệ thống bản dựng, bạn có thể coi macro theo quy trình Rust (proc-macros) là một loại thư viện đặc biệt.
rust_library
Mô-đun rust_library tạo ra các thư viện Rust để các mô-đun Rust khác sử dụng.
Ngoài các biến thể _host, các thư viện Rust còn có các loại mô-đun kiểm soát mối liên kết có sẵn.
| Loại mô-đun thư viện Rust | Định nghĩa |
|---|---|
| rust_library | Cung cấp cả hai biến thể thư viện, rlib và dylib. AOSP đề xuất loại mô-đun này cho các thư viện Rust, vì loại mô-đun này cho phép các mô-đun hoạt động đúng cách khi được liệt kê dưới dạng một phần phụ thuộc trong thuộc tính rustlibs |
| rust_library_rlib | Chỉ cung cấp biến thể rlib của một thư viện Rust; các mô-đun chỉ cung cấp biến thể rlib không đảm bảo hoạt động với thuộc tính rustlibs. |
| rust_library_dylib | Chỉ cung cấp biến thể dylib của một thư viện Rust; không thể đảm bảo các mô-đun chỉ cung cấp biến thể dylib sẽ hoạt động với thuộc tính rustlibs. |
rust_ffi
Mô-đun rust_ffi tạo ra các thư viện tương thích với C để tương tác với các mô-đun CC.
Ngoài các biến thể _host, thư viện Rust FFI còn có các loại mô-đun kiểm soát mối liên kết có sẵn, như trong bảng sau.
| Loại mô-đun thư viện FFI Rust | Định nghĩa |
|---|---|
| rust_ffi | Cung cấp cả hai biến thể thư viện C: tĩnh và dùng chung. |
| rust_ffi_shared | Chỉ cung cấp biến thể thư viện dùng chung C. |
| rust_ffi_static | Chỉ cung cấp biến thể thư viện tĩnh C. |
Để xem ví dụ cơ bản về cách sử dụng rust_ffi để gọi Rust từ C, hãy xem trang Các mẫu Rust trên Android.
Để biết thông tin về cách sử dụng nâng cao hơn, hãy truy cập vào tài liệu chính thức về Rust.
rust_proc_macro
Macro theo quy trình Rust (proc-macro) có thể hữu ích cho việc mở rộng trình biên dịch để thực hiện các biến đổi mã nguồn hoặc cung cấp các thuộc tính mới. Bạn có thể tìm thêm thông tin về các macro này trên trang Procedural Macros (Macro theo quy trình) trong tài liệu chính thức về Rust.
Đối với mục đích của hệ thống xây dựng, mô-đun rust_proc_macro hoạt động tương tự như các mô-đun rust_library. Đối với các mô-đun phụ thuộc vào rust_proc_macros, hãy thêm tên mô-đun vào thuộc tính proc_macros.
Vì proc_macros là các trình bổ trợ của trình biên dịch, nên chúng nhất thiết phải nhắm đến máy chủ lưu trữ và không tạo ra bất kỳ mã nào sẽ chạy trên thiết bị.
Các thuộc tính đáng chú ý của thư viện Rust
Ngoài các thuộc tính được xác định trong bảng bên dưới, còn có Các thuộc tính chung quan trọng áp dụng cho tất cả các mô-đun. Đây là những mô-đun đặc biệt quan trọng đối với các mô-đun thư viện Rust hoặc có hành vi riêng biệt dành riêng cho loại mô-đun rust_library.
| Thuộc tính thư viện Rust | Định nghĩa |
|---|---|
| stem / name | Thuộc tính stem kiểm soát tên tệp thư viện đầu ra, nếu không thì tên này sẽ mặc định là name.
Trình biên dịch Rust áp đặt một số yêu cầu nhất định đối với tên tệp thư viện và do đó, hệ thống xây dựng sẽ thực thi các yêu cầu này để tránh các vấn đề về biên dịch.
Tên tệp đầu ra phải tuân thủ định dạng |
| crate_name | Đây là một thuộc tính bắt buộc đối với các mô-đun tạo thư viện; ngoài ra, thuộc tính này còn có mối quan hệ với tên tệp đầu ra. (Xem định nghĩa về stem.) |
| export_include_dirs | Đối với các mô-đun rust_ffi, thuộc tính này xác định một danh sách các chuỗi đại diện cho đường dẫn bao gồm tương đối: đường dẫn chứa các tiêu đề mà các mô-đun cc phụ thuộc có thể sử dụng. |
Liên kết rust_library hoặc rust_ffi
Theo mặc định, các mô-đun thư viện Rust nhắm đến thiết bị luôn được liên kết động với libstd. Tuy nhiên, các mô-đun máy chủ lưu trữ luôn được liên kết tĩnh với libstd.
Mối liên kết dùng cho các phần phụ thuộc rustlibs phụ thuộc vào các lựa chọn ưu tiên về mối liên kết của mô-đun gốc. (Ví dụ: rust_binary có prefer_rlib: true sẽ sử dụng các biến thể thư viện Rust liên kết rustlibs dưới dạng rlibs.)
Để cho phép tạo các mô-đun phần phụ thuộc gốc không dựa vào bất kỳ thư viện rust động nào (chẳng hạn như các tệp thực thi tĩnh), rlibs cung cấp cả các biến thể liên kết libstd tĩnh và động. Soong sẽ tự động liên kết biến thể chính xác.