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)
}
Output:
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.
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Instantiate
deprecated
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 ¶ added in v1.1.0
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
deprecated
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 ¶ added in v1.1.0
func NewFunctionExporterForModule(guest wazero.CompiledModule) (FunctionExporter, error)
NewFunctionExporterForModule returns a guest-specific FunctionExporter, populated with any known functions used in emscripten.
Source Files