Sebagai prinsip umum, definisi modul rust_* sangat mematuhi penggunaan dan ekspektasi cc_*. Berikut adalah contoh definisi modul
untuk biner Rust:
rust_binary {
name: "hello_rust",
crate_name: "hello_rust",
srcs: ["src/hello_rust.rs"],
host_supported: true,
}
Halaman ini membahas properti paling umum untuk modul rust_*. Untuk
informasi selengkapnya tentang jenis modul tertentu dan contoh definisi modul,
lihat
Modul biner,
Modul library,
atau
Modul pengujian.
Jenis modul dasar
| Jenis | Definisi | Untuk Informasi Selengkapnya |
|---|---|---|
rust_binary | Biner Rust | Modul Biner halaman |
rust_library | Menghasilkan library Rust, dan menyediakan varian rlib dan
dylib. |
rust_library,
halaman Modul Library. |
rust_ffi | Menghasilkan library C Rust yang dapat digunakan oleh modul cc, dan menyediakan varian statis dan bersama. | rust_ffi,
Halaman Modul Library |
rust_proc_macro | Menghasilkan library Rust proc-macro.
(Hal ini analog dengan plugin compiler.) |
rust_proc_macro,
Halaman Modul Library |
rust_test | Menghasilkan biner pengujian Rust yang menggunakan harness pengujian Rust standar. | Halaman Test Modules |
rust_fuzz | Menghasilkan biner fuzz Rust yang memanfaatkan
libfuzzer. |
Contoh modul rust_fuzz |
rust_protobuf | Membuat sumber dan menghasilkan library Rust yang menyediakan antarmuka untuk protobuf tertentu. | Halaman Protobufs Modules dan Source Generators |
rust_bindgen | Menghasilkan sumber dan membuat library Rust yang berisi binding Rust ke library C. | Modul Bindings Bindgen dan halaman Generator Sumber |
Properti umum penting
Properti ini umum di semua Modul Rust Android. Setiap properti tambahan (unik) yang terkait dengan setiap modul Rust tercantum di halaman modul tersebut.
nama
name adalah nama modul Anda. Seperti modul Soong lainnya, modul ini harus unik
di sebagian besar jenis modul Android.bp. Secara default, name digunakan sebagai nama file output. Jika nama file output harus berbeda dari nama modul, gunakan properti
stem untuk menentukannya.
batang
stem (opsional) memberikan kontrol langsung atas nama file output (tidak termasuk
ekstensi file dan akhiran lainnya). Misalnya, library rust_library_rlib
dengan nilai batang libfoo menghasilkan file libfoo.rlib. Jika Anda
tidak memberikan nilai untuk properti stem, nama file output akan menggunakan
nama modul secara default.
Gunakan fungsi stem jika Anda tidak dapat menetapkan nama modul ke nama file output yang diinginkan. Misalnya, rust_library untuk peti log diberi nama
liblog_rust,
karena liblog cc_library
sudah ada. Penggunaan properti stem dalam hal ini memastikan bahwa file
output diberi nama liblog.*, bukan liblog_rust.*.
srcs
srcs berisi satu file sumber yang merepresentasikan titik entri ke modul Anda (biasanya main.rs atau lib.rs). rustc menangani penyelesaian dan penemuan semua file sumber lain yang diperlukan untuk kompilasi, dan file ini dicantumkan dalam file deps yang dihasilkan.
Jika memungkinkan, hindari penggunaan ini untuk kode platform; lihat Generator Sumber untuk mengetahui informasi selengkapnya.
crate_name
crate_name menetapkan metadata nama crate melalui tanda rustc --crate_name. Untuk modul yang menghasilkan library, harus cocok dengan
nama crate yang diharapkan yang digunakan dalam sumber. Misalnya, jika modul libfoo_bar dirujuk
dalam sumber sebagai extern crate foo_bar, maka harus berupa
crate_name: "foo_bar".
Properti ini umum untuk semua modul rust_*, tetapi diperlukan untuk modul
yang menghasilkan library Rust (seperti rust_library
rust_ffi, rust_bindgen, rust_protobuf, dan rust_proc_macro). Modul-modul ini menerapkan persyaratan rustc pada hubungan antara crate_name
dan nama file output. Untuk mengetahui informasi selengkapnya, lihat bagian
Modul Library.
lint
Linter rustc dijalankan secara default untuk semua jenis modul, kecuali generator sumber. Beberapa set lint ditentukan dan digunakan untuk memvalidasi sumber modul. Kemungkinan nilai untuk set lint tersebut adalah sebagai berikut:
defaultset lint default, bergantung pada lokasi modulandroidset lint paling ketat yang berlaku untuk semua kode platform Androidvendorsekumpulan lint yang lebih longgar diterapkan pada kode vendornoneuntuk mengabaikan semua peringatan dan error lint
clippy_lints
Clippy linter juga dijalankan secara default untuk semua jenis modul, kecuali generator sumber. Beberapa set lint ditentukan yang digunakan untuk memvalidasi sumber modul. Berikut beberapa kemungkinan nilainya:
- Set lint default
defaultbergantung pada lokasi modul androidset lint paling ketat yang berlaku untuk semua kode platform Androidvendorsekumpulan lint yang lebih longgar diterapkan pada kode vendornoneuntuk mengabaikan semua peringatan dan error lint
edisi
edition menentukan edisi Rust yang akan digunakan untuk
mengompilasi kode ini. Ini mirip dengan versi std untuk C dan C++. Nilai yang valid adalah 2015, 2018, dan 2021 (default).
flags
flags berisi daftar string tanda yang akan diteruskan ke rustc selama kompilasi.
ld_flags
ld-flags berisi daftar string flag yang akan diteruskan ke linker saat mengompilasi
sumber. Opsi ini diteruskan oleh tanda rustc -C linker-args. clang digunakan sebagai
front-end linker, yang memanggil lld untuk penautan sebenarnya.
fitur
features adalah daftar string fitur yang harus diaktifkan selama kompilasi.
Ini diteruskan ke rustc oleh --cfg 'feature="foo"'. Sebagian besar fitur bersifat tambahan,
sehingga dalam banyak kasus, hal ini terdiri dari set fitur lengkap yang diperlukan oleh semua modul
dependen. Namun, jika fitur saling eksklusif,
tentukan modul tambahan dalam file build yang menyediakan fitur yang bertentangan.
cfgs
cfgs berisi daftar string tanda cfg yang akan diaktifkan selama kompilasi.
Hal ini diteruskan ke rustc oleh --cfg foo dan --cfg "fizz=buzz".
Sistem build otomatis menetapkan flag cfg tertentu dalam situasi tertentu, yang tercantum di bawah:
Modul yang dibuat sebagai dylib akan memiliki setelan
android_dylibcfg.Modul yang akan menggunakan VNDK akan memiliki setelan cfg
android_vndk. Hal ini mirip dengan definisi__ANDROID_VNDK__untuk C++.
strip
strip mengontrol apakah dan bagaimana file output dihapus (jika berlaku).
Jika tidak disetel, modul perangkat akan menghapus semuanya kecuali info debug mini secara default.
Modul host, secara default, tidak menghapus simbol apa pun. Nilai yang valid mencakup none
untuk menonaktifkan penghapusan, dan all untuk menghapus semuanya, termasuk info debug mini.
Nilai tambahan dapat ditemukan di
Referensi Modul Soong.
host_supported
Untuk modul perangkat, parameter host_supported menunjukkan apakah modul
juga harus menyediakan varian host.
Menentukan dependensi library
Modul Rust dapat bergantung pada library CC dan Rust melalui properti berikut:
| Nama Properti | Deskripsi |
|---|---|
rustlibs |
Daftar modul rust_library yang juga merupakan dependensi. Gunakan ini sebagai
metode pilihan Anda untuk mendeklarasikan dependensi, karena memungkinkan sistem build
memilih penautan yang diinginkan. (Lihat Saat menautkan ke library Rust di bawah) |
rlibs |
Daftar modul rust_library yang harus ditautkan secara statis
sebagai rlibs. (Gunakan dengan hati-hati; lihat
Saat menautkan ke library Rust di bawah.) |
shared_libs |
Daftar modul cc_library yang harus ditautkan secara dinamis sebagai library bersama. |
static_libs |
Daftar modul cc_library yang harus ditautkan secara statis sebagai library statis. |
whole_static_libs |
Daftar modul cc_library yang harus ditautkan secara statis sebagai library statis dan disertakan secara keseluruhan dalam library yang dihasilkan. Untuk varian
rust_ffi_static, whole_static_libraries akan disertakan dalam
arsip library statis yang dihasilkan. Untuk varian rust_library_rlib,
library whole_static_libraries akan di-bundle ke dalam library rlib
yang dihasilkan.
|
Saat menautkan ke library Rust, sebagai praktik terbaik, lakukan penautan menggunakan properti rustlibs, bukan rlibs atau dylibs, kecuali jika Anda memiliki alasan khusus untuk melakukannya. Hal ini memungkinkan sistem build memilih penautan yang benar berdasarkan persyaratan modul root, dan mengurangi kemungkinan pohon dependensi berisi versi rlib dan dylib dari library (yang akan menyebabkan kompilasi gagal).
Fitur build dukungan terbatas dan tidak didukung
Rust Soong menawarkan dukungan terbatas untuk gambar dan snapshot vendor dan vendor_ramdisk. Namun, staticlibs, cdylibs,
rlibs, dan binaries didukung. Untuk target build image vendor, properti
android_vndk cfg ditetapkan. Anda dapat menggunakannya dalam kode jika ada perbedaan antara target sistem dan vendor. rust_proc_macros tidak
direkam sebagai bagian dari snapshot vendor; jika dependensi ini digunakan, pastikan Anda
mengontrol versi dengan tepat.
Gambar Produk, VNDK, dan Pemulihan tidak didukung.
Build inkremental
Developer dapat mengaktifkan kompilasi inkremental sumber
Rust dengan menetapkan variabel lingkungan SOONG_RUSTC_INCREMENTAL ke true.
Peringatan: Cara ini tidak dijamin akan menghasilkan biner yang identik dengan biner yang dihasilkan oleh buildbot. Alamat fungsi atau data yang ada dalam file objek mungkin berbeda. Untuk memastikan artefak yang dihasilkan 100% identik dengan artefak yang dibuat oleh infrastruktur EngProd, biarkan nilai ini tidak disetel.