Rust scaffolding

Rust scaffolding code

Now we generate some Rust helper code to make the add method available to foreign-language bindings.

First, add uniffi to your crate as both a dependency and build-dependency. Enable the build feature for the build-dependencies. This adds the runtime support code that powers UniFFI and build-time support for generating the Rust scaffolding code.

[dependencies]
uniffi = "0.XX.0"

[build-dependencies]
uniffi = { version = "0.XX.0", features = ["build"] }

As noted in Describing the interface, UniFFI currently supports two methods of interface definitions: UDL files and proc macros. If you are using only proc macros, you can skip some boilerplate in your crate setup as well.

Setup for crates using 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();
}

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

uniffi::include_scaffolding!("math");

Note: The file name is always <namespace>.uniffi.rs.

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 NOTE: This function takes an optional parameter, the namespace used by the component. If not specified, the crate name will be used as the namespace.

uniffi::setup_scaffolding!();

⚠ Warning ⚠ Do not call both uniffi::setup_scaffolding!() and uniffi::include_scaffolding!!() in the same crate.

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.