Modul Android Rust

Sebagai prinsip umum, definisi modul rust_* sangat mematuhi 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 Modul biner , Modul perpustakaan , atau Modul pengujian .

Jenis modul dasar

Jenis Definisi Untuk informasi lebih lanjut
rust_binary Biner Rust Halaman Modul Biner
rust_library Menghasilkan perpustakaan Rust , dan menyediakan varian rlib dan dylib . rust_library , halaman Modul Perpustakaan.
rust_ffi Menghasilkan pustaka 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 kompiler.) rust_proc_macro , halaman Modul Perpustakaan
rust_test Menghasilkan biner uji Rust yang menggunakan rangkaian uji Rust standar. Halaman Modul Uji
rust_fuzz Menghasilkan biner fuzz Rust yang memanfaatkan libfuzzer . contoh modul rust_fuzz
rust_protobuf Menghasilkan sumber dan menghasilkan perpustakaan Rust yang menyediakan antarmuka untuk protobuf tertentu. Halaman Modul Protobuf dan Generator Sumber
rust_bindgen Menghasilkan sumber dan menghasilkan perpustakaan Rust yang berisi pengikatan Rust ke perpustakaan C. Modul Binding Bindgen dan halaman Generator Sumber

Properti umum yang penting

Properti ini umum di semua Modul Android Rust . Properti tambahan (unik) apa pun yang terkait dengan masing-masing 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 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 akhiran lainnya). Misalnya, perpustakaan rust_library_rlib dengan nilai dasar libfoo menghasilkan file libfoo.rlib . Jika Anda tidak memberikan nilai untuk properti stem , nama file keluaran akan 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 diberi nama 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.

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

nama_ peti

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

Properti ini umum untuk semua modul rust_* , namun diperlukan untuk modul yang menghasilkan pustaka 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 keluaran. Untuk informasi lebih lanjut, lihat bagian Modul Perpustakaan .

serat

Linter Rustc 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 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 sekumpulan lint santai yang diterapkan pada kode vendor
  • none yang mengabaikan semua peringatan dan kesalahan lint

clippy_lints

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

  • kumpulan lint default bergantung pada lokasi modul
  • android kumpulan lint paling ketat yang berlaku untuk semua kode platform Android
  • vendor sekumpulan lint santai yang diterapkan pada kode vendor
  • none yang mengabaikan semua peringatan dan kesalahan lint

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 yang akan diteruskan ke rustc selama kompilasi.

ld_flags

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

fitur

features adalah daftar string fitur yang harus diaktifkan selama kompilasi. Ini diteruskan ke rustic oleh --cfg 'feature="foo"' . Sebagian besar fitur bersifat tambahan, jadi dalam banyak kasus fitur ini terdiri dari kumpulan fitur lengkap yang diperlukan oleh semua modul dependen. Namun, jika fitur-fiturnya eksklusif satu sama lain, tentukan modul tambahan di file build apa pun yang menyediakan fitur-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 menyetel tanda cfg tertentu dalam situasi tertentu, seperti 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 dihapus (jika ada). Jika ini tidak disetel, modul perangkat secara default akan menghapus semuanya kecuali mini debuginfo. Modul host, secara default, tidak menghapus simbol apa pun. Nilai yang valid mencakup none untuk menonaktifkan pengupasan, 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.

Tentukan 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 ini memungkinkan sistem build untuk memilih linkage 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.)
shared_libs Daftar modul cc_library yang harus dihubungkan secara dinamis sebagai perpustakaan bersama.
static_libs Daftar modul cc_library yang harus ditautkan secara statis sebagai perpustakaan statis.
whole_static_libs Daftar modul cc_library yang harus ditautkan secara statis sebagai perpustakaan statis dan dimasukkan secara keseluruhan ke dalam perpustakaan 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.

Saat menautkan ke perpustakaan Rust , sebagai praktik terbaik, lakukan dengan menggunakan properti rustlibs daripada rlibs atau dylibs kecuali Anda memiliki alasan khusus untuk melakukannya. Hal ini memungkinkan sistem pembangunan untuk memilih linkage yang benar berdasarkan apa yang dibutuhkan oleh modul root, dan mengurangi kemungkinan bahwa pohon dependensi berisi versi rlib dan dylib dari sebuah perpustakaan (yang akan menyebabkan kegagalan kompilasi).

Fitur build dukungan tidak didukung dan terbatas

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

Gambar Produk, VNDK, dan Pemulihan tidak didukung.

Pembangunan bertahap

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

Peringatan : Hal ini tidak menjamin menghasilkan biner yang identik dengan yang dihasilkan oleh buildbots. Alamat fungsi atau data yang terdapat dalam file objek mungkin berbeda. Untuk memastikan bahwa artefak yang dihasilkan 100% identik dengan artefak yang dibuat oleh infrastruktur EngProd, biarkan nilai ini tidak disetel.