Modul Android Rust

Sebagai prinsip umum, definisi modul rust_* sangat mematuhi Penggunaan dan ekspektasi cc_*. Berikut ini contoh 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_*. Sebagai informasi lebih lanjut tentang tipe modul tertentu dan contoh definisi modul, lihat Modul biner, Modul library, atau Menguji modul.

Jenis modul dasar

Jenis	Definisi	Untuk Informasi Selengkapnya
rust_binary	Biner Rust	Modul Biner halaman
rust_library	Menghasilkan library Rust, dan menyediakan rlib serta Varian dylib.	rust_library, Library Modules.
rust_ffi	Menghasilkan library Rust C yang dapat digunakan oleh cc modul, dan menyediakan varian statis dan bersama.	rust_ffi, Halaman Modul Library
rust_proc_macro	Menghasilkan library proc-macro Rust. (Ini setara dengan plugin compiler.)	rust_proc_macro, Halaman Modul Library
rust_test	Menghasilkan biner pengujian Rust yang menggunakan Harness uji Rust standar.	Halaman Modul Pengujian
rust_fuzz	Menghasilkan biner fuzz Rust yang memanfaatkan libfuzzer.	Contoh modul rust_fuzz
rust_protobuf	Menghasilkan sumber dan menghasilkan Rust yang menyediakan antarmuka untuk protobuf tertentu.	Halaman Modul Protobufs dan Generator Sumber
rust_bindgen	Menghasilkan sumber dan menghasilkan Library Rust yang berisi binding Rust ke library C.	Modul Bindgen Binding dan halaman Source Generator

Properti umum yang penting

Properti ini umum di semua Android Rust Modul. Setiap properti tambahan (unik) yang terkait dengan Modul Rust tercantum di halaman modul tersebut.

nama

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

batang

stem (opsional) memberikan kontrol langsung atas nama file output (tidak termasuk ekstensi file dan akhiran lainnya). Misalnya, rust_library_rlib library dengan nilai batang libfoo menghasilkan file libfoo.rlib. Jika Anda tidak memberikan nilai untuk properti stem, nama file output akan mengadopsi nama modul secara {i>default<i}.

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

src

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

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

{i>crate_name<i}

crate_name menetapkan metadata nama peti melalui rustc --crate_name penanda. Untuk modul yang menghasilkan library, nilai ini harus cocok dengan parameter yang diharapkan nama peti yang digunakan dalam sumber. Misalnya, jika modul libfoo_bar direferensikan dalam sumber sebagai extern crate foo_bar, maka harus {i>crate_name<i}: "foo_bar".

Properti ini umum untuk semua modul rust_*, tetapi wajib untuk modul yang menghasilkan library Rust (seperti rust_library rust_ffi, rust_bindgen, rust_protobuf, dan rust_proc_macro). Ini modul menerapkan rustc persyaratan pada hubungan antara crate_name dan nama file {i>output<i}. Untuk informasi selengkapnya, lihat Modul Library bagian.

lint

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 lint tersebut adalah sebagai berikut:

• default kumpulan lint default, bergantung pada lokasi modul
• android kumpulan lint paling ketat yang berlaku untuk semua kode platform Android
• vendor serangkaian lint longgar yang diterapkan ke kode vendor
• none untuk mengabaikan semua peringatan dan error lint

clippy_lint

Linter klip juga dijalankan secara default untuk semua jenis modul kecuali generator sumber. Beberapa kumpulan lint ditentukan yang digunakan untuk memvalidasi sumber modul. Berikut beberapa kemungkinan nilai-nilai:

• Kumpulan lint default default bergantung pada lokasi modul
• android kumpulan lint paling ketat yang berlaku untuk semua kode platform Android
• vendor serangkaian lint longgar yang diterapkan ke kode vendor
• none untuk mengabaikan semua peringatan dan error lint

edisi

edition menentukan edisi Rust yang akan digunakan untuk mengompilasi kode ini. Ini mirip dengan versi {i>std<i} untuk C dan C++. Nilai valid adalah 2015 dan 2018 (default).

flags

flags berisi daftar string tanda yang akan diteruskan ke rustc selama kompilasi.

ld_flag

ld-flags berisi daftar string tanda yang akan diteruskan ke penaut saat mengompilasi sumber. Hal ini diteruskan oleh flag rustc -C linker-args. clang digunakan sebagai front-end penaut, 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 adalah tambahan, jadi dalam banyak kasus, ini terdiri dari set fitur lengkap yang diperlukan oleh semua dependensi modul. Namun, dalam kasus di mana fitur bersifat eksklusif satu sama lain, mendefinisikan modul tambahan dalam setiap file build yang menyediakan fitur yang bertentangan.

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 menetapkan tanda cfg tertentu secara khusus yang tercantum, seperti yang tercantum di bawah ini:

• Modul yang dibuat sebagai dylib akan memiliki kumpulan android_dylib cfg.

• Modul yang akan menggunakan VNDK akan memiliki kumpulan android_vndk cfg. Ini adalah mirip dengan __ANDROID_VNDK__ untuk C++.

strip

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

didukung host

Untuk modul perangkat, parameter host_supported menunjukkan apakah modul juga harus menyediakan varian {i>host<i}.

Menentukan dependensi library

Modul Rust dapat bergantung pada 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 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, tercantum di bawah ini.)
shared_libs	Daftar modul cc_library yang harus dinamis ditautkan sebagai {i>shared library<i}.
static_libs	Daftar modul cc_library yang harus berada secara statis ditautkan sebagai library statis.
whole_static_libs	Daftar modul cc_library yang harus bersifat statis ditautkan sebagai library statis dan menyertakan keseluruhan library yang dihasilkan. Sebagai rust_ffi_static varian, whole_static_libraries akan disertakan dalam arsip perpustakaan statis yang dihasilkan. Untuk varian rust_library_rlib, Library whole_static_libraries akan digabungkan ke dalam rlib yang dihasilkan library.

Saat menautkan ke library Rust, sebagai praktik terbaiknya, gunakan properti rustlibs, bukan rlibs atau dylibs kecuali jika Anda memiliki alasan khusus untuk melakukannya. Hal ini memungkinkan build sistem untuk memilih penautan yang benar berdasarkan kebutuhan modul {i>root<i}, dan mengurangi kemungkinan bahwa hierarki dependensi berisi rlib dan dylib versi library (yang akan menyebabkan kompilasi gagal).

Fitur build yang tidak didukung dan dukungan terbatas

Rust Soong menawarkan dukungan terbatas untuk vendor dan vendor_ramdisk gambar dan snapshot. Namun, staticlibs, cdylibs, rlibs dan binaries didukung. Untuk target build image vendor, Properti android_vndk cfg ditetapkan. Anda dapat menggunakan ini dalam kode jika ada perbedaan antara target sistem dan vendor. rust_proc_macros tidak direkam sebagai bagian dari snapshot vendor; jika diperlukan, pastikan mengontrol versi dengan tepat.

Image Produk, VNDK, dan Pemulihan tidak didukung.

Build inkremental

Pengembang dapat mengaktifkan kompilasi inkremental dari Sumber Rust dengan menyetel SOONG_RUSTC_INCREMENTAL variabel lingkungan menjadi true.

Peringatan: Tindakan ini tidak dijamin akan menghasilkan biner yang identik dengan yang dihasilkan oleh buildbot. Alamat fungsi atau data yang terkandung dalam file objek mungkin berbeda. Untuk memastikan artefak yang dihasilkan 100% sama dengan yang dibangun oleh infrastruktur EngProd, jangan tetapkan nilai ini.