Go Tooling

The TinyGo toolchain has native support for WASI and can build Wasm core modules. With the help of some component model tooling, we can then take that core module and embed it in a component. To demonstrate how to use the tooling, this guide walks through building a component that implements the example world defined in the add.wit package. The component will implement a simple add function.

Overview of Building a Component with TinyGo

There are several steps to building a component in TinyGo:

Determine which world the component will implement
Build a Wasm core module using the native TinyGo toolchain
Convert the Wasm core module to a component using wasm-tools

The following sections will walk through these steps, producing a core Wasm module that targets WASI preview 1 and converting this core module to a component that supports WASI preview 2.

1: The `example` World

The next two sections walk through creating a component that implements the the following example world:

package example:component;

world example {
    export add: func(x: s32, y: s32) -> s32;
}

This is a simple world that exports one add function. If you want to go beyond a quick start to a more realistic example, jump to the section on implementing worlds with interfaces.

2: Creating a TinyGo Core Wasm Module

The TinyGo toolchain natively supports compiling Go programs to core Wasm modules. Let's create one that implements the add function in the example world.

First, implement a simple add function in add.go:

package main

//go:wasm-module yourmodulename
//export add
func add(x, y int32) int32 {
	return x + y
}

// main is required for the `wasi` target, even if it isn't used.
func main() {}

Note, we must still provide a main function. This is a limitation of TinyGo's support of WASI as it currently only supports main packages - commands that run start-to-finish and then exit. Our example program, however, is more like a library which exports an add function that can be called multiple times; and nothing will ever call its main function.

Now, we can use TinyGo to build our core Wasm module:

tinygo build -o add.wasm -target=wasi add.go

You should now have an add.wasm module. But at the moment, this is a core module. In the next section, we will convert it into a component.

3: Converting a Wasm Core Module to a Component

In the previous step, we produced a core module that implements our example world. We now want to convert to a component to gain the benefits of the component model, such as the ability to compose with it with other components as done in the calculator component in the tutorial. TinyGo is actively developing a wasip2 target (in this PR), but for now we must take additional steps to convert the module to a component.

We will use wasm-tools, a low level tool for manipulating Wasm modules. Download the latest release from the project's repository.

We also need to download the WASI preview 1 adapter. TinyGo (similar to C) targets preview 1 of WASI which does not support the component model (.wit files). Fortunately, Wasmtime provides adapters for adapting preview 1 modules to preview 2 components. There are adapters for both reactor and command components. Our add.wit world defines a reactor component, so download the wasi_snapshot_preview1.reactor.wasm adapter from the latest Wasmtime release.

Now that we have all the prerequisites downloaded, we can use the wasm-tools component subcommand to componentize our Wasm module, first embedding component metadata inside the core module and then encoding the module as a component using the WASI preview 1 adapter.

export COMPONENT_ADAPTER_REACTOR=/path/to/wasi_snapshot_preview1.reactor.wasm
wasm-tools component embed --world example ./add.wit add.wasm -o add.embed.wasm
wasm-tools component new -o add.component.wasm --adapt wasi_snapshot_preview1="$COMPONENT_ADAPTER_REACTOR" add.embed.wasm

We now have an add component that satisfies our example world, exporting the add function, which we can confirm using another wasm-tools command:

$ wasm-tools component wit add.component.wit
package root:component

world root {
  import wasi:io/streams
  import wasi:filesystem/types
  import wasi:filesystem/preopens
  import wasi:cli/stdin
  import wasi:cli/stdout
  import wasi:cli/stderr
  import wasi:cli/terminal-input
  import wasi:cli/terminal-output
  import wasi:cli/terminal-stdin
  import wasi:cli/terminal-stdout
  import wasi:cli/terminal-stderr

  export add: func(x: s32, y: s32) -> s32
}

Testing an `add` Component

To run our add component, we need to use a host program with a WASI runtime that understands the example world. We've provided an example-host to do just that. It calls the add function of a passed in component providing two operands. To use it, clone this repository and run the Rust program:

git clone git@github.com:bytecodealliance/component-docs.git
cd component-docs/component-model/examples/example-host
cargo run --release -- 1 2 /path/to/add.component.wasm

Implementing Worlds with Interfaces with TinyGo and Wit-Bindgen

The example world we were using in the previous sections simply exports a function. However, to use your component from another component, it must export an interface. This means we will need to use a tool to generate bindings to use as glue code, and adds a couple more steps (2-3) to building Wasm components with TinyGo:

Determine which world the component will implement
Generate bindings for that world using wit-bindgen
Implement the interface defined in the bindings
Build a Wasm core module using the native TinyGo toolchain
Convert the Wasm core module to a component using wasm-tools

For this example, we will use the following world, which moves the add function behind an add interface:

package docs:adder@0.1.0;

interface add {
    add: func(a: u32, b: u32) -> u32;
}

world adder {
    export add;
}

Our new steps use a low-level tool, wit-bindgen to generate bindings, or wrapper code, for implementing the desired world.

First, install a release of wit-bindgen, updating the environment variables for your desired version, architecture and OS:

export VERSION=0.24.0 ARCH=aarch64 OS=macos
wget https://github.com/bytecodealliance/wit-bindgen/releases/download/v$VERSION/wit-bindgen-$VERSION-$ARCH-$OS.tar.gz
tar -xzf wit-bindgen-$VERSION-$ARCH-$OS.tar.gz
mv wit-bindgen-$VERSION-$ARCH-$OS/wit-bindgen ./
rm -rf wit-bindgen-$VERSION-$ARCH-$OS.tar.gz wit-bindgen-$VERSION-$ARCH-$OS

Now, create your Go project:

mkdir add && cd add
go mod init example.com

Next, run wit-bindgen, specifying TinyGo as the target language, the path to the add.wit package, the name of the world in that package to generate bindings for (example), and a directory to output the generated code (gen):

wit-bindgen tiny-go ./add.wit --world example --out-dir=gen

The gen directory now contains several files:

$ tree gen
gen
├── adder.c
├── adder.go
└── adder.h

The adder.go file defines an ExportsDocsAdder0_1_0_Add interface that matches the structure of our add interface. The name of the interface is taken from the WIT package name (docs:adder@0.1.0) combined with the interface name (add). In our Go module, first implement the ExportsDocsAdder0_1_0_Add interface by defining the Add function.

package main

import (
	. "example.com/gen"
)

type AdderImpl struct {
}

// Implement the `ExportsDocsAdder0_1_0_Add` interface to ensure the component satisfies the
// `adder` world
func (i AdderImpl) Add(x, y uint32) uint32 {
	return x + y
}

// main is required for the `wasi` target, even if it isn't used.
func main() {}

After implementing the adder world, we need to load it by passing it to the SetExportsDocsAdder0_1_0_Add function from our bindings (adder.go). Since our component is a library, main will not be called. However, only Go programs with main can target WASI currently. As a loophole, we will initialize our AdderImpl type inside an init function. Go's init functions are used to do initialization tasks that should be done before any other tasks. In this case, we are using it to export the Add function and make it callable using the generated C bindings (adder.c). After populating the init function, our complete implementation looks similar to the following:

package main

import (
	. "example.com/gen"
)

type AdderImpl struct {
}

// Implement the ExportsDocsAdder0_1_0_Add interface to ensure the component satisfies the
// `adder` world
func (i AdderImpl) Add(x, y uint32) uint32 {
	return x + y
}

// To enable our component to be a library, implement the component in the
// `init` function which is always called first when a Go package is run.
func init() {
	example := AdderImpl{}
	SetExportsDocsAdder0_1_0_Add(example)
}

// main is required for the `WASI` target, even if it isn't used.
func main() {}

Once again, we can build our core module using TinyGo, componentize it, and adapt it for WASI 0.2:

export COMPONENT_ADAPTER_REACTOR=/path/to/wasi_snapshot_preview1.reactor.wasm
tinygo build -o add.wasm -target=wasi add.go
wasm-tools component embed --world example ./add.wit add.wasm -o add.embed.wasm
wasm-tools component new -o add.component.wasm --adapt wasi_snapshot_preview1="$COMPONENT_ADAPTER_REACTOR" add.embed.wasm

We now have an add component that satisfies our adder world, exporting the add function, which we can confirm using the wasm-tools component wit command:

wasm-tools component wit add.component.wasm 
package root:component;

world root {
  import wasi:io/error@0.2.0;
  import wasi:io/streams@0.2.0;
  import wasi:cli/stdin@0.2.0;
  import wasi:cli/stdout@0.2.0;
  import wasi:cli/stderr@0.2.0;
  import wasi:clocks/wall-clock@0.2.0;
  import wasi:filesystem/types@0.2.0;
  import wasi:filesystem/preopens@0.2.0;

  export docs:adder/add@0.1.0;
}

The WebAssembly Component Model