emscripten

Documentation

Overview

Package emscripten contains Go-defined special functions imported by Emscripten under the module name "env".

Emscripten has many imports which are triggered on build flags. Use FunctionExporter, instead of Instantiate, to define more "env" functions.

Relationship to WASI

Emscripten typically requires wasi_snapshot_preview1 to implement exit.

See wasi_snapshot_preview1.Instantiate and https://github.com/emscripten-core/emscripten/wiki/WebAssembly-Standalone

Example (FunctionExporter)

This shows how to instantiate Emscripten function imports when you also need other functions in the "env" module.

package main

import (
	"context"

	_ "embed"
	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/wazero/imports/emscripten"
	"github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
)

//go:embed testdata/invoke.wasm
var invokeWasm []byte

func main() {
	ctx := context.Background()

	r := wazero.NewRuntime(ctx)
	defer r.Close(ctx) // This closes everything this Runtime created.

	// Add WASI which is typically required when using Emscripten.
	wasi_snapshot_preview1.MustInstantiate(ctx, r)

	// Compile the WASM so wazero can handle dynamically generated imports.
	compiled, err := r.CompileModule(ctx, invokeWasm)
	if err != nil {
		panic(err)
	}
	exporter, err := emscripten.NewFunctionExporterForModule(compiled)
	if err != nil {
		panic(err)
	}
	// Next, construct your own module builder for "env" with any functions
	// you need.
	envBuilder := r.NewHostModuleBuilder("env").
		NewFunctionBuilder().
		WithFunc(func() uint32 { return 1 }).
		Export("get_int")

	// Now, add Emscripten special function imports into it.
	exporter.ExportFunctions(envBuilder)
}

Example (InstantiateForModule)

This shows how to instantiate Emscripten function imports.

package main

import (
	"context"

	_ "embed"
	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/wazero/imports/emscripten"
	"github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
)

//go:embed testdata/invoke.wasm
var invokeWasm []byte

func main() {
	ctx := context.Background()

	r := wazero.NewRuntime(ctx)
	defer r.Close(ctx) // This closes everything this Runtime created.

	// Add WASI which is typically required when using Emscripten.
	wasi_snapshot_preview1.MustInstantiate(ctx, r)

	// Compile the WASM so wazero can handle dynamically generated imports.
	compiled, err := r.CompileModule(ctx, invokeWasm)
	if err != nil {
		panic(err)
	}

	envCloser, err := emscripten.InstantiateForModule(ctx, r, compiled)
	if err != nil {
		panic(err)
	}
	defer envCloser.Close(ctx) // This closes the env module.

}

Index

• func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error)
• func InstantiateForModule(ctx context.Context, r wazero.Runtime, guest wazero.CompiledModule) (api.Closer, error)
• func MustInstantiate(ctx context.Context, r wazero.Runtime)
• type FunctionExporter
  • func NewFunctionExporter() FunctionExporter
  • func NewFunctionExporterForModule(guest wazero.CompiledModule) (FunctionExporter, error)

Examples

• Package (FunctionExporter)
• Package (InstantiateForModule)

Functions

func Instantiate

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

Instantiate instantiates the "env" module used by Emscripten into the runtime.

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 the "env" module, use FunctionExporter.

Deprecated: Due to Emscripten dynamic import generation, InstantiateForModule should be used instead.

func InstantiateForModule

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

InstantiateForModule instantiates a module named "env" populated with any known functions used in emscripten.

func MustInstantiate

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

MustInstantiate calls Instantiate or panics on error.

This is a simpler function for those who know the module "env" is not already instantiated, and don't need to unload it.

Deprecated: Due to Emscripten dynamic import generation, InstantiateForModule should be used instead.

Types

type FunctionExporter

type FunctionExporter interface {
	// ExportFunctions builds functions to export with a wazero.HostModuleBuilder
	// named "env".
	ExportFunctions(wazero.HostModuleBuilder)
}

FunctionExporter configures the functions in the "env" module used by Emscripten.

Notes

• This is an interface for decoupling, not third-party implementations. All implementations are in wazero.

func NewFunctionExporter

func NewFunctionExporter() FunctionExporter

NewFunctionExporter returns a FunctionExporter object with trace disabled. Deprecated: Due to Emscripten dynamic import generation, NewFunctionExporterForModule should be used instead.

func NewFunctionExporterForModule

func NewFunctionExporterForModule(guest wazero.CompiledModule) (FunctionExporter, error)

NewFunctionExporterForModule returns a guest-specific FunctionExporter, populated with any known functions used in emscripten.