crywasm3

Crystal bindings for Wasm3, a small and portable WebAssembly interpreter.

Installation

Build Wasm3 first. Its CMake build produces libm3.a:

git clone https://github.com/wasm3/wasm3
cmake -S wasm3 -B wasm3-build -DBUILD_WASI=none
cmake --build wasm3-build --target m3

Then add the shard:

dependencies:
  crywasm3:
    github: mikeoz32/crywasm3

The linker looks for the library as m3. If it is in a non-standard location, pass its directory to Crystal, for example:

crystal run examples/add.cr --link-flags '-L/path/to/wasm3-build/source'

Usage

require "crywasm3"

environment = Wasm3::Environment.new
runtime = environment.new_runtime
wasm_module = environment.parse(File.read("add.wasm").to_slice)
runtime.load(wasm_module)

result = runtime.call("add", 20, 22)
puts result # => 42

runtime.close
environment.close

For normal applications, the block API handles cleanup and load_file parses and loads in one step:

Wasm3::Environment.with do |environment|
  environment.with_runtime do |runtime|
    runtime.load_file("add.wasm")
    puts runtime.find_function("add").call_i32(20, 22)
  end
end

Runtime#memory returns a bounds-checked Memory view. It supports byte access, copied reads, and an IO adapter:

memory = runtime.memory
memory.write(128, "hello")

io = memory.io(128, 5, writable: false)
puts io.gets_to_end # => hello

Memory#bytes is available for a zero-copy Bytes view. Use it only while the guest memory cannot grow; MemoryIO refreshes the pointer for each operation. The LibWasm3 module is also public for applications that need raw imports, globals, custom sections, or the low-level C API.

Host imports can be linked after loading a module. The signature uses Wasm3's notation: i, I, f, and F mean i32, i64, f32, and f64:

wasm_module.link_function("env", "get_value", "i()") do |_arguments|
  7
end

puts runtime.find_function("call").call_i32

The examples include a CLI runner, module inspection, memory IO, host imports, and error handling. For example:

crystal run examples/run_file.cr -- module.wasm add 20 22
crystal run examples/inspect.cr -- module.wasm
crystal run examples/memory_io.cr -- module.wasm 128 32

Close runtimes before their environment. close is idempotent, and the runtime keeps loaded modules alive until it is closed.

License

MIT