package emscripten

import "github.com/tetratelabs/wazero/imports/emscripten"

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.

Code:play  

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.

Code:play  

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

Examples

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

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

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.

Source Files

emscripten.go

Version
v1.9.0 (latest)
Published
Feb 18, 2025
Platform
linux/amd64
Imports
6 packages
Last checked
4 days ago –

Tools for package owners.