gojs

README

Overview

When GOOS=js and GOARCH=wasm, Go's compiler targets WebAssembly Binary format (%.wasm).

Wazero's "github.com/AR1011/wazero/experimental/gojs" package allows you to run a %.wasm file compiled by Go. This is similar to what is implemented in wasm_exec.js. See https://wazero.io/languages/go/ for more.

Example

wazero includes an example that implements the cat utility.

Experimental

Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise." Accordingly, wazero cannot guarantee this will work from release to release, or that usage will be relatively free of bugs. Moreover, GOOS=wasip1 will be shipped in Go 1.21. wazero will remove this package after Go 1.22 is released.

Due to these concerns and the relatively high implementation overhead, most will choose TinyGo instead of gojs.

Documentation

Overview

Package gojs allows you to run wasm binaries compiled by Go when `GOOS=js GOARCH=wasm`. See https://wazero.io/languages/go/ for more.

Experimental

Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise." Accordingly, wazero cannot guarantee this will work from release to release, or that usage will be relatively free of bugs. Moreover, `GOOS=wasi` will happen, and once that's available in two releases wazero will remove this package.

Due to these concerns and the relatively high implementation overhead, most will choose TinyGo instead of gojs.

Index

• func Instantiate(ctx context.Context, r wazero.Runtime, guest wazero.CompiledModule) (api.Closer, error)
• func MustInstantiate(ctx context.Context, r wazero.Runtime, guest wazero.CompiledModule)
• func Run(ctx context.Context, r wazero.Runtime, compiled wazero.CompiledModule, ...) error
• type Config
  • func NewConfig(moduleConfig wazero.ModuleConfig) Config
• type FunctionExporter
  • func NewFunctionExporter() FunctionExporter

Functions

func Instantiate

func Instantiate(ctx context.Context, r wazero.Runtime, guest wazero.CompiledModule) (api.Closer, error)

Instantiate detects and instantiates host functions for wasm compiled with `GOOS=js GOARCH=wasm`. `guest` must be a result of `r.CompileModule`.

Notes

• Failure cases are documented on wazero.Runtime InstantiateModule.
• Closing the wazero.Runtime has the same effect as closing the result.
• To add more functions to `goModule`, use FunctionExporter.

func MustInstantiate

func MustInstantiate(ctx context.Context, r wazero.Runtime, guest wazero.CompiledModule)

MustInstantiate calls Instantiate or panics on error.

This is a simpler function for those who know host functions are not already instantiated, and don't need to unload them separate from the runtime.

func Run

func Run(ctx context.Context, r wazero.Runtime, compiled wazero.CompiledModule, moduleConfig Config) error

Run instantiates a new module and calls "run" with the given config.

Parameters

• ctx: context to use when instantiating the module and calling "run".
• r: runtime to instantiate both the host and guest (compiled) module in.
• compiled: guest binary compiled with `GOOS=js GOARCH=wasm`
• config: the Config to use including wazero.ModuleConfig or extensions of it.

Example

After compiling your Wasm binary with wazero.Runtime's `CompileModule`, run it like below:

// Instantiate host functions needed by gojs
gojs.MustInstantiate(ctx, r)

// Assign any configuration relevant for your compiled wasm.
config := gojs.NewConfig(wazero.NewConfig())

// Run your wasm, notably handing any ExitError
err = gojs.Run(ctx, r, compiled, config)
if exitErr, ok := err.(*sys.ExitError); ok && exitErr.ExitCode() != 0 {
	log.Panicln(err)
} else if !ok {
	log.Panicln(err)
}

Notes

• Wasm generated by `GOOS=js GOARCH=wasm` is very slow to compile: Use wazero.RuntimeConfig with wazero.CompilationCache when re-running the same binary.
• The guest module is closed after being run.

Types

type Config

type Config interface {
	// WithOSWorkdir sets the initial working directory used to Run Wasm to
	// the value of os.Getwd instead of the default of root "/".
	//
	// Here's an example that overrides this to the current directory:
	//
	//	err = gojs.Run(ctx, r, compiled, gojs.NewConfig(moduleConfig).
	//			WithOSWorkdir())
	//
	// Note: To use this feature requires mounting the real root directory via
	// wazero.FSConfig `WithDirMount`. On windows, this root must be the same drive
	// as the value of os.Getwd. For example, it would be an error to mount `C:\`
	// as the guest path "", while the current directory is inside `D:\`.
	WithOSWorkdir() Config
}

Config extends wazero.ModuleConfig with GOOS=js specific extensions. Use NewConfig to create an instance.

func NewConfig

func NewConfig(moduleConfig wazero.ModuleConfig) Config

NewConfig returns a Config that can be used for configuring module instantiation.

type FunctionExporter

type FunctionExporter interface {
	// ExportFunctions builds functions to an existing host module builder.
	//
	// This should be named "go" or "gojs", depending on the version of Go the
	// guest was compiled with. The module name changed from "go" to "gojs" in
	// Go 1.21.
	ExportFunctions(wazero.HostModuleBuilder)
}

FunctionExporter builds host functions for wasm compiled with `GOOS=js GOARCH=wasm`.

func NewFunctionExporter

func NewFunctionExporter() FunctionExporter

NewFunctionExporter returns a FunctionExporter object.