C/C++ Tooling

WebAssembly components can be built from C and C++ using clang, the C language family frontend for LLVM.

wit-bindgen is a tool to generate guest language bindings from a given .wit file.

Although wit-bindgen is a standalone tool (whereas some languages have more integrated toolchains like Rust's cargo-component), wit-bindgen can generate source-level bindings for Rust, C, Java (TeaVM), and TinyGo, with the ability for more language generators to be added in the future.

wit-bindgen can be used to build C applications that can be compiled directly to Wasm modules using clang with a wasm32-wasi target.

1. Download dependencies

First, install the CLI for wit-bindgen, wasm-tools, and the WASI SDK.

The WASI SDK will install a local version of clang configured with a wasi-sysroot. Follow these instructions to configure it for use. Note that you can also use your installed system or emscripten clang by building with --target=wasm32-wasi but you will need some artifacts from WASI SDK to enable and link that build target (more information is available in WASI SDK's docs).

2. Generate program skeleton from WIT

Start by generating a C skeleton from wit-bindgen using the sample adder/world.wit file:

> wit-bindgen c path/to/adder/world.wit
Generating "adder.c"
Generating "adder.h"
Generating "adder_component_type.o"

This has generated several files:

1.adder.h (based on the adder world) with the prototype of the add function (prefixed by exports_) - uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y);. 2. adder.c that interfaces with the component model ABI to call your function. 3. adder_component_type.o which contains object code referenced in adder.c from an extern that must be linked via clang.

3. Write program code

Next, create an component.c that implements the adder world (i.e. the interface defined in adder.h):

#include "adder.h"

uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y)
{
	return x + y;
}

4. Compile a WebAssembly P2 component with wasi-sdk's wasm32-wasip2-clang

Given that wasi-sdk has ben installed, we can build a Preview 2 component quickly by using the provided wasm32-wasip2-clang binary:

/opt/wasi-sdk/bin/wasm32-wasip2-clang \
    -o adder.wasm \
    -mexec-model=reactor \
    component.c \
    adder.c \
    adder_component_type.o

After this command completes, you will have a new file named adder.wasm available in the source folder.

For use cases that require building a P1 module and/or adapting an existing P1 module into a P2 module, such as buliding for a platform that does not support P2, details on a more manual approach can be found below:

clang component.c adder.c adder_component_type.o -o adder.wasm -mexec-model=reactor

wasm-tools component new ./adder.wasm -o adder.component.wasm

#include "adder.h"
#include <stdio.h>

uint32_t exports_docs_adder_add_add(uint32_t x, uint32_t y)
{
	uint32_t result = x + y;
	printf("%d", result);
	return result;
}

>wasm-tools component new ./adder.wasm -o adder.component.wasm
error: failed to encode a component from module

Caused by:
    0: failed to decode world from module
    1: module was not valid
    2: module requires an import interface named `wasi_snapshot_preview1`

wasm-tools component new adder.wasm --adapt wasi_snapshot_preview1.wasm -o adder.component.wasm

5. Inspect the built component

Finally, you can inspect the embedded wit to see your component (including any WASI imports if necessary):

>wasm-tools component wit adder.component.wasm
package root:component;

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

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

8. Running the component from the example host

This repository contains an example WebAssembly host written in Rust that can run components that implement the adder world.

A successful run should show the following output:

cargo run --release -- 1 2 adder.component.wasm
   Compiling example-host v0.1.0 (/path/to/component-docs/component-model/examples/example-host)
    Finished `release` profile [optimized] target(s) in 7.85s
     Running `target/debug/example-host 1 2 /tmp/docs/c/adder.component.wasm`
1 + 2 = 3

If not configured correctly, you may see errors like the following:

cargo run --release -- 1 2 adder.component.wasm
   Compiling example-host v0.1.0 (/path/to/component-docs/component-model/examples/example-host)
    Finished `release` profile [optimized] target(s) in 7.85s
     Running `target/release/example-host 1 2 adder.component.wasm`
Error: Failed to instantiate the example world

Caused by:
    0: component imports instance `wasi:io/error@0.2.2`, but a matching implementation was not found in the linker
    1: instance export `error` has the wrong type
    2: resource implementation is missing

This kind of error normally indicates that the host in question does not contain satisfy WASI imports.

9. Running a Component from C/C++ Applications

It is not yet possible to run a WebAssembly Component using the C API of wasmtime c-api. See wasmtime issue #6987 for more details. The c-api is preferred over directly using the example host Rust crate in C++.

However, C/C++ language guest components can be composed with components written in any other language and run by their toolchains, or even composed with a C language command component and run via the wasmtime CLI or any other host.

See the Rust Tooling guide for instructions on how to run this component from the Rust example-host (replacing the path to add.wasm with your add-component above).