The wasm utility is a command-line WebAssembly runtime that can parse, validate, instantiate, and execute WebAssembly modules. It supports WASI (WebAssembly System Interface) for system interactions and provides integration with JavaScript functions.
Usage
Basic syntax
wasm [options] <file.wasm>
Command-line options
Module operations
| Option | Description |
|---|
-p, --print | Print the parsed WebAssembly module |
--print-compiled | Print the compiled module bytecode |
-f, --print-function <address> | Print specific function bytecode by address |
-i, --instantiate | Instantiate the module (resolve imports and initialize) |
Execution options
| Option | Description |
|---|
-e, --execute <name> | Execute the named exported function (implies -i) |
--arg <value> | Supply arguments to the function (see value format below) |
-l, --link <file> | Link with additional WASM modules to resolve imports |
--export-noop | Export no-op stub functions for all imports |
WASI support
| Option | Description |
|---|
-w, --wasi | Enable WASI (WebAssembly System Interface) |
--wasi-map-dir <path[:path]> | Map host directory to WASI filesystem |
<args> | Positional arguments passed to WASI module |
WASI is not available on Windows builds.
JavaScript integration
| Option | Description |
|---|
--export-js <spec> | Export JavaScript function as WASM import (see format below) |
--arg option accepts values in the following formats:
Scalar values
wasm --arg "i32.const:42" module.wasm
wasm --arg "i64.const:1000" module.wasm
wasm --arg "f32.const:3.14" module.wasm
wasm --arg "f64.const:2.718" module.wasm
wasm --arg "f32.const:nan" module.wasm
wasm --arg "f64.const:inf" module.wasm
Vector values (v128)
Hexadecimal format:
wasm --arg "v128.const:0x01000000020000000300000004000000" module.wasm
wasm --arg "v(i32.const:1, i32.const:2, i32.const:3, i32.const:4)" module.wasm
When using vector component format, all values must have the same type. Mixed types will result in an error.
Smaller integer types
wasm --arg "i8.const:127" module.wasm
wasm --arg "i16.const:32767" module.wasm
--export-js option uses this format:
module.function(arg:type,...):returnType=source
Examples
# Export simple function
wasm --export-js "env.log(x:i32):i32=console.log(x)" module.wasm
# Export with multiple arguments
wasm --export-js "env.add(a:i32,b:i32):i32=a + b" module.wasm
# Export with f64 return
wasm --export-js "math.sqrt(x:f64):f64=Math.sqrt(x)" module.wasm
# Export without return value
wasm --export-js "env.print(msg:i32)=console.log(msg)" module.wasm
Supported types
i32 - 32-bit integeri64 - 64-bit integerf32 - 32-bit floatf64 - 64-bit floatv128 - 128-bit vector
Examples
Parse and print a module
Instantiate and execute a function
wasm --execute "_start" module.wasm
Execute with arguments
wasm --execute "add" --arg "i32.const:10" --arg "i32.const:20" module.wasm
Link multiple modules
wasm --link utils.wasm --execute "main" app.wasm
WASI module execution
wasm --wasi --execute "_start" wasi-app.wasm arg1 arg2 arg3
Map host directories to WASI
wasm --wasi --wasi-map-dir "/tmp:/sandbox" --execute "_start" app.wasm
wasm --wasi --wasi-map-dir "/home/user/data" --execute "_start" app.wasm
When no mapping is specified (e.g., /home/user/data), the directory is mapped to the same path in the WASI filesystem.
Export JavaScript functions
wasm --export-js "env.log(x:i32)=console.log(x)" \
--execute "main" module.wasm
Debug compiled bytecode
wasm --instantiate --print-compiled module.wasm
Export no-op stubs for testing
wasm --export-noop --instantiate module.wasm
Module structure
When using --print, the utility displays:
- Module sections
- Function signatures
- Import/export declarations
- Memory and table definitions
Compiled bytecode
When using --print-compiled, displays:
- Function addresses
- Stack usage hints
- Instruction sequences
- Register assignments
Function return values
Execution results are printed to stderr:
$ wasm --execute "add" --arg "i32.const:5" --arg "i32.const:3" module.wasm
Returned:
-> 8 (i32)
WASI implementation
Supported WASI functions
The WASI implementation supports:
- Command-line argument access
- Environment variable access
- File system operations via preopened directories
- Standard input/output/error
Exit codes
WASI modules can exit with custom exit codes:
wasm --wasi --execute "_start" app.wasm
echo $? # Prints the exit code
If a WASM trap contains exit:N, the utility returns the negated exit code. For example, exit:0 returns 0, and exit:1 returns -1.
Error handling
Parse errors
$ wasm invalid.wasm
Failed to open invalid.wasm: No such file or directory
Link errors
$ wasm --instantiate module.wasm
Linking main module failed
Missing import 'env.memory'
Runtime traps
$ wasm --execute "divide" --arg "i32.const:10" --arg "i32.const:0" module.wasm
Execution trapped: integer divide by zero
Advanced features
Module linking
You can link multiple WASM modules to resolve imports:
wasm --link lib1.wasm --link lib2.wasm --execute "main" app.wasm
Bytecode inspection
Inspect compiled bytecode for specific functions:
wasm --instantiate --print-function 5 module.wasm
- Instruction pointer
- Register allocations
- Source/destination mappings
JavaScript callbacks
WASM modules can call back into JavaScript:
wasm --export-js "env.callback(x:i32):i32=x * 2" \
--execute "process" module.wasm
Implementation details
WebAssembly engine
The utility uses LibWasm, Ladybird’s WebAssembly implementation:
- Full WebAssembly 1.0 support
- Bytecode interpreter
- Register allocation optimization
- Module validation
JavaScript integration
JavaScript exports are compiled using LibJS and executed through the bytecode interpreter. Type conversions are automatic:
- WASM integers → JS numbers
- WASM floats → JS numbers
- WASM v128 → JS BigInt
- js - JavaScript interpreter (can execute WASM-generated JS glue code)
- test262-runner - Test runner that may include WASM-related tests
Source code
Source file: Utilities/wasm.cpp