wasm3

go-wasm3

Golang wrapper for WASM3, WIP.

This is part of a series of WASM-related experiments: go-wavm and go-wasm-benchmark.

About this fork

This is a fork of go-wasm3 by matiasinsaurralde starting from another fork.

Changes

• Add android static libraries to allow building in gomobile
• Add Runtime.ResizeMemory()
• Add Module.LinkRawFunction()
• Remove Function.CallWithArgs()
• Allow any compatible input/output type in Function.Call()

Build example for Android:

set -ex

mkdir -p /tmp/gomobile
docker run -it \
    --mount type=bind,source=$HOME/git,target=/root/git,readonly \
    --mount type=bind,source=/tmp/gomobile,target=/tmp/gomobile \
    ed255/gomobile-android:latest \
    /bin/bash -c 'set -ex && \
        apt-get update && \
        apt-get install -y cmake && \
        rm -r /tmp/gomobile/git || true && \
        mkdir -p /tmp/gomobile/git && \
        cp -r /root/git/go-wasm3 /tmp/gomobile/git && \
        cp -r /root/git/wasm3 /tmp/gomobile/git && \
        cd /tmp/gomobile/git/wasm3 && \
        cd android && \
        rm -r build || true && \
        mkdir build && \
        cd build && \
        NDK_HOME=/opt/android-ndk/android-ndk-r20 ../make_all.sh && \
        cp -r android /tmp/gomobile/git/go-wasm3/lib/
        cd /tmp/gomobile/git/go-wasm3 && \
        go build && \
        gomobile bind -androidapi=16 --target android -o /tmp/gomobile/wasm.aar'
    # /bin/bash

Install/build

This package ships with pre-built WASM3 libraries (static builds) for Linux and Android. If you want to hack around it, check the original repository.

Check the building instructions for Android if you want to rebuild the static libraries.

If you're using one of the mentioned platforms, you may install the package using go get:

$ go get -u github.com/iden3/go-wasm3

To inspect or run the little sample use:

$ cd go-wasm3/examples/sum
$ go build # or "go run sum.go"
$ ./sum

The output will look as follows:

2020/01/15 09:51:24 Initializing WASM3
2020/01/15 09:51:24 Runtime ok
2020/01/15 09:51:24 Read WASM module (139 bytes)
2020/01/15 09:51:24 Module loaded
2020/01/15 09:51:24 Calling function
Result: 3
Result: 4

You will find additional sample projects in the next section.

Sample projects

boa

This program uses the boa engine to evaluate JS code. Boa is an embeddable JS engine written in Rust, for this sample it was compiled targeting WASM.

Link here.

libxml

This program loads libxml2 as a WASM module (it's a custom build, full instructions here). The library is used to validate a XML file against a XSD (both loaded from the Go side).

Link here.

Memory access

Take the following sample program:

#include <stdlib.h>
#include <string.h>

char* somecall() {
    // Allocate a few bytes on the heap:
    char* test = (char*) malloc(12*sizeof(char));

    // Copy a string into the previously defined address:
    strcpy(test, "testingonly");

    // Return the pointer:
    return test;
}

Build it using wasicc, this will generate a cstring.wasm file (WASM module):

wasicc cstring.c -Wl,--export-all -o cstring.wasm

The following Go code will load the WASM module and retrieve the data after calling somecall:

    // Initialize the runtime and load the module:
    env := wasm3.NewEnvironment()
	defer env.Destroy()
	runtime := wasm3.NewRuntime(env, 64*1024)
	defer runtime.Destroy()
    wasmBytes, err := ioutil.ReadFile("program.wasm")
	module, _ := env.ParseModule(wasmBytes)
	runtime.LoadModule(module)
    fn, _ := runtime.FindFunction(fnName)

    // Call somecall and get the pointer to our data:
    result := fn()
    
    // Reconstruct the string from memory:
    memoryLength = runtime.GetAllocatedMemoryLength()
    mem := runtime.GetMemory(memoryLength, 0)
    
    // Initialize a Go buffer:
	buf := new(bytes.Buffer)
	for n := 0; n < memoryLength; n++ {
		if n < result {
			continue
		}
		value := mem[n]
		if value == 0 {
			break
        }
		buf.WriteByte(value)
    }

    // Print the string: "testingonly"
    str := buf.String()
    fmt.Println(str)

For more details check this.

Limitations and future

This is a WIP. Stay tuned!

Related projects

A Rust wrapper is available here.

License

MIT.

wasm3 is also under this license.