• Stars
    star
    2,679
  • Rank 17,052 (Top 0.4 %)
  • Language
    Go
  • License
    MIT License
  • Created over 5 years ago
  • Updated 12 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🐹🕸️ WebAssembly runtime for Go

A complete and mature WebAssembly runtime for Go based on Wasmer.

Features

  • Easy to use: The wasmer API mimics the standard WebAssembly API,
  • Fast: wasmer executes the WebAssembly modules as fast as possible, close to native speed,
  • Safe: All calls to WebAssembly will be fast, but more importantly, completely safe and sandboxed.

Documentation: browse the detailed API documentation full of examples.

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

Install

To install the library, follow the classical:

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

And you're ready to get fun!

Supported platforms

This library embeds the Wasmer runtime compiled as shared library objects, and so uses cgo to consume it. A set of precompiled shared library objects are provided. Thus this library works (and is tested) on the following platforms:

Platform Architecture Triple Status
Linux amd64 x86_64-unknown-linux-gnu
aarch64 aarch64-unknown-linux-gnu
Darwin amd64 x86_64-apple-darwin
aarch64 aarch64-apple-darwin
Windows amd64 x86_64-pc-windows-msvc
What to do if your platform is missing?

Up to now, there is no script to automate that process. We are working on it.

Here are the steps to do that manually:

$ # 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.
$ just test -tags custom_wasmer_runtime

Examples

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

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

#[no_mangle]
pub extern "C" fn sum(x: i32, y: i32) -> i32 {
    x + y
}

A compiled WebAssembly binary is included in examples/appendices/simple.wasm.

Then, we can execute it in Go:

package main

import (
	"fmt"
	"io/ioutil"
	wasmer "github.com/wasmerio/wasmer-go/wasmer"
)

func main() {
    wasmBytes, _ := ioutil.ReadFile("simple.wasm")

    engine := wasmer.NewEngine()
    store := wasmer.NewStore(engine)

    // Compiles the module
    module, _ := wasmer.NewModule(store, wasmBytes)

    // Instantiates the module
    importObject := 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.go
42

Testing

Run the tests with the following command:

$ just test

What is WebAssembly?

Quoting the WebAssembly site:

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

About speed:

WebAssembly aims to execute at native speed by taking advantage of common hardware capabilities available on a wide range of platforms.

About safety:

WebAssembly describes a memory-safe, sandboxed execution environment […].

License

The entire project is under the MIT License. Please read the LICENSE file.

FAQ

How to run Go programs compiled to WebAssembly modules with wasmer-go?

Let's start by emphasing that wasmer-go is a WebAssembly runtime. It allows to run WebAssembly inside Go. It's not a tool to compile a Go program into WebAssembly. Nonetheless, many people are reporting issues when compiling Go programs to WebAssembly, and then trying to run them with wasmer-go (or in another hosts, like Python, C, PHP, Ruby, Rust…).

The major problem is that, whilst the Go compiler supports WebAssembly, it does not support WASI (WebAssembly System Interface). It generates an ABI that is deeply tied to JavaScript, and one needs to use the wasm_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. Use TinyGo to compile your Go program to WebAssembly with the -target wasi option, e.g.:

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

    The generated WebAssembly module will be portable across all WebAssembly 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 .

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

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

    and follow their documentation.

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

More Repositories

1

wasmer

🚀 The leading Wasm Runtime supporting WASIX, WASI and Emscripten
Rust
16,915
star
2

wasmer-python

🐍🕸 WebAssembly runtime for Python
Rust
1,999
star
3

wasmer-php

🐘🕸️ WebAssembly runtime for PHP
PHP
964
star
4

winterjs

Winter is coming... ❄️
JavaScript
844
star
5

wasmer-js

Monorepo for Javascript WebAssembly packages by Wasmer
Rust
828
star
6

kernel-wasm

Sandboxed kernel mode WebAssembly runtime.
C
702
star
7

wasmer-java

☕ WebAssembly runtime for Java
Java
544
star
8

awesome-wasi

😎 Curated list of awesome things regarding WebAssembly WASI ecosystem.
476
star
9

wasmer-ruby

💎🕸 WebAssembly runtime for Ruby
Rust
462
star
10

wasmer-postgres

💽🕸 Postgres library to run WebAssembly binaries.
Rust
392
star
11

wapm-cli

📦 WebAssembly Package Manager (CLI)
Rust
368
star
12

webassembly.sh

Open-source and installable PWA terminal powered by WebAssembly, WAPM, and Wasmer-JS 🖥
JavaScript
269
star
13

wasmer-rust-example

Example of WebAssembly embedding in Rust using Wasmer
Rust
163
star
14

ate

Distributed immutable data store with strong encryption and authentication
Rust
129
star
15

vscode-wasm

WebAssembly extension for VSCode
Rust
122
star
16

wai

A language binding generator for `wai` (a precursor to WebAssembly interface types)
Rust
110
star
17

rusty_jsc

Rust bindings for the JavaScriptCore engine.
Rust
86
star
18

wasmer-c-api

Example of the C API to embed the Wasmer runtime
C
76
star
19

io-devices-lib

Library for interacting with the Wasmer Experimental IO Devices
WebAssembly
51
star
20

wasmer-pack

Rust
49
star
21

sonde-rs

A library to compile USDT probes into a Rust library
Rust
44
star
22

old-docs.wasmer.io

Wasmer Documentation (for standalone and embedded use cases)
WebAssembly
41
star
23

wasmer-install

Wasmer Binary Installer https://wasmer.io/
Shell
39
star
24

loupe

Profiling tool for Rust code.
Rust
35
star
25

c-wasm-simd128-example

Example C++ repo emitting Wasm SIMD 128 instructions
C++
30
star
26

wasmer-nginx-example

This is a simple example of Nginx running with wasmer
HTML
29
star
27

wasmer-ocaml

OCaml bindings for Wasmer
OCaml
28
star
28

cargo-wasmer

A cargo sub-command for publishing Rust crates to the WebAssembly Package Manager.
Rust
24
star
29

wasm-fuzz

Fuzzer for Wasm and Wasmer
JavaScript
22
star
30

wasmer.io

The Wasmer.io website
JavaScript
21
star
31

wasmer-bench

This is a repo for benchmarking Wasmer (compilation & runtime)
Rust
20
star
32

wcgi-wordpress-demo

PHP
15
star
33

wcgi-php-template

PHP
14
star
34

docs.wasmer.io

The Wasmer Docs Website (website deployed using Wasmer Edge)
MDX
14
star
35

setup-wasmer

GitHub action for setting up Wasmer
TypeScript
14
star
36

c-http-server

A very simple http server in c
JavaScript
13
star
37

rust-wasm-simd128-example

Example Rust repo emitting Wasm SIMD 128 instructions
Rust
10
star
38

wasm-debug

A runtime-independent crate for transforming Wasm-DWARF
Rust
9
star
39

wasmer-terminal-js

The WebAssembly terminal, revamped!
Rust
7
star
40

rust-cli-app-example

Example CLI app written in rust for Wasmer
Rust
7
star
41

wapm-publish

GitHub action for publishing to WAPM
TypeScript
7
star
42

wasmer-rust-customabi-example

An example repo to demonstrate how to create a module with a custom ABI to then use it from an embedder
Rust
6
star
43

wasm-interface-cli

A binary for verifying Wasm interfaces
Rust
6
star
44

interface-types

The `wasmer-interface-types` crate
Rust
5
star
45

ewasm-workshop

Ewasm workshow with Wasmer Metering
Rust
5
star
46

sgp4

Rust
5
star
47

llvm-custom-builds

Sandbox to produce custom LLVM builds for various platforms
Shell
5
star
48

sha2

A WebAssembly interface to Rust's sha2 crate
Rust
5
star
49

wasm-python-api

WebAssembly Python standard API prototype
Python
4
star
50

python-flask-example

Sample Python Flask server for Wasmer Edge
Python
4
star
51

shared-buffer

An abstraction over buffers backed by memory-mapped files or bytes in memory
Rust
3
star
52

wcgi-rust-template

Rust
3
star
53

wasmer-toml

Split out the wapm.toml parsing from wasmerio/wapm-cli
Rust
3
star
54

wasmer-nightly

Nightly releases of Wasmer
3
star
55

llvm-build

LLVM Distribution for being used with Wasmer
3
star
56

js-service-worker-example

Sample for a js service worker running on Wasmer Edge.
JavaScript
3
star
57

wasi-tests

Integration tests for WASI
Rust
2
star
58

.github

Github profile
2
star
59

wasmer-js-example

Wasmer-JS example
2
star
60

edge-react-starter

Wasmer Edge + Vite + React + TS starter template. Deploy it like it's hot 🚀
CSS
1
star
61

rustfft

Rustfft for WASM, published on WAPM
Rust
1
star
62

inline-c

Rust
1
star
63

speed.wasmer.io

Speed tracker of Wasmer
CSS
1
star
64

windows-llvm-build

Build of LLVM in Windows
1
star
65

wasmer-edge-support

1
star
66

zig2wapm

CI script to clone zig/zig to wapm.io
Shell
1
star
67

wasm4-on-wapm

This is a demo repo to showcase how to upload your WASM-4 games to WAPM
1
star
68

wai-hashids

Hashids demonstration with WAI
Rust
1
star
69

astro-starter-a1d

Astro
1
star
70

flask-starter-324

Python
1
star
71

wasmerio-flask-template

Python
1
star
72

wasmer-integration-tests

Integration tests between Edge and the backend
Rust
1
star