zwasm Rust SDK

zwasm-sdk provides safe, idiomatic Rust bindings to the zwasm WebAssembly runtime.

Supported Rust Version

A recent stable Rust compiler is recommended. (Rust 2021 edition)

Build and Platform Requirements

• Requires Zig 0.16.0+ in your PATH (used to build the zwasm C library)
• Supported platforms: Linux (x86_64, aarch64), macOS (aarch64)

Version Compatibility

Usage

Add this to your Cargo.toml:

[dependencies]
zwasm-sdk = "0.1"

Example (safe API)

use zwasm_sdk::{Config, Module};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let wasm_bytes = std::fs::read("your_module.wasm")?;
    let mut config = Config::new()?;
    config.set_timeout(5_000);
    let module = Module::new_configured(&wasm_bytes, &config)?;
    let results = module.invoke("main", &[])?;
    println!("results = {results:?}");
    Ok(())
}

Examples

Practical runnable examples are available in examples/:

• run_wasm.rs: Load a module, list exports, and invoke a function.
• host_imports.rs: Register host functions and call them from Wasm.
• memory_io.rs: Read/write module linear memory.
• wasi_config.rs: Configure argv/env/preopen for WASI.

Run examples with:

cargo run --example run_wasm
cargo run --example host_imports
cargo run --example memory_io
cargo run --example wasi_config

Cancellation and Interruption

Use Config::set_cancelable(true) when you want running Wasm to be interruptible from another thread.

When cancellation checks are enabled, you can obtain a thread-safe CancelHandle from Module::cancel_handle() and call cancel() from another thread or task. A running invoke() then returns an error that can be classified with ZwasmError::is_interrupted() or ZwasmError::is_canceled().

Safety and Usage Notes

zwasm-sdk provides a safe, ergonomic API for most use cases. All FFI unsafety is encapsulated. For advanced or low-level usage, see zwasm-sys.

CancelHandle is the intended way to interrupt a running invocation from another thread. Other module operations remain single-threaded.

API Reference

• API documentation on docs.rs
• zwasm C API documentation

License

MIT License. See LICENSE for details.

Contributing

Contributions, bug reports, and feature requests are welcome! See CONTRIBUTING.md for details.