tinywasm

TinyWasm does not interpret WebAssembly instructions directly. Instead, it follows a multi-stage process to optimize execution:

1. Parsing & Validation: WebAssembly is translated into a compact internal bytecode format.
2. Lowering: Structured control flow (like block, loop, if, br*) is resolved ahead of time into jump-oriented instructions such as Jump, JumpIfZero, BranchTable*, DropKeep*, and Return.
3. Optimization: A peephole optimizer (optimize.rs) performs superinstruction fusion. It combines common sequences (like binary operations with local access or comparisons with conditional branches) into single instructions to reduce interpreter dispatch overhead.
4. Execution: The runtime uses a single iterative interpreter loop over the lowered, optimized instruction stream.

This architecture allows modules to be optionally serialized as .twasm files for faster reuse, as the heavy lifting of parsing and lowering is already complete.

Use tinywasm-parser to convert WebAssembly binaries into tinywasm modules. You can use the high-level Parser struct for fine-grained control or top-level helper functions for default configurations.

Using the Parser struct

To use custom configurations, instantiate a Parser and use its methods:

• parse_module_bytes(bytes): Parses from a byte slice.
• parse_module_file(path): Parses from a file path.
• parse_module_stream(stream): Parses from an object implementing std::io::Read.

You can configure the parser using Parser::with_options(ParserOptions) to adjust settings like rewrite optimizations.

Using top-level helpers

For default settings, use the following thin wrappers:

• parse_bytes(bytes)
• parse_file(path)
• parse_stream(stream)

use tinywasm_parser::{Parser, ParserOptions};

let bytes = include_bytes!("./file.wasm");

// Default parser
let parser = Parser::new();
let module = parser.parse_module_bytes(bytes)?;

// Parser with custom options
let parser = Parser::with_options(ParserOptions::default().with_rewrite_optimization(false));
let module = parser.parse_module_bytes(bytes)?;

// Parsing from a file
let module = parser.parse_module_file("path/to/file.wasm")?;

// Parsing from a stream
let mut stream = std::fs::File::open("path/to/file.wasm")?;
let module = parser.parse_module_stream(&mut stream)?;

The tinywasm CLI provides several commands for running, compiling, and inspecting WebAssembly modules.

Supported File Formats

The run, dump, and inspect commands accept .wasm, .wat, and .twasm inputs.

Common Commands

• Run a module: tinywasm ./module.wasm. Without the --invoke flag, the CLI expects the module to have a start function or a _start export.
• Invoke a specific function: tinywasm run --invoke <name> <path> <args...>. Arguments are automatically parsed based on the function's export signature, so you do not need to specify types.
• Compile to Twasm: tinywasm compile ./module.wat -o ./module.twasm. This writes the TinyWasm twasm archive format.
• Dump module contents: tinywasm dump ./module.twasm.
• Inspect a module: tinywasm inspect ./module.wasm. This uses ANSI colors by default; set NO_COLOR=1 to disable them.
• Run WASM spec tests: tinywasm wast <path> (accepts files or folders containing .wast files).

Input via Stdin

You can use - as the input path to read a module from standard input.

$ tinywasm --help
$ tinywasm ./module.wasm
$ tinywasm run --invoke add ./module.wasm 1 2
$ tinywasm compile ./module.wat -o ./module.twasm
$ tinywasm dump ./module.twasm
$ tinywasm inspect ./module.wasm
$ tinywasm wast ./spec-tests/address.wast