Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Halaman ini diterjemahkan oleh Cloud Translation API.

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 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

Jenis	Definisi	Untuk Informasi Selengkapnya
`rust_binary`	Biner Rust	Halaman Binary Modules
`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`. (Ini analog dengan plugin compiler.)	`rust_proc_macro`, halaman Modul Library
`rust_test`	Menghasilkan biner pengujian Rust yang menggunakan harness pengujian Rust standar.	Halaman Modul Pengujian
`rust_fuzz`	Menghasilkan biner fuzz Rust yang memanfaatkan `libfuzzer`.	Contoh modul `rust_fuzz`
`rust_protobuf`	Menghasilkan sumber dan menghasilkan library 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.	Halaman Modul Binding dan Generator Sumber

Properti umum yang penting

Properti ini umum di semua Modul Rust Android. Semua properti tambahan (unik) yang terkait dengan masing-masing 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 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 batang 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 kotak 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 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.

Tips: srcs juga menangani sumber yang dihasilkan yang direferensikan oleh makro include!. 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 berikan awalan dengan :. (Seperti, misalnya, ":libmyproto". File sumber utama harus menjadi entri pertama dalam array saat menggunakan fungsi ini.

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

{i>crate_name<i}

crate_name menetapkan metadata nama crate melalui tanda 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, parameter ini harus bernilai 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 Modul Library.

lint

rustc linter 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

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 nilainya:

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. Hal ini mirip dengan versi std untuk C dan C++. Nilai yang valid adalah 2015 dan 2018 (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, jadi dalam banyak kasus, fitur ini terdiri dari set 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 kumpulan android_vndk cfg. Hal ini serupa dengan definisi __ANDROID_VNDK__ untuk C++.

strip

strip mengontrol apakah file output dihapus dan bagaimana caranya (jika ada). Jika tidak ditetapkan, modul perangkat akan menghapus semua kecuali debuginfo 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 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 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 arsip library statis yang dihasilkan. Untuk varian `rust_library_rlib`, library `whole_static_libraries` akan dipaketkan ke dalam library `rlib` yang dihasilkan. Tips: Hal ini mencegah Anda mendeklarasikan ulang dependensi dependen untuk library ini. Namun, dalam beberapa kasus, hal ini dapat menyebabkan ukuran yang membesar jika library statis diduplikasi dalam hierarki dependensi. Library statis yang disertakan sepenuhnya dalam `rlibs` akan sepenuhnya disertakan dalam `dylibs` dependen, yang menyediakan sumber lain untuk potensi bloat.

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

Fitur build yang tidak didukung dan dukungan 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 diperlukan, pastikan Anda mengontrol versinya dengan tepat.

Image 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.