Shared core and types

These are the steps to set up the two crates forming the shared core – the core itself, and the shared types crate which does type generation for the foreign languages.

Sharp edge

Most of these steps are going to be automated in future tooling, and published as crates. For now the set up is effectively a copy & paste from one of the example projects.

Install the tools

This is an example of a rust-toolchain.toml file, which you can add at the root of your repo. It should ensure that the correct rust channel and compile targets are installed automatically for you when you use any rust tooling within the repo.

[toolchain]
channel = "stable"
components = ["rustfmt", "rustc-dev"]
targets = [
  "aarch64-apple-darwin",
  "aarch64-apple-ios",
  "aarch64-apple-ios-sim",
  "aarch64-linux-android",
  "wasm32-unknown-unknown",
  "x86_64-apple-ios"
]
profile = "minimal"

Create the core crate

The shared library

The first library to create is the one that will be shared across all platforms, containing the behavior of the app. You can call it whatever you like, but we have chosen the name shared here. You can create the shared rust library, like this:

cargo new --lib shared

The workspace and library manifests

We'll be adding a bunch of other folders into the monorepo, so we are choosing to use Cargo Workspaces. Edit the workspace /Cargo.toml file, at the monorepo root, to add the new library to our workspace. It should look something like this (the package and dependencies fields are just examples):

[workspace]
members = ["shared", "shared_types", "web-dioxus", "web-leptos", "web-yew"]
resolver = "1"

[workspace.package]
authors = ["Red Badger Consulting Limited"]
edition = "2021"
repository = "https://github.com/redbadger/crux/"
license = "Apache-2.0"
keywords = ["crux", "crux_core", "cross-platform-ui", "ffi", "wasm"]
rust-version = "1.66"

[workspace.dependencies]
anyhow = "1.0.75"
serde = "1.0.188"

The library's manifest, at /shared/Cargo.toml, should look something like the following, but there are a few things to note:

the crate-type
- lib is the default rust library when linking into a rust binary, e.g. in the web-yew, or cli, variant
- staticlib is a static library (libshared.a) for including in the Swift iOS app variant
- cdylib is a C-ABI dynamic library (libshared.so) for use with JNA when included in the Kotlin Android app variant
we need to declare a feature called typegen that depends on the feature with the same name in the crux_core crate. This is used by its sister library (often called shared_types) that will generate types for use across the FFI boundary (see the section below on generating shared types).
the path fields on the crux dependencies are for the examples in the Crux repo and so you will probably not need them
the uniffi dependencies and uniffi-bindgen target should make sense after you read the next section

[package]
name = "shared"
version = "0.1.0"
edition = "2021"
rust-version = "1.66"

[lib]
crate-type = ["lib", "staticlib", "cdylib"]
name = "shared"

[features]
typegen = ["crux_core/typegen"]

[dependencies]
crux_core = "0.6"
crux_macros = "0.3"
serde = { workspace = true, features = ["derive"] }
lazy_static = "1.4.0"
uniffi = "0.24.3"
wasm-bindgen = "0.2.87"

[target.uniffi-bindgen.dependencies]
uniffi = { version = "0.24.3", features = ["cli"] }

[build-dependencies]
uniffi = { version = "0.24.3", features = ["build"] }

FFI bindings

Crux uses Mozilla's Uniffi to generate the FFI bindings for iOS and Android.

Generating the `uniffi-bindgen` CLI tool

Since Mozilla released version 0.23.0 of Uniffi, we need to also generate the binary that generates these bindings. This avoids the possibility of getting a version mismatch between a separately installed binary and the crate's Uniffi version. You can read more about it here.

Generating the binary is simple, we just add the following to our crate, in a file called /shared/src/bin/uniffi-bindgen.rs.

fn main() {
    uniffi::uniffi_bindgen_main()
}

And then we can build it with cargo.

cargo run -p shared --bin uniffi-bindgen

# or

cargo build
./target/debug/uniffi-bindgen

The uniffi-bindgen executable will be used during the build in XCode and in Android Studio (see the following pages).

The interface definitions

We will need an interface definition file for the FFI bindings. Uniffi has its own file format (similar to WebIDL) that has a .udl extension. You can create one at /shared/src/shared.udl, like this:

namespace shared {
  bytes process_event([ByRef] bytes msg);
  bytes handle_response([ByRef] bytes uuid, [ByRef] bytes res);
  bytes view();
};

There are also a few additional parameters to tell Uniffi how to create bindings for Kotlin and Swift. They live in the file /shared/uniffi.toml, like this (feel free to adjust accordingly):

[bindings.kotlin]
package_name = "com.example.counter.shared"
cdylib_name = "shared"

[bindings.swift]
cdylib_name = "shared_ffi"
omit_argument_labels = true

Finally, we need a build.rs file in the root of the crate (/shared/build.rs), to generate the bindings:

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

Scaffolding

Soon we will have macros and/or code-gen to help with this, but for now, we need some scaffolding in /shared/src/lib.rs. You'll notice that we are re-exporting the Request type and the capabilities we want to use in our native Shells, as well as our public types from the shared library.

pub mod app;

use lazy_static::lazy_static;
use wasm_bindgen::prelude::wasm_bindgen;

pub use crux_core::{bridge::Bridge, Core, Request};

pub use app::*;

// TODO hide this plumbing

uniffi::include_scaffolding!("shared");

lazy_static! {
    static ref CORE: Bridge<Effect, Counter> = Bridge::new(Core::new::<Capabilities>());
}

#[wasm_bindgen]
pub fn process_event(data: &[u8]) -> Vec<u8> {
    CORE.process_event(data)
}

#[wasm_bindgen]
pub fn handle_response(uuid: &[u8], data: &[u8]) -> Vec<u8> {
    CORE.handle_response(uuid, data)
}

#[wasm_bindgen]
pub fn view() -> Vec<u8> {
    CORE.view()
}

The app

Now we are in a position to create a basic app in /shared/src/app.rs. This is from the simple Counter example (which also has tests, although we're not showing them here):

use crux_core::{render::Render, App};
use crux_macros::Effect;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Clone, Debug)]
pub enum Event {
    Increment,
    Decrement,
    Reset,
}

#[derive(Default)]
pub struct Model {
    count: isize,
}

#[derive(Serialize, Deserialize, Clone)]
pub struct ViewModel {
    pub count: String,
}

#[cfg_attr(feature = "typegen", derive(crux_macros::Export))]
#[derive(Effect)]
#[effect(app = "Counter")]
pub struct Capabilities {
    render: Render<Event>,
}

#[derive(Default)]
pub struct Counter;

impl App for Counter {
    type Event = Event;
    type Model = Model;
    type ViewModel = ViewModel;
    type Capabilities = Capabilities;

    fn update(&self, event: Self::Event, model: &mut Self::Model, caps: &Self::Capabilities) {
        match event {
            Event::Increment => model.count += 1,
            Event::Decrement => model.count -= 1,
            Event::Reset => model.count = 0,
        };

        caps.render.render();
    }

    fn view(&self, model: &Self::Model) -> Self::ViewModel {
        ViewModel {
            count: format!("Count is: {}", model.count),
        }
    }
}

Make sure everything builds OK

cargo build

Create the shared types crate

This crate serves as the container for type generation for the foreign languages.

Copy over the shared_types folder from the counter example.
Edit the build.rs file and make sure that your app type is registered. You may also need to register any nested enum types (due to a current limitation with the reflection library, see https://github.com/zefchain/serde-reflection/tree/main/serde-reflection#supported-features). Here is an example of this from the build.rs file in the shared_types crate of the notes example:

use crux_core::typegen::TypeGen;
use shared::{NoteEditor, TextCursor};
use std::path::PathBuf;

fn main() {
    println!("cargo:rerun-if-changed=../shared");

    let mut gen = TypeGen::new();

    gen.register_app::<NoteEditor>().expect("register");

    // Note: currently required as we can't find enums inside enums, see:
    // https://github.com/zefchain/serde-reflection/tree/main/serde-reflection#supported-features
    gen.register_type::<TextCursor>().expect("register");

    let output_root = PathBuf::from("./generated");

    gen.swift("SharedTypes", output_root.join("swift"))
        .expect("swift type gen failed");

    // TODO these are for later
    //
    // gen.java("com.example.counter.shared_types", output_root.join("java"))
    //     .expect("java type gen failed");

    gen.typescript("shared_types", output_root.join("typescript"))
        .expect("typescript type gen failed");
}

Tip

For the above to compile, your Capabilities struct must implement the Export trait. There is a derive macro that can do this for you, e.g.:

#[cfg_attr(feature = "typegen", derive(crux_macros::Export))]
pub struct Capabilities {
    pub render: Render<Event>,
    pub http: Http<Event>,
}

Make sure everything builds and foreign types get generated into the generated folder.
```
cargo build
```

Success

You should now be ready to set up iOS, Android, or web specific builds.

Crux: Cross-platform app development in Rust