...
▽

Package emscripten

import "github.com/tetratelabs/wazero/imports/emscripten"
Overview
Index
Examples

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.

Code:

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:

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.

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.

type FunctionExporter

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

Notes

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

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.