watgo – a WebAssembly Toolkit for Go

CLI use case

watgo comes with a CLI, which you can install by issuing this command:

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

The CLI aims to be compatible with wasm-tools , and I’ve already switched my wasm-wat-samples projects to use it; e.g. a command to parse a WAT file, validate it and encode it into binary format:

watgo parse stack.wat -o stack.wasm

API use case

wasmir semantically represents a WASM module with an API that’s easy to work with. Here’s an example of using watgo to parse a simple WAT program and do some analysis:

package main

import (
  "fmt"

  "github.com/eliben/watgo"
  "github.com/eliben/watgo/wasmir"
)

const wasmText = `
(module
  (func (export "add") (param i32 i32) (result i32)
    local.get 0
    local.get 1
    i32.add
  )
  (func (param f32 i32) (result i32)
    local.get 1
    i32.const 1
    i32.add
    drop
    i32.const 0
  )
)`

func main() {
  m, err := watgo.ParseWAT([]byte(wasmText))
  if err != nil {
    panic(err)
  }

  i32Params := 0
  localGets := 0
  i32Adds := 0

  // Module-defined functions carry a type index into m.Types. The function
  // body itself is a flat sequence of wasmir.Instruction values.
  for _, fn := range m.Funcs {
    sig := m.Types[fn.TypeIdx]
    for _, param := range sig.Params {
      if param.Kind == wasmir.ValueKindI32 {
        i32Params++
      }
    }

    for _, instr := range fn.Body {
      switch instr.Kind {
      case wasmir.InstrLocalGet:
        localGets++
      case wasmir.InstrI32Add:
        i32Adds++
      }
    }
  }

  fmt.Printf("module-defined funcs: %dn", len(m.Funcs))
  fmt.Printf("i32 params: %dn", i32Params)
  fmt.Printf("local.get instructions: %dn", localGets)
  fmt.Printf("i32.add instructions: %dn", i32Adds)
}

One important note: the WAT format supports several syntactic niceties that are flattened / canonicalized when lowered to wasmir. For example, all folded instructions are lowered to unfolded ones (linear form), function & type names are resolved to numeric indices, etc. This matches the validation and execution semantics of WASM and its binary representation.

These syntactic details are present in watgo in the textformat package (which parses WAT into an AST) and are removed when this is lowered to wasmir. The textformat package is kept internal at this time, but in the future I may consider exposing it publicly – if there’s interest.

Testing strategy

Even though it’s still early days for watgo, I’m reasonably confident in its correctness due to a strategy of very heavy testing right from the start.

WebAssembly comes with a large official test suite, which is perfect for end-to-end testing of new implementations. The core test suite includes almost 200K lines of WAT files that carry several modules with expected execution semantics and a variety of error scenarios exercised. These live in specially designed .wast files and leverage a custom spec interpreter.

watgo hijacks this approach by using the official test suite for its own testing. A custom harness parses .wast files and uses watgo to convert the WAT in them to binary WASM, which is then executed by Node.js ; this harness is a significant effort in itself, but it’s very much worth it – the result is excellent testing coverage. watgo passes the entire WASM spec core test suite.

Similarly, we leverage wabt’s interp test suite which also includes end-to-end tests, using a simpler Node-based harness to test them against watgo.

Finally, I maintain a collection of realistic program samples written in WAT in the wasm-wat-samples repository; these are also used by watgo to test itself.