emscripten-rs-sys

Low-level Rust FFI bindings to the Emscripten C API, generated using bindgen.

This crate provides raw, unsafe bindings to the C API of Emscripten, allowing Rust code to interface directly with the Emscripten runtime.

⚠️ The only supported target is wasm32-unknown-emscripten.

Features

The default build provides the raw FFI bindings and supports stable Rust. The nightly feature is disabled by default. Enable it on nightly Rust to use em_js (js!, inline_js!) and em_asm (js_asm!):

emscripten_rs_sys = { version = "0.3.0", features = ["nightly"] }

Macro expansions also require feature attributes in the calling crate: #![feature(asm_experimental_arch)] for em_js, and #![feature(min_generic_const_args, generic_const_args)] for em_asm.

Prerequisites

You must have the Emscripten SDK (emsdk) installed and activated on your system before building.

Follow the official installation instructions here: Emscripten SDK Installation Guide

After installing, ensure the emcc tool is on your PATH, because the create relies on it to locate the SDK.

Linker setup

Some APIs of Emscripten only work at runtime if they are explicitly enabled at link time.

See the settings Reference for all -s options.

Ways to set linker settings:

• With the RUSTFLAG environment variable: RUSTFLAGS='-C link-args=-sALLOW_MEMORY_GROWTH=1'
• In the build script: println!("cargo:rustc-link-arg=-sALLOW_MEMORY_GROWTH=1");
• In the .cargo/config.toml with the rustflags field.

Highlights

• The complete C API is covered.
• EM_JS support for inline JS functions.

Example

Define Javascript function in Rust:

js! {
    fn compute_sum(n: c_int) -> c_int
    {
        let sum = 0;
        for(let i=1; i<n; i++)
        {
            sum += i;
        }
        return sum;
    }
}

fn test_sum() {
    assert_eq!(unsafe { compute_sum(100) }, 4950)
}

Conveniently call Javascript from Rust, with parameter type inference:

fn js_asm() {
    let a = 2;
    let b = 3;
    let result = js_asm! { 
        |a,b| -> i32 { return a+b*b; } 
    };
    assert_eq!(result, 2+3*3);
}