wasm-tools-go

README

wasm-tools-go

WebAssembly + WASI tools for Go

About

This repository contains code to generate Go bindings for Component Model interfaces defined in WIT (WebAssembly Interface Type) files. The goal of this project is to accelerate adoption of the Component Model and development of WASI 0.2+ in Go.

Component Model

Package cm contains helper types and functions used by generated packages, such as option<t>, result<ok, err>, variant, list, and resource. These are intended for use by generated Component Model bindings, where the caller converts to a Go equivalent. It attempts to map WIT semantics to their equivalent in Go where possible.

Note on Memory Safety

Package cm and generated bindings from wit-bindgen-go may have compatibility issues with the Go garbage collector, as they directly represent variant and result types as tagged unions where a pointer shape may be occupied by a non-pointer value. The GC may detect and throw an error if it detects a non-pointer value in an area it expects to see a pointer. This is an area of active development.

wit-bindgen-go

WIT → Go

The wit-bindgen-go tool can generate Go bindings for WIT interfaces and worlds. If wasm-tools is installed and in $PATH, then wit-bindgen-go can load WIT directly.

wit-bindgen-go generate ../wasi-cli/wit

Otherwise, pass the JSON representation of a fully-resolved WIT package:

wit-bindgen-go generate wasi-cli.wit.json

Or pipe via stdin:

wasm-tools component wit -j --all-features ../wasi-cli/wit | wit-bindgen-go generate

JSON → WIT

For debugging purposes, wit-bindgen-go can also convert a JSON representation back into WIT. This is useful for validating that the intermediate representation faithfully represents the original WIT source.

wit-bindgen-go wit example.wit.json

WIT → JSON

The wit package can decode a JSON representation of a fully-resolved WIT file. Serializing WIT into JSON requires wasm-tools v1.210.0 or higher. To convert a WIT file into JSON, run wasm-tools with the -j argument:

wasm-tools component wit -j --all-features example.wit

This will emit JSON on stdout, which can be piped to a file or another program.

wasm-tools component wit -j --all-features example.wit > example.wit.json

License

This project is licensed under the Apache 2.0 license with the LLVM exception. See LICENSE for more details.