Crate uniffi_bindgen

Uniffi: easily build cross-platform software components in Rust

This is a highly-experimental crate for building cross-language software components in Rust, based on things we’ve learned and patterns we’ve developed in the mozilla/application-services project.

The idea is to let you write your code once, in Rust, and then re-use it from many other programming languages via Rust’s C-compatible FFI layer and some automagically generated binding code. If you think of it as a kind of wasm-bindgen wannabe, with a clunkier developer experience but support for more target languages, you’ll be pretty close to the mark.

Currently supported target languages include Kotlin, Swift and Python.

Usage

To build a cross-language component using uniffi, follow these steps.

1) Specify your Component Interface

Start by thinking about the interface you want to expose for use from other languages. Use the Interface Definition Language to specify your interface in a .udl file, where it can be processed by the tools from this crate. For example you might define an interface like this:

namespace example {
  u32 foo(u32 bar);
}

dictionary MyData {
  u32 num_foos;
  bool has_a_bar;
}

2) Implement the Component Interface as a Rust crate

With the interface, defined, provide a corresponding implementation of that interface as a standard-looking Rust crate, using functions and structs and so-on. For example an implementation of the above Component Interface might look like this:

fn foo(bar: u32) -> u32 {
    // TODO: a better example!
    bar + 42
}

struct MyData {
  num_foos: u32,
  has_a_bar: bool
}

3) Generate and include component scaffolding from the UDL file

Add to your crate uniffi_build under [build-dependencies], then add a build.rs script to your crate and have it call uniffi_build::generate_scaffolding to process your .udl file. This will generate some Rust code to be included in the top-level source code of your crate. If your UDL file is named example.udl, then your build script would call:

uniffi_build::generate_scaffolding("src/example.udl")

This would output a rust file named example.uniffi.rs, ready to be included into the code of your rust crate like this:

include_scaffolding!("example");

4) Generate foreign language bindings for the library

You will need ensure a local uniffi-bindgen - see https://mozilla.github.io/uniffi-rs/tutorial/foreign_language_bindings.html This utility provides a command-line tool that can produce code to consume the Rust library in any of several supported languages. It is done by calling (in kotlin for example):

cargo run --bin -p uniffi-bindgen --language kotlin ./src/example.udl

This will produce a file example.kt in the same directory as the .udl file, containing kotlin bindings to load and use the compiled rust code via its C-compatible FFI.

Re-exports

pub use interface::ComponentInterface;

pub use library_mode::find_components;

Modules

backend

bindings

Generate foreign language bindings for a uniffi component.

cargo_metadata

Helpers for data returned by cargo_metadata. Note that this doesn’t execute cargo_metadata, just parses its output.

interface

Component Interface Definition.

library_mode

macro_metadata

scaffolding

Structs

Component

Everything needed to generate a ComponentInterface.

EmptyCrateConfigSupplier

GenerationSettings

The options used when creating bindings. Named such it doesn’t cause confusion that it’s settings specific to the generator itself.

Traits

BindgenCrateConfigSupplier

A trait used by the bindgen to obtain config information about a source crate which was found in the metadata for the library.

BindingGenerator

A trait representing a UniFFI Binding Generator

VisitMut

A trait to alter language specific type representations.

Functions

generate_bindings

generate_component_scaffolding

generate_component_scaffolding_for_crate

generate_external_bindings

Generate bindings for an external binding generator Ideally, this should replace the generate_bindings function below

guess_crate_root

Guess the root directory of the crate from the path of its UDL file.

is_cdylib

A convenience function for the CLI to help avoid using static libs in places cdylibs are required.

print_repr