There are two types of Rust library modules, one that produces Rust libraries and one that produces C-compatible libraries. Additionally, for build system purposes you can consider Rust procedural macros (proc-macros) as a special type of library.
rust_library
The rust_library module produces Rust libraries for use by other Rust modules.
In addition to the _host variants, Rust libraries have module types that control the available linkage.
| Rust Library Module Type | Definition |
|---|---|
| rust_library | Provides both library variants, rlib and dylib. AOSP recommends this module type for Rust libraries, as it allows modules to work correctly when listed as a dependency under the rustlibs property |
| rust_library_rlib | Provides only the rlib variant of a Rust library; modules providing only rlib variants can't be guaranteed to work with the rustlibs property. |
| rust_library_dylib | Provides only the dylib variant of a Rust library; modules providing only dylib variants can't be guaranteed to work with the rustlibs property. |
rust_ffi
The rust_ffi module produces C-compatible libraries to interop with CC modules.
In addition to the _host variants, Rust FFI libraries have module types that control the available linkage, shown in the following table.
| Rust FFI Library Module Type | Definition |
|---|---|
| rust_ffi | Provides both C library variants: static and shared. |
| rust_ffi_shared | Provides only the C shared library variant. |
| rust_ffi_static | Provides only the C static library variant. |
For a basic example of using rust_ffi for calling Rust from C, see the Android Rust Patterns page.
For information on more advanced usage, visit the official Rust documentation.
rust_proc_macro
Rust procedural macros (proc-macros) can be useful for extending the compiler to perform source code transformations or providing new attributes. More information can be found on these in the Procedural Macros page of the official Rust documentation.
For the purposes of the build system, the rust_proc_macro module works similarly to the rust_library modules. For modules that depend on rust_proc_macros, add the module name to the proc_macros property.
As proc_macros are compiler plugins, they necessarily target the host and don't produce any code that would run on a device.
Notable Rust library properties
The properties defined in the table below are in addition to the Important common properties that apply to all modules. These are either particularly important to Rust library modules, or exhibit unique behavior specific to the rust_library module type.
| Rust Library Properties | Definition |
|---|---|
| stem / name | The stem property controls the output library filename, which otherwise defaults to name. The Rust compiler imposes certain requirements on library filenames, and as a result the build system enforces these requirements to avoid compilation issues. The output filename must conform to the format |
| crate_name | This is a required property for library-producing modules; it additionally has a relationship to the output filename. (See the stem definition.) |
| export_include_dirs | For rust_ffi modules, this property defines a list of strings representing relative include paths: paths which contain headers that dependent cc modules can use. |
Linkage of rust_library or rust_ffi
By default, Rust library modules targeting devices are always linked dynamically against libstd. Host modules, however, are always linked statically against libstd.
The linkage used for rustlibs dependencies depends on the root module's linkage preferences. (For example, a rust_binary with prefer_rlib: true will use Rust library variants that link rustlibs as rlibs.)
To allow production of root dependency modules that don't rely on any dynamic rust libraries (such as static executables), rlibs provides both dynamic and static libstd linkage variants. The correct variant is automatically linked by Soong.