/wasmtime-rb

Ruby WebAssembly runtime powered by Wasmtime

Primary LanguageRustApache License 2.0Apache-2.0

wasmtime-rb

Ruby embedding of Wasmtime

A Bytecode Alliance project

CI status

Goal

wasmtime-rb's goal is to expose the full power of Wasmtime in Ruby with minimal overhead, serving as a foundation layer for other projects or gems.

Installation

Add the wasmtime gem to your Gemfile and run bundle install:

gem "wasmtime"

Alternatively, you can install the gem manually:

gem install wasmtime

Precompiled gems

We recommend installing the wasmtime precompiled gems available for Linux, macOS, and Windows. Installing a precompiled gem avoids the need to compile from source code, which is generally slower and less reliable.

When installing the wasmtime gem for the first time using bundle install, Bundler will automatically download the precompiled gem for your current platform. However, you will need to inform Bundler of any additional platforms you plan to use.

To do this, lock your Bundle to the required platforms you will need from the list of supported platforms below:

bundle lock --add-platform x86_64-linux # Standard Linux (e.g. Heroku, GitHub Actions, etc.)
bundle lock --add-platform x86_64-linux-musl # MUSL Linux deployments (i.e. Alpine Linux)
bundle lock --add-platform aarch64-linux # ARM64 Linux deployments (i.e. AWS Graviton2)
bundle lock --add-platform x86_64-darwin # Intel MacOS (i.e. pre-M1)
bundle lock --add-platform arm64-darwin # Apple Silicon MacOS  (i.e. M1)

Usage

Example usage:

require "wasmtime"

# Create an engine. Generally, you only need a single engine and can
# re-use it throughout your program.
engine = Wasmtime::Engine.new

# Compile a Wasm module from either Wasm or WAT. The compiled module is
# specific to the Engine's configuration.
mod = Wasmtime::Module.new(engine, <<~WAT)
  (module
    (func $hello (import "" "hello"))
    (func (export "run") (call $hello))
  )
WAT

# Create a store. Store can keep state to be re-used in Funcs.
store = Wasmtime::Store.new(engine, {count: 0})

# Define a Wasm function from Ruby code.
func = Wasmtime::Func.new(store, [], []) do |caller|
  puts "Hello from Func!"
  caller.store_data[:count] += 1
  puts "Ran #{caller.store_data[:count]} time(s)"
end

# Build the Wasm instance by providing its imports.
instance = Wasmtime::Instance.new(store, mod, [func])

# Run the `run` export.
instance.invoke("run")

# Or: get the `run` export and call it.
instance.export("run").to_func.call

For more, see examples or the API documentation.