Repository files navigation

Wasmer Go

Website •Docs •Slack Channel

A complete and mature WebAssembly runtime for Go based onWasmer.

Features

• Easy to use: Thewasmer API mimics the standard WebAssembly API,
• Fast:wasmer executes the WebAssembly modules as fast aspossible, close tonative speed,
• Safe: All calls to WebAssembly will be fast, but moreimportantly, completely safe and sandboxed.

Documentation:browse the detailed APIdocumentationfull of examples.

Examples as tutorials:browse theexamples/directory,it's the best place for a complete introduction!

To install the library, follow the classical:

$ go get github.com/wasmerio/wasmer-go/wasmer

And you're ready to get fun!

This library embeds the Wasmer runtime compiled as shared libraryobjects, and so usescgo to consumeit. A set of precompiled shared library objects are provided. Thusthis library works (and is tested) on the following platforms:

$# Build the new Wasmer C API shared object library.$ cargo build --release$$# Configure cgo.$export CGO_CFLAGS="-I$(pwd)/wasmer/packaged/include/"$export CGO_LDFLAGS="-Wl,-rpath,$(pwd)/target/release/ -L$(pwd)/target/release/ -lwasmer_go"$$# Run the tests.$ justtest -tags custom_wasmer_runtime

We highly recommend to read theexamples/directory, which contains a sequence of examples/tutorials. It's thebest place to learn by reading examples.

But for the most eager of you, there is a quick toy program inexamples/appendices/simple.go, written in Rust:

#[no_mangle]pubextern"C"fnsum(x:i32,y:i32) ->i32{    x + y}

A compiled WebAssembly binary is included inexamples/appendices/simple.wasm.

Then, we can execute it in Go:

package mainimport ("fmt""os"wasmer"github.com/wasmerio/wasmer-go/wasmer")funcmain() {wasmBytes,_:=os.ReadFile("simple.wasm")engine:=wasmer.NewEngine()store:=wasmer.NewStore(engine)// Compiles the modulemodule,_:=wasmer.NewModule(store,wasmBytes)// Instantiates the moduleimportObject:=wasmer.NewImportObject()instance,_:=wasmer.NewInstance(module,importObject)// Gets the `sum` exported function from the WebAssembly instance.sum,_:=instance.Exports.GetFunction("sum")// Calls that exported function with Go standard values. The WebAssembly// types are inferred and values are casted automatically.result,_:=sum(5,37)fmt.Println(result)// 42!}

And then, finally, enjoy by running:

$cd examples/appendices/$ go run simple.go42

Run the tests with the following command:

$ justtest

Quotingthe WebAssembly site:

WebAssembly (abbreviated Wasm) is a binary instruction format for astack-based virtual machine. Wasm is designed as a portable targetfor compilation of high-level languages like C/C++/Rust, enablingdeployment on the web for client and server applications.

About speed:

WebAssembly aims to execute at native speed by taking advantage ofcommon hardwarecapabilitiesavailable on a wide range of platforms.

About safety:

WebAssembly describes a memory-safe, sandboxedexecutionenvironment […].

The entire project is under the MIT License. Please readtheLICENSE file.

Let's start by emphasing thatwasmer-go is a WebAssembly runtime. Itallows torun WebAssembly inside Go. It's not a tool tocompile aGo program into WebAssembly. Nonetheless, many people are reportingissues when compiling Go programs to WebAssembly, and then trying torun them withwasmer-go (or in another hosts, likePython,C,PHP,Ruby,Rust…).

The major problem is that, whilst the Go compiler supportsWebAssembly,it does not supportWASI (WebAssembly SystemInterface). It generates an ABI that is deeply tied to JavaScript, andone needs to use thewasm_exec.js file provided by the Go toolchain,which doesn't work outside a JavaScript host.

Fortunately, there are two solutions to this problem:

1. UseTinyGo to compile your Go program toWebAssembly with the-target wasi option, e.g.:

   $ tinygo build -o module.wasm -target wasi.

   The generated WebAssembly module will be portable across allWebAssembly runtimes that support WASI.

2. Use the Go compiler with adapters. Let's see how to compile:

   $ GOOS=js GOARCH=wasm go build -o module.wasm.

   (theGOOS=js is the sign that JavaScript is targeted, not a surprise).

   Then pick one adapter (they are written by the community):

   • mattn/gowasmer,
   • go-wasm-adapter/go-wasm,

   and follow their documentation.

We highly recommend the first solution (with TinyGo) if it works foryou as the WebAssembly module will be portable across all WebAssemblyruntimes. It's not a hacky solution based on adapters; it's the rightway to… go.