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.