watgo

README

watgo

---

WebAssembly Toolkit for Go (watgo) to parse WASM text or decode WASM binary into internal data structures, allowing conversions, etc.

WASM feature support and proposals

Initially, we aim to support all the finished proposals without any flags or feature selection. Finished proposals are part of the WASM spec.

If there's a request to support active proposals, we'll consider employing explicit feature flags to gate this support.

Installation

To install the CLI into your Go bin directory:

go install github.com/eliben/watgo/cmd/watgo@latest

To run it directly from a checkout without installing:

go run ./cmd/watgo

To run it straight from the module path without installing:

go run github.com/eliben/watgo/cmd/watgo@latest

Go API

The public Go API is documented on pkg.go.dev, including runnable examples for the high-level functions in package watgo.

CLI

watgo currently provides basic parse and validate subcommands.

For supported subcommands and flags, the CLI aims to stay compatible with wasm-tools.

Examples:

# Compile WAT text to a WASM binary file.
watgo parse input.wat -o output.wasm

# Validate a WAT file.
watgo validate input.wat

# Validate a WASM binary.
watgo validate input.wasm

# Read WAT from stdin and write WASM to stdout.
cat input.wat | watgo parse > output.wasm

For full command-line help, run:

watgo help

Documentation

Overview

Package watgo provides the public high-level Go API for parsing, validating, decoding, and encoding WebAssembly modules.

The package is centered on semantic IR represented by wasmir.Module. Text-format WAT and binary WASM both normalize into that IR:

• ParseWAT parses and lowers WAT into semantic IR.
• DecodeWASM decodes binary WASM into semantic IR.
• ValidateModule validates semantic IR.
• EncodeWASM encodes semantic IR back to binary WASM.
• CompileWATToWASM is the end-to-end convenience helper for WAT-to-WASM.

A typical pipeline is:

m, err := watgo.ParseWAT(src)
if err != nil {
	// handle parse/lower diagnostics
}
if err := watgo.ValidateModule(m); err != nil {
	// handle validation diagnostics
}
wasm, err := watgo.EncodeWASM(m)
if err != nil {
	// handle encoding diagnostics
}

See the package examples for complete runnable usage snippets.

Index

• func CompileWATToWASM(src []byte) ([]byte, error)
• func DecodeWASM(src []byte) (*wasmir.Module, error)
• func EncodeWASM(m *wasmir.Module) ([]byte, error)
• func ParseWAT(src []byte) (*wasmir.Module, error)
• func ValidateModule(m *wasmir.Module) error

Examples

• CompileWATToWASM
• DecodeWASM
• EncodeWASM
• ParseWAT
• ValidateModule

Functions

func CompileWATToWASM

func CompileWATToWASM(src []byte) ([]byte, error)

CompileWATToWASM parses, lowers, validates, and encodes text-format WebAssembly to binary WebAssembly.

This is the public end-to-end convenience API when the caller wants binary output directly from WAT input.

Example

package main

import (
	"fmt"

	"github.com/eliben/watgo"
)

func main() {
	wasm, err := watgo.CompileWATToWASM([]byte(`(module
  (func (export "answer") (result i32)
    i32.const 42
  )
)`))
	if err != nil {
		panic(err)
	}
	fmt.Println(len(wasm) > 0)
}

Output:
true

func DecodeWASM

func DecodeWASM(src []byte) (*wasmir.Module, error)

DecodeWASM decodes binary WebAssembly into semantic IR.

DecodeWASM performs binary decoding into wasmir.Module, but does not run semantic validation. Call ValidateModule on the returned module before using it when you need a validated module.

On failure, DecodeWASM returns a non-nil error. Decode errors are typically returned as diag.ErrorList values.

Example

package main

import (
	"fmt"

	"github.com/eliben/watgo"
)

func canonicalAddModuleBytes() []byte {
	return []byte{
		0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
		0x01, 0x07, 0x01, 0x60, 0x02, 0x7f, 0x7f, 0x01, 0x7f,
		0x03, 0x02, 0x01, 0x00,
		0x07, 0x07, 0x01, 0x03, 0x61, 0x64, 0x64, 0x00, 0x00,
		0x0a, 0x09, 0x01, 0x07, 0x00, 0x20, 0x00, 0x20, 0x01, 0x6a, 0x0b,
	}
}

func main() {
	m, err := watgo.DecodeWASM(canonicalAddModuleBytes())
	if err != nil {
		panic(err)
	}
	fmt.Println(len(m.Types), len(m.Funcs))
}

Output:
1 1

func EncodeWASM

func EncodeWASM(m *wasmir.Module) ([]byte, error)

EncodeWASM encodes semantic IR as binary WebAssembly.

EncodeWASM does not implicitly validate m. Call ValidateModule first when you need validation before encoding.

On failure, EncodeWASM returns a non-nil error. Encoder failures are typically returned as diag.ErrorList values.

Example

package main

import (
	"fmt"

	"github.com/eliben/watgo"
)

func main() {
	m, err := watgo.ParseWAT([]byte(`(module
  (func (export "answer") (result i32)
    i32.const 42
  )
)`))
	if err != nil {
		panic(err)
	}
	if err := watgo.ValidateModule(m); err != nil {
		panic(err)
	}
	wasm, err := watgo.EncodeWASM(m)
	if err != nil {
		panic(err)
	}
	fmt.Println(len(wasm) > 0)
}

Output:
true

func ParseWAT

func ParseWAT(src []byte) (*wasmir.Module, error)

ParseWAT parses and lowers text-format WebAssembly into semantic IR.

ParseWAT performs text parsing plus lowering into wasmir.Module, but does not run semantic validation. Call ValidateModule on the returned module before encoding or executing it when you need a validated module.

On failure, ParseWAT returns a non-nil error. Most parser and lowering failures are returned as diag.ErrorList values.

Example

package main

import (
	"fmt"

	"github.com/eliben/watgo"
)

func main() {
	m, err := watgo.ParseWAT([]byte(`(module
  (func (export "answer") (result i32)
    i32.const 42
  )
)`))
	if err != nil {
		panic(err)
	}
	fmt.Println(len(m.Funcs), len(m.Exports))
}

Output:
1 1

func ValidateModule

func ValidateModule(m *wasmir.Module) error

ValidateModule validates a semantic WebAssembly module.

This is the public validation entry point over wasmir.Module. It reports semantic issues such as type mismatches, invalid indices, and malformed instruction sequences. Validation errors are typically returned as diag.ErrorList values.

Example

package main

import (
	"fmt"

	"github.com/eliben/watgo"
)

func main() {
	m, err := watgo.ParseWAT([]byte(`(module
  (func (export "answer") (result i32)
    i32.const 42
  )
)`))
	if err != nil {
		panic(err)
	}
	fmt.Println(watgo.ValidateModule(m) == nil)
}

Output:
true