Warning

This is the next branch and contains unreleased changes. See v0.10.0 for the latest released version.

tinywasm

Why tinywasm?

• Tiny: Small by design, while still passing the full WebAssembly 3.0 core test suite.
• Portable: Runs anywhere Rust can target, supports no_std, has minimal dependencies¹, and can itself compile to WebAssembly.
• Safe by default: Written entirely in safe Rust².

Installation

[dependencies]
tinywasm = "0.10"

Usage

use tinywasm::{ModuleInstance, Store};

// Load a module from bytes
let wasm = include_bytes!("../examples/wasm/add.wasm");
let module = tinywasm::parse_bytes(wasm)?;

// Create a new store
let mut store = Store::default();

// Instantiate the module
let instance = ModuleInstance::instantiate(&mut store, &module, None)?;

// Call an exported function with typed parameters
let func = instance.func::<(i32, i32), i32>(&store, "add")?;
let result = func.call(&mut store, (1, 2))?;

assert_eq!(result, 3);

See the examples directory and documentation for more information.

Cargo Features

• std: Enables std and parsing from files and streams. Enabled by default.
• log: Enables integration with the log crate. Enabled by default.
• parser: Enables tinywasm-parser and top-level parse helpers. Enabled by default.
• validate: Enables WebAssembly validation while parsing. Enabled by default and configurable through ParserOptions.
• archive: Enables serialization and deserialization of the internal twasm format. Enabled by default.
• canonicalize-nans: Uses a canonical NaN for normalized NaN results. Enabled by default.
• debug: Derives Debug for runtime types. Enabled by default.
• parallel-parser: Parallelizes function parsing when std is enabled. Enabled by default.
• guest-debug: Exposes module-internal by-index inspection APIs (*_by_index).
• simd-x86: Enables x86-specific SIMD intrinsics and uses unsafe internally.

With default features disabled, tinywasm depends only on core, alloc, and libm, making it usable in no_std + alloc environments.

Use Engine and engine::Config for non-default fuel accounting, stack sizing, or GC collection thresholds. A configured ResourceLimiter can allow, reject, or trap memory and table allocation or growth requests, and GC object allocations.

Precompiled Modules

TinyWasm can serialize a parsed module to its version-specific .twasm format. Loading an archive skips WebAssembly parsing, validation, and optimization.

Applications that only load .twasm can remove the parser and validator from their binary by only enabling the archive feature. Depending on the target and release profile, this can produce binaries smaller than 300 KB.

Untrusted Input

WebAssembly validation is enabled by default through the validate feature. Keep this feature enabled and leave ParserOptions::validation enabled for modules from untrusted sources. Without validation, parsing can produce modules that violate runtime assumptions and may panic during instantiation or execution.

Validation does not limit parsing or execution resources. Hosts that run untrusted code should also set input limits, configure stack and ResourceLimiter limits, and use fuel- or time-budgeted execution as needed.

Loading .twasm checks the archive header and encoding but does not run WebAssembly validation or verify TinyWasm's runtime invariants. Load archives only from trusted sources. For untrusted input, parse a WebAssembly binary with validation enabled.

WebAssembly Proposal Support

TinyWasm generally implements non-JavaScript core proposals at phase 4 or later, with some proposals implemented earlier. The table shows current support and known exceptions.

Proposal	Status	tinywasm Version
Import/Export of Mutable Globals	🟢	0.2.0
Multi-value	🟢	0.2.0
Non-trapping Float-to-int Conversions	🟢	0.2.0
Sign-extension Operators	🟢	0.2.0
Bulk Memory Operations	🟢	0.4.0
Reference Types	🟢	0.7.0
Fixed-width SIMD	🟢	0.9.0
Tail Calls	🟢	0.9.0
Extended Constant Expressions	🟢	0.9.0
Multiple Memories	🟢	0.8.0
Relaxed SIMD	🟢	0.9.0
Custom Annotation Syntax	🟢	0.8.0
Memory64	🟢	0.9.0
Wide Arithmetic	🟢	0.9.0
Custom Page Sizes	🟢	0.9.0
Typed Function References	🟢	next
Garbage Collection	🟢	next
Exception Handling	🟢	next
Compact Import Section	🟢	next
Stack Switching	🌑	-
Threads	🌑	-

Legend
🌑 -- not available
🚧 -- in development/partially supported
🟢 -- fully supported

See Also

If you're looking for a WebAssembly runtime with JIT compilation, better performance or other advanced features, check out these other runtimes:

• wasmi - efficient and versatile WebAssembly interpreter for embedded systems
• wasm3 - a fast WebAssembly interpreter written in C
• wazero - a zero-dependency WebAssembly interpreter written in Go
• wasmer - a fast and secure WebAssembly runtime written in Rust
• wasmtime - a fast and secure WebAssembly runtime written in Rust

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in tinywasm by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Footnotes

1. The two main external components are wasmparser for WebAssembly parsing and validation, and postcard for .twasm archives. ↩

2. The optional simd-x86 feature is the only exception. It uses unsafe internally for selected x86 SIMD intrinsics. ↩