Categorygithub.com/tetratelabs/wazero
modulepackage
1.9.0
Repository: https://github.com/tetratelabs/wazero.git
Documentation: pkg.go.dev

# README

wazero: the zero dependency WebAssembly runtime for Go developers

Go Reference License

WebAssembly is a way to safely run code compiled in other languages. Runtimes execute WebAssembly Modules (Wasm), which are most often binaries with a .wasm extension.

wazero is a WebAssembly Core Specification 1.0 and 2.0 compliant runtime written in Go. It has zero dependencies, and doesn't rely on CGO. This means you can run applications in other languages and still keep cross compilation.

Import wazero and extend your Go application with code written in any language!

Example

The best way to learn wazero is by trying one of our examples. The most basic example extends a Go application with an addition function defined in WebAssembly.

Runtime

There are two runtime configurations supported in wazero: Compiler is default:

By default, ex wazero.NewRuntime(ctx), the Compiler is used if supported. You can also force the interpreter like so:

r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())

Interpreter

Interpreter is a naive interpreter-based implementation of Wasm virtual machine. Its implementation doesn't have any platform (GOARCH, GOOS) specific code, therefore interpreter can be used for any compilation target available for Go (such as riscv64).

Compiler

Compiler compiles WebAssembly modules into machine code ahead of time (AOT), during Runtime.CompileModule. This means your WebAssembly functions execute natively at runtime. Compiler is faster than Interpreter, often by order of magnitude (10x) or more. This is done without host-specific dependencies.

Conformance

Both runtimes pass WebAssembly Core 1.0 and 2.0 specification tests on supported platforms:

RuntimeUsageamd64arm64others
Interpreterwazero.NewRuntimeConfigInterpreter()
Compilerwazero.NewRuntimeConfigCompiler()

Support Policy

The below support policy focuses on compatibility concerns of those embedding wazero into their Go applications.

wazero

wazero's 1.0 release happened in March 2023, and is in use by many projects and production sites.

We offer an API stability promise with semantic versioning. In other words, we promise to not break any exported function signature without incrementing the major version. This does not mean no innovation: New features and behaviors happen with a minor version increment, e.g. 1.0.11 to 1.2.0. We also fix bugs or change internal details with a patch version, e.g. 1.0.0 to 1.0.1.

You can get the latest version of wazero like this.

go get github.com/tetratelabs/wazero@latest

Please give us a star if you end up using wazero!

Go

wazero has no dependencies except Go, so the only source of conflict in your project's use of wazero is the Go version.

wazero follows the same version policy as Go's Release Policy: two versions. wazero will ensure these versions work and bugs are valid if there's an issue with a current Go version.

Additionally, wazero intentionally delays usage of language or standard library features one additional version. For example, when Go 1.29 is released, wazero can use language features or standard libraries added in 1.27. This is a convenience for embedders who have a slower version policy than Go. However, only supported Go versions may be used to raise support issues.

Platform

wazero has two runtime modes: Interpreter and Compiler. The only supported operating systems are ones we test, but that doesn't necessarily mean other operating system versions won't work.

We currently test Linux (Ubuntu and scratch), MacOS and Windows as packaged by GitHub Actions, as well as nested VMs running on Linux for FreeBSD, NetBSD, OpenBSD, DragonFly BSD, illumos and Solaris.

We also test cross compilation for many GOOS and GOARCH combinations.

  • Interpreter
    • Linux is tested on amd64 (native) as well arm64 and riscv64 via emulation.
    • Windows, FreeBSD, NetBSD, OpenBSD, DragonFly BSD, illumos and Solaris are tested only on amd64.
    • macOS is tested only on arm64.
  • Compiler
    • Linux is tested on amd64 (native) as well arm64 via emulation.
    • Windows, FreeBSD, NetBSD, DragonFly BSD, illumos and Solaris are tested only on amd64.
    • macOS is tested only on arm64.

wazero has no dependencies and doesn't require CGO. This means it can also be embedded in an application that doesn't use an operating system. This is a main differentiator between wazero and alternatives.

We verify zero dependencies by running tests in Docker's scratch image. This approach ensures compatibility with any parent image.


wazero is a registered trademark of Tetrate.io, Inc. in the United States and/or other countries

# Packages

Package api includes constants and interfaces used by both end-users and internal implementations.
Package experimental includes features we aren't yet sure about.
Package sys includes constants and types used by both public and internal APIs.

# Functions

NewCompilationCache returns a new CompilationCache to be passed to RuntimeConfig.
NewCompilationCacheWithDir is like wazero.NewCompilationCache except the result also writes state into the directory specified by `dirname` parameter.
NewFSConfig returns a FSConfig that can be used for configuring module instantiation.
NewModuleConfig returns a ModuleConfig that can be used for configuring module instantiation.
NewRuntime returns a runtime with a configuration assigned by NewRuntimeConfig.
NewRuntimeConfig returns a RuntimeConfig using the compiler if it is supported in this environment, or the interpreter otherwise.
NewRuntimeConfigCompiler compiles WebAssembly modules into runtime.GOARCH-specific assembly for optimal performance.
NewRuntimeConfigInterpreter interprets WebAssembly modules instead of compiling them into assembly.
NewRuntimeWithConfig returns a runtime with the given configuration.

# Interfaces

CompilationCache reduces time spent compiling (Runtime.CompileModule) the same wasm module.
CompiledModule is a WebAssembly module ready to be instantiated (Runtime.InstantiateModule) as an api.Module.
FSConfig configures filesystem paths the embedding host allows the wasm guest to access.
HostFunctionBuilder defines a host function (in Go), so that a WebAssembly binary (e.g.
HostModuleBuilder is a way to define host functions (in Go), so that a WebAssembly binary (e.g.
ModuleConfig configures resources needed by functions that have low-level interactions with the host operating system.
Runtime allows embedding of WebAssembly modules.
RuntimeConfig controls runtime behavior, with the default implementation as NewRuntimeConfig The example below explicitly limits to Wasm Core 1.0 features as opposed to relying on defaults: rConfig = wazero.NewRuntimeConfig().WithCoreFeatures(api.CoreFeaturesV1) # Notes - This is an interface for decoupling, not third-party implementations.