Modul Android Rust

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 yang paling umum untuk modul rust_*. Untuk mengetahui informasi selengkapnya tentang jenis modul tertentu dan contoh definisi modul, lihat Modul biner, Modul library, atau Modul pengujian.

Jenis modul dasar

JenisDefinisiUntuk Informasi Selengkapnya
rust_binaryBiner Rust Halaman Modul Biner
rust_libraryMenghasilkan library Rust, dan menyediakan varian rlib dan dylib. rust_library, halaman Library Modules.
rust_ffiMenghasilkan library C Rust yang dapat digunakan oleh modul cc, dan menyediakan varian statis dan bersama. rust_ffi, halaman Modul Library
rust_proc_macroMenghasilkan library Rust proc-macro. (Ini analog dengan plugin compiler.) rust_proc_macro, halaman Modul Library
rust_testMenghasilkan biner pengujian Rust yang menggunakan harness pengujian Rust standar. Halaman Test Modules
rust_fuzzMenghasilkan biner fuzz Rust yang memanfaatkan libfuzzer. Contoh modul rust_fuzz
rust_protobufMenghasilkan sumber dan menghasilkan library Rust yang menyediakan antarmuka untuk protobuf tertentu. Halaman Protobufs Modules dan Source Generators
rust_bindgenMenghasilkan sumber dan menghasilkan library Rust yang berisi binding Rust ke library C. Halaman Modul Binding Bindgen dan Generator Sumber

Properti umum yang 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, nama ini harus unik di sebagian besar jenis modul Android.bp. Secara default, name digunakan sebagai nama file output. Jika nama file output harus berbeda dengan nama modul, gunakan properti stem untuk menentukannya.

tangkai

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

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

srcs

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

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

crate_name

crate_name menetapkan metadata nama crate melalui flag rustc --crate_name. Untuk modul yang menghasilkan library, ini harus cocok dengan nama crate yang diharapkan yang digunakan dalam sumber. Misalnya, jika modul libfoo_bar direferensikan 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 ini menerapkan persyaratan rustc pada hubungan antara crate_name dan nama file output. Untuk informasi selengkapnya, lihat bagian Library Modules.

lint

Lint rustc dijalankan secara default untuk semua jenis modul kecuali generator sumber. Beberapa kumpulan lint ditentukan dan digunakan untuk memvalidasi sumber modul. Kemungkinan nilai untuk kumpulan 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 kumpulan lint longgar yang diterapkan ke kode vendor
  • none untuk mengabaikan semua peringatan dan error lint

clippy_lints

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

  • Kumpulan lint default default bergantung pada lokasi modul
  • android kumpulan lint paling ketat yang berlaku untuk semua kode platform Android
  • vendor kumpulan 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 std untuk C dan C++. Nilai yang valid adalah 2015, 2018, dan 2021 (default).

flags

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

ld_flags

ld-flags berisi daftar string flag yang akan diteruskan ke penaut saat mengompilasi sumber. Flag ini diteruskan oleh flag rustc -C linker-args. clang digunakan sebagai frontend penaut, yang memanggil lld untuk penautan yang 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, fitur ini terdiri dari kumpulan fitur lengkap yang diperlukan oleh semua modul dependen. Namun, jika fitur bersifat eksklusif satu sama lain, tentukan modul tambahan dalam file build yang menyediakan fitur yang bertentangan.

cfgs

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 flag cfg tertentu dalam situasi tertentu, yang tercantum di bawah:

  • Modul yang di-build sebagai dylib akan memiliki set cfg android_dylib.

  • Modul yang akan menggunakan VNDK akan memiliki cfg android_vndk yang ditetapkan. Hal ini serupa dengan definisi __ANDROID_VNDK__ untuk C++.

strip

strip mengontrol apakah dan bagaimana file output dihapus (jika berlaku). Jika tidak ditetapkan, modul perangkat akan menghapus semua kecuali debuginfo mini secara default. Secara default, modul host tidak menghapus simbol apa pun. Nilai yang valid mencakup none untuk menonaktifkan penghapusan, dan all untuk menghapus semuanya, termasuk debuginfo 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 deklarasi dependensi pilihan Anda, 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 hasil arsip library statis. Untuk varian rust_library_rlib, library whole_static_libraries akan dipaketkan ke dalam library rlib yang dihasilkan.

Saat menautkan ke library Rust, sebagai praktik terbaik, lakukan 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 apa yang diperlukan modul root, dan mengurangi kemungkinan hierarki dependensi berisi versi rlib dan dylib library (yang akan menyebabkan kompilasi gagal).

Fitur build dukungan yang tidak didukung dan terbatas

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 diambil sebagai bagian dari snapshot vendor; jika ini bergantung, pastikan Anda mengontrol versinya dengan benar.

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: Hal ini tidak dijamin akan menghasilkan biner yang identik dengan yang dibuat oleh buildbot. Alamat fungsi atau data yang terdapat dalam file objek mungkin berbeda. Untuk memastikan artefak yang dihasilkan 100% identik dengan yang dibuat oleh infrastruktur EngProd, biarkan nilai ini tidak ditetapkan.