Modul Android Rust

Penting: Penggunaan Rust di Android dikontrol melalui daftar jalur yang membatasi jenis modul Rust tertentu dapat digunakan. Untuk mengizinkan penggunaan modul Rust di jalur baru, tambahkan setiap jalur baru ke daftar yang diizinkan di build/soong/rust/config/allowed_list.go .

Sebagai prinsip umum, definisi modul rust_* sangat sesuai dengan penggunaan dan harapan cc_* . Berikut ini 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 mencakup properti paling umum untuk modul rust_* . Untuk informasi selengkapnya tentang jenis modul tertentu dan contoh definisi modul, lihat halaman Modul Biner , Modul Pustaka , atau Modul Uji .

Catatan: Untuk dokumentasi terkini yang dibuat secara otomatis untuk semua jenis dan properti modul, lihat referensi modul Soong .

Jenis modul dasar

Jenis	Definisi	Untuk informasi lebih lanjut
rust_binary	Biner karat	Halaman Modul Biner
rust_library	Menghasilkan perpustakaan Rust, dan menyediakan varian rlib dan dylib .	rust_library , halaman Modul Perpustakaan.
rust_ffi	Menghasilkan perpustakaan Rust C yang dapat digunakan oleh modul cc, dan menyediakan varian statis dan bersama.	rust_ffi , halaman Modul Perpustakaan
rust_proc_macro	Menghasilkan perpustakaan Rust proc-macro . (Ini analog dengan plugin compiler.)	rust_proc_macro , halaman Modul Perpustakaan
rust_test	Menghasilkan biner uji Rust yang menggunakan harness uji Rust standar.	Halaman Modul Tes
rust_fuzz	Menghasilkan biner Rust fuzz yang memanfaatkan libfuzzer .	contoh modul rust_fuzz
rust_protobuf	Menghasilkan sumber dan menghasilkan perpustakaan Rust yang menyediakan antarmuka untuk protobuf tertentu.	Modul Protobufs dan halaman Sumber Generator
rust_bindgen	Menghasilkan sumber dan menghasilkan perpustakaan Rust yang berisi binding Rust ke perpustakaan C.	Halaman Modul Bindgen Bindings dan Sumber Generator

Properti umum yang penting

Properti ini umum di semua Modul Android Rust. Setiap properti tambahan (unik) yang terkait dengan masing-masing modul Rust terdaftar di halaman modul itu.

nama

name adalah nama modul Anda. Seperti modul Soong lainnya, ini harus unik di sebagian besar jenis modul Android.bp . Secara default, name digunakan sebagai nama file keluaran. Jika nama file keluaran harus berbeda dari nama modul, gunakan properti stem untuk mendefinisikannya.

tangkai

stem (opsional) memberikan kontrol langsung atas nama file keluaran (tidak termasuk ekstensi file dan sufiks lainnya). Misalnya, pustaka rust_library_rlib dengan nilai batang libfoo menghasilkan file libfoo.rlib . Jika Anda tidak memberikan nilai untuk properti stem , nama file keluaran mengadopsi nama modul secara default.

Gunakan fungsi stem ketika Anda tidak dapat mengatur nama modul ke nama file keluaran yang diinginkan. Misalnya, rust_library untuk peti log diberi nama liblog_rust , karena liblog cc_library sudah ada. Menggunakan properti stem dalam hal ini memastikan bahwa file keluaran bernama liblog.* bukan liblog_rust.* .

srcs

srcs berisi satu file sumber yang mewakili titik masuk ke modul Anda (biasanya main.rs atau lib.rs ). rustc menangani resolusi dan penemuan semua file sumber lain yang diperlukan untuk kompilasi, dan ini disebutkan dalam file deps yang dihasilkan.

Tip: srcs juga menangani sumber yang dihasilkan yang dirujuk oleh include! makro. Sumber-sumber ini harus disediakan oleh modul lain (seperti genrule , atau rust_protobuf , dan seterusnya). Untuk menyertakan sumber, tambahkan nama modul yang menyediakan sumber yang dihasilkan ke srcs , dan awali dengan : . (Seperti dalam, misalnya, ":libmyproto" . File sumber utama harus menjadi entri pertama dalam larik saat menggunakan fungsi ini.

Jika memungkinkan, hindari penggunaan ini untuk kode platform; lihat Generator Sumber untuk informasi lebih lanjut.

peti_nama

crate_name menyetel metadata nama peti melalui flag rustc --crate_name . Untuk modul yang menghasilkan pustaka, ini harus cocok dengan nama peti yang diharapkan yang digunakan dalam sumber. Misalnya, jika modul libfoo_bar dirujuk dalam sumber sebagai extern crate foo_bar , maka ini harus crate_name: "foo_bar" .

Properti ini umum untuk semua modul rust_* , tetapi diperlukan untuk modul yang menghasilkan pustaka Rust (seperti rust_library , rust_ffi , rust_bindgen , rust_protobuf , dan rust_proc_macro ). Modul-modul ini memberlakukan persyaratan rustc pada hubungan antara crate_name dan nama file keluaran. Untuk informasi selengkapnya, lihat bagian Modul Pustaka .

serat

Rustc linter dijalankan secara default untuk semua jenis modul kecuali generator sumber. Beberapa kumpulan lint ditentukan dan digunakan untuk memvalidasi sumber modul. Nilai yang mungkin untuk kumpulan serat tersebut adalah sebagai berikut:

• default (Set lint default, tergantung pada lokasi modul)
• android (untuk kumpulan lint paling ketat yang berlaku untuk semua kode platform Android)
• vendor (untuk serangkaian lint yang diterapkan ke kode vendor)
• none (untuk mengabaikan semua peringatan dan kesalahan lint)

clippy_lints

Clippy linter juga dijalankan secara default untuk semua jenis modul kecuali generator sumber. Beberapa set lint didefinisikan yang digunakan untuk memvalidasi sumber modul. Ini adalah beberapa nilai yang mungkin:

• default (Set lint default tergantung pada lokasi modul)
• android (untuk kumpulan lint paling ketat yang berlaku untuk semua kode platform Android)
• vendor (untuk serangkaian lint yang diterapkan ke kode vendor)
• none (untuk mengabaikan semua peringatan dan kesalahan lint)

Tip: Anda dapat menyetel linter ke `none` saat mengembangkan untuk menghindari kesalahan linter. Namun, selama peninjauan, Anda mungkin perlu membenarkan memiliki modul yang dikomit dengan lint yang tidak terlalu ketat.

edisi

edition mendefinisikan edisi Rust yang akan digunakan untuk mengkompilasi kode ini. Ini mirip dengan versi std untuk C dan C++. Nilai yang valid adalah 2015 dan 2018 (default).

bendera

flags berisi daftar string flag untuk diteruskan ke rustc selama kompilasi.

ld_flags

ld-flags berisi daftar string flag untuk diteruskan ke linker saat mengkompilasi sumber. Ini dilewatkan oleh flag -C linker-args rustc. clang digunakan sebagai front-end penghubung, memanggil lld untuk penautan yang sebenarnya.

Catatan: Karena ini diteruskan ke Clang, perlakukan mereka sebagai flag Clang . Tanda awalan untuk diteruskan ke lld dengan awalan -Wl Clang yang biasa.

fitur

features adalah daftar string fitur yang harus diaktifkan selama kompilasi. Ini diteruskan ke rustc oleh --cfg 'feature="foo"' . Sebagian besar fitur bersifat aditif, jadi dalam banyak kasus ini terdiri dari kumpulan fitur lengkap yang diperlukan oleh semua modul dependen. Namun, jika fitur bersifat eksklusif satu sama lain, tentukan modul tambahan di file build apa pun yang menyediakan fitur yang saling bertentangan.

Catatan: Tidak seperti di build Cargo, tidak ada set fitur "default" yang diaktifkan secara implisit. Fitur "default" adalah kata kunci khusus Kargo; kecuali kode secara eksplisit menangani fitur yang disebut "default", pengaturan "default" tidak berdampak .

cfg

cfgs berisi daftar string flag cfg yang akan diaktifkan selama kompilasi. Ini diteruskan ke rustc oleh --cfg foo dan --cfg "fizz=buzz" .

Sistem build secara otomatis menyetel flag cfg tertentu dalam situasi tertentu, tercantum di bawah ini:

• Modul yang dibuat sebagai dylib akan memiliki set android_dylib cfg.
• Modul yang akan menggunakan VNDK akan memiliki set android_vndk cfg. Ini mirip dengan definisi __ANDROID_VNDK__ untuk C++.

mengupas

strip mengontrol apakah dan bagaimana file output dilucuti (jika berlaku). Jika ini tidak disetel, modul perangkat default untuk menghapus semuanya kecuali mini debuginfo. Modul host, secara default, tidak menghapus simbol apa pun. Nilai yang valid tidak menyertakan none untuk menonaktifkan stripping, dan all untuk menghapus semuanya, termasuk mini debuginfo. Nilai tambahan dapat ditemukan di Referensi Modul Soong .

host_didukung

Untuk modul perangkat, parameter host_supported menunjukkan apakah modul juga harus menyediakan varian host.

Mendefinisikan dependensi perpustakaan

Modul Rust dapat bergantung pada pustaka CC dan Rust melalui properti berikut:

Nama properti	Keterangan
rustlibs	Daftar modul rust_library yang juga merupakan dependensi. Gunakan ini sebagai metode pilihan Anda untuk mendeklarasikan dependensi, karena memungkinkan sistem build untuk memilih tautan yang diinginkan. (Lihat Saat menautkan ke perpustakaan Rust , di bawah)
rlibs	Daftar modul rust_library yang harus ditautkan secara statis sebagai rlibs . (Gunakan dengan hati-hati; lihat Saat menautkan ke perpustakaan Rust , di bawah.)
dylibs	Daftar modul rust_library yang akan ditautkan secara dinamis sebagai dylibs . (Gunakan dengan hati-hati; lihat Saat menautkan ke perpustakaan Rust , di bawah.)
shared_libs	Daftar modul cc_library yang harus ditautkan secara dinamis sebagai pustaka bersama.
static_libs	Daftar modul cc_library yang harus ditautkan secara statis sebagai pustaka statis.
whole_static_libs	Daftar modul cc_library yang harus diberi tinta statis sebagai pustaka statis dan disertakan seluruhnya dalam pustaka yang dihasilkan. Untuk varian rust_ffi_static , whole_static_libraries akan disertakan dalam arsip perpustakaan statis yang dihasilkan. Untuk varian rust_library_rlib , pustaka whole_static_libraries akan digabungkan ke dalam pustaka rlib yang dihasilkan. Tip: Ini mencegah Anda mendeklarasikan ulang dependensi dependen untuk library ini. Namun, dalam beberapa kasus ini dapat menyebabkan kembung jika pustaka statis diduplikasi dalam pohon ketergantungan. Pustaka statis yang disertakan sepenuhnya dalam `rlibs` akan sepenuhnya disertakan dalam `dylibs` dependen, yang menyediakan sumber lain dari potensi mengasapi.

Saat menautkan ke Rust library , sebagai praktik terbaik, lakukan dengan menggunakan properti rustlibs daripada rlibs atau dylibs kecuali Anda memiliki alasan khusus untuk melakukannya. Ini memungkinkan sistem build untuk memilih tautan yang benar berdasarkan apa yang dibutuhkan modul root, dan ini mengurangi kemungkinan pohon dependensi berisi versi rlib dan dylib dari pustaka (yang akan menyebabkan kompilasi gagal).

Fitur build dukungan yang tidak didukung dan terbatas

Soong's Rust menawarkan dukungan terbatas untuk gambar dan snapshot vendor dan vendor_ramdisk . Namun, rlibs staticlibs cdylibs binaries didukung. Untuk target pembuatan gambar vendor, properti android_vndk cfg disetel. Anda dapat menggunakan ini dalam kode jika ada perbedaan antara sistem dan target vendor. rust_proc_macros tidak ditangkap sebagai bagian dari snapshot vendor; jika ini bergantung, pastikan Anda mengontrol versi dengan tepat.

Gambar produk, VNDK, dan Pemulihan tidak didukung.

Bangunan Inkremental

Pengembang dapat mengaktifkan kompilasi tambahan dari sumber Rust dengan menyetel variabel lingkungan SOONG_RUSTC_INCREMENTAL ke true .

Peringatan : Ini tidak dijamin untuk menghasilkan binari yang identik dengan yang dihasilkan oleh buildbots. Alamat fungsi atau data yang terkandung dalam file objek mungkin berbeda. Untuk memastikan bahwa artefak yang dihasilkan 100% identik dengan yang dibuat oleh infrastruktur EngProd, biarkan nilai ini tidak disetel.