The Wasmi CLI Application
A lightweight WebAssembly interpreter CLI built on top of the Wasmi crate.
This application provides a command-line interface for executing WebAssembly modules (.wasm) and WebAssembly script files (.wast). It supports WASI, configurable compilation strategies and fuel metering.
For details about the Wasmi project itself (architecture, design goals, embedding API, no_std support, etc.), see the Wasmi repository or the Wasmi blog.
Overview
wasmi is intended for:
- Deterministic and efficient WebAssembly execution
- Embedded and constrained environments
- WASI-compatible execution
Build / Install
Build from source:
The resulting binary will be located at target/release/wasmi from the root of the git repository.
Alternatively, build and install the wasmi binary from the latest release on crates.io:
NOTE: codegen-units = 1 is required to avoid stack overflows when not using wasmi's portable-dispatch feature. This configuration is preset in Wasmi's release profile.
Usage
Commands
| Command | Description |
|---|---|
run |
Executes a WebAssembly module |
wast |
Executes a WebAssembly Script (.wast) file |
help |
Prints help information |
When no command is provided, the run command is used if the run crate feature is enabled. This feature is enabled by default.
Running a WebAssembly Module
Execute the foo.wasm Wasm module.
Execute the foo.wasm Wasm module and provide a b c as WASI arguments.
Execute the function bar from the foo.wasm Wasm module and provide a b c as parameters.
WASI Integration
Wasmi provides support for WASI 0.1 (preview 1, released in 2019). There is presently no plan to officially add support for WASI 0.2 or newer.
Pre-open Directories
Preopen a host directory for guest access.
Environment Variables
Add an environment variable visible to the guest.
TCP Listening Socket
Provide a listening socket to the module for WASI socket operations.
Compilation Modes
Control Wasmi’s compilation mode:
Where <MODE> is any of eager, lazy-translation or lazy.
Fuel Metering
Enable deterministic execution fuel limits to make sure any execution halts.
Executing .wast Files
Executes the foo.wast Wasm script.
This is primarily intended for specification testing, conformance validation and regression testing of the Wasmi interpreter.
Crate Features
| Feature | Default | Description |
|---|---|---|
run |
✅ | Enables execution of WebAssembly modules (.wasm). This is the primary functionality most users require. Can be disabled via --no-default-features to build a reduced binary. |
wat |
✅ | Allows the run command to accept WebAssembly Text (.wat) modules in addition to .wasm. |
wast |
✅ | Enables execution of WebAssembly Script (.wast) files. Primarily intended for specification testing and interpreter debugging. Enabled by default for CLI parity with other WebAssembly runtimes. |
wasi |
✅ | Enables WASI support when executing modules via run, including environment variables, preopened directories, and socket support. |
simd |
❌ | Enables support for WebAssembly SIMD proposal for both module execution and script testing. Disabled by default due to significant bloat. |
portable-dispatch |
❌ | Allows to compile Wasmi universally at the cost of execution performance. Use --profile bench to counteract performance regressions to some extend. |
indirect-dispatch |
❌ | Uses a slightly more compact IR encoding at the cost of execution performance. |
unstable |
❌ | Enables unstable Rust compiler features in Wasmi. (e.g. become) Only usable when disabling default features via --no-default-features and requires a nightly Rust compiler. |
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.