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