Rust scaffolding

UniFFI requires that our generated Rust "scaffolding" code is included in your project. For proc macros, most of this is conveniently generated by the macros.

If you use UDL files, you need to generate this "scaffolding" then include the generated .rs in your project.

Rust scaffolding code for UDL

Crates using UDL need a build.rs file next to Cargo.toml. This uses uniffi to generate the Rust scaffolding code.

fn main() {
    uniffi::generate_scaffolding("src/math.udl").unwrap();
}

It will generate <namespace>.uniffi.rs under your target directory.

Lastly, we include the generated scaffolding code in our lib.rs using this handy macro:

uniffi::include_scaffolding!("math");

Setup for crates using only proc macros

If you are only using proc macros, you can skip build.rs entirely! All you need to do is add this to the top of lib.rs

uniffi::setup_scaffolding!();

Don't use uniffi::setup_scaffolding!() in a crate which uses uniffi::include_scaffolding!().

If you don't specify a namespace the crate name is used.

Libraries that depend on UniFFI components

Suppose you want to create a shared library that includes one or more components using UniFFI. The typical way to achieve this is to create a new crate that depends on the component crates. However, this can run into rust-lang#50007. Under certain circumstances, the scaffolding functions that the component crates export do not get re-exported by the dependent crate.

Use the uniffi_reexport_scaffolding! macro to work around this issue. If your library depends on foo_component, then add foo_component::uniffi_reexport_scaffolding!(); to your lib.rs file and UniFFI will add workaround code that forces the functions to be re-exported.

Each scaffolding function contains a hash that's derived from the UDL file. This avoids name collisions when combining multiple UniFFI components into one library.