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 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,
|rust_library_rlib||Provides only the
|rust_library_dylib||Provides only 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 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
rust_library modules. For modules that depend on
add the module name to the
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
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
Linkage of rust_library or rust_ffi
By default, Rust library modules targeting devices are always linked dynamically
libstd. Host modules, however, are always linked statically
The linkage used for
rustlibs dependencies depends on the root module's
linkage preferences. (For example, a
prefer_rlib: true will
use Rust library variants that link
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
libstd linkage variants. The correct variant is automatically linked by