Repository files navigation

This project is a suite of bindings generators for languages that are compiledto WebAssembly and use thecomponent model. Bindings are described with*.wit files which specify imports, exports, and facilitate reusebetween bindings definitions.

Thewit-bindgen repository is currently focused onguest programs whichare those compiled to WebAssembly. Executing a component in a host is notmanaged in this repository, and some options of how to do so aredescribedbelow. Languages developed in this repository are Rust, C, Java (TeaVMJava), Go (TinyGo), and C#. If you encounter any problems feel free toopen anissue or chat withus onZulip.

Thewit-bindgen project extensively usesWIT definitions to describe importsand exports. The items supported byWIT directly map to the component modelwhich allows core WebAssembly binaries produced by native compilers to betransformed into a component. All imports into a WebAssembly binary and allexports must be described withWIT. An example file looks like:

packageexample:host;worldhost {importprint:func(msg:string);exportrun:func();}

This describes a "world" which describes both imports and exports that theWebAssembly component will have available. In this case the host will provide aprint function and the component itself will provide arun function.

Functionality inWIT can also be organized intointerfaces:

packageexample:my-game;interfacemy-plugin-api {recordcoord {x:u32,y:u32,  }get-position:func()->coord;set-position:func(pos:coord);recordmonster {name:string,hp:u32,pos:coord,  }monsters:func()->list<monster>;}worldmy-game {importprint:func(msg:string);importmy-plugin-api;exportrun:func();}

Here themy-plugin-api interface encapsulates a group of functions, types,etc. This can then be imported wholesale into themy-game world via themy-plugin-api namespace. The structure of aWIT document and world will affect thegenerated bindings per-language.

For more information about WIT and its syntax see theonline documentation forWIT as well as itsupstreamreference.

The end-goal ofwit-bindgen is to facilitate creation of acomponent. Once a component is created it can then be handedoff to any one of a number ofhost runtimes for execution. Creating acomponent is not supported natively by any language today, however, sowit-bindgen is only one of the pieces in the process of creating a component.The general outline for the build process of a component for a compiled languageis:

1. Usingwit-bindgen source code for the language is generated representingbindings to the specified APIs. This source code is then compiled by thenative compiler and used by user-written code as well.
2. The native language toolchain is used to emit a core WebAssembly module. Thiscore wasm module is the "meat" of a component and contains all user-definedcode compiled to WebAssembly. The most common native target to use forcompilation today is thewasm32-wasi target.
3. The output core wasm module is transformed into a component using thewasm-tools project, notably thewasm-tools component new subcommand.This will ingest the native core wasm output and wrap the output into thecomponent model binary format.

The precise tooling and commands at each of these stepsdiffers language bylanguage, but this is the general idea. With a component in-hand thebinary can then be handed off toa host runtimes for execution.

An important consideration when creating a component today is WASI. All currentnative toolchains for languages which have WASI support are using thewasi_snapshot_preview1 version of WASI. This definition of WASI was madewith historical*.witx files and is not compatible with the component model.There is, however, a means by which to still create components from modulesthat are usingwasi_snapshot_preview1 APIs.

Thewasm-tools component new subcommand takes an--adapt argument which actsas a way to polyfill non-component-model APIs, likewasi_snapshot_preview1,with component model APIs. TheWasmtime runtime publishesadaptermodules with each release that are suitable to use with--adapt to implementwasi_snapshot_preview1 in terms of WASI 0.2. OnWasmtime's releases page you'll see three modules to choose from:

• wasi_snapshot_preview1.command.wasm - use this for CLI applications.
• wasi_snapshot_preview1.reactor.wasm - use this for applications that don'thave amain function for example: for example a process that responds to anevent.
• wasi_snapshot_preview1.proxy.wasm - use this for applications fed intowasmtime serve for example.

Only one adapter is necessary and be sure to look for thelatestversions as well.

Thewit-bindgen project is primarily focused onguest languages which arethose compiled to WebAssembly. Each language here already has native support forexecution in WebAssembly at the core wasm layer (e.g. targets the currentcorewasm specification). Brief instructionsare listed here for each language of how to use it as well.

Each project below will assume the following*.wit file in the root of yourproject.

// wit/host.witpackageexample:host;worldhost {importprint:func(msg:string);exportrun:func();}

The Rust compiler supports a nativewasm32-wasi target and can be added toanyrustup-based toolchain with:

rustup target add wasm32-wasi

In order to compile a wasi dynamic library, the following must be added to theCargo.toml file:

[lib]crate-type = ["cdylib"]

Projects can then depend onwit-bindgen by executing:

cargo add wit-bindgen

WIT files are currently added to awit/ folder adjacent to yourCargo.tomlfile. Example code using this then looks like:

// src/lib.rs// Use a procedural macro to generate bindings for the world we specified in// `host.wit`wit_bindgen::generate!({// the name of the world in the `*.wit` input file    world:"host",});// Define a custom type and implement the generated `Guest` trait for it which// represents implementing all the necessary exported interfaces for this// component.structMyHost;implGuestforMyHost{fnrun(){print("Hello, world!");}}// export! defines that the `MyHost` struct defined below is going to define// the exports of the `world`, namely the `run` function.export!(MyHost);

By usingcargo expand orcargo doc you can also explore the generated code. If there's a bug inwit-bindgenand the generated bindings do not compile or if there's an error in thegenerated code (which is probably also a bug inwit-bindgen), you can useWIT_BINDGEN_DEBUG=1 as an environment variable to help debug this.

This project can then be built with:

cargo build --target wasm32-wasiwasm-tools component new ./target/wasm32-wasi/debug/my-project.wasm \    -o my-component.wasm --adapt ./wasi_snapshot_preview1.reactor.wasm

This creates amy-component.wasm file which is suitable to execute in anycomponent runtime. Usingwasm-tools you can inspect the binary as well, forexample inferring the WIT world that is the component:

wasm-tools component wit my-component.wasm# world my-component {#  import print: func(msg: string)#  export run: func()# }

which in this case, as expected, is the same as the input world.

C and C++ code can be compiled for thewasm32-wasi target using theWASISDK project. The releases on that repository have precompiledclang binarieswhich are pre-configured to compile for WebAssembly.

To start in C and C++ a*.c and*.h header file is generated for yourproject to use. These files are generated with thewit-bindgen CLIcommand in this repository.

wit-bindgen c ./wit# Generating "host.c"# Generating "host.h"# Generating "host_component_type.o"

Some example code using this would then look like

// my-component.c#include"host.h"voidhost_run() {host_string_tmy_string;host_string_set(&my_string,"Hello, world!");host_print(&my_string);}

This can then be compiled withclang from theWASI SDK and assembled into acomponent with:

clang host.c host_component_type.o my-component.c -o my-core.wasm -mexec-model=reactorwasm-tools component new ./my-core.wasm -o my-component.wasm

Like with Rust, you can then inspect the output binary:

wasm-tools component wit ./my-component.wasm

Java bytecode can be compiled to WebAssembly usingTeaVM-WASI. With this generator,wit-bindgen will emit*.java files which may be used with any JVM language,e.g. Java, Kotlin, Clojure, Scala, etc.

You can compile Go code into a Wasm module using theTinyGo compiler. For example, the following command compilesmain.go to a WASI module:

tinygo build -target=wasi main.go

Note: the current TinyGobindgen requires TinyGo version v0.27.0 or later.

When usingwit-bindgen tiny-go bindgen,*.go and*.h C header file are generated for your project. These files are generated with thewit-bindgen CLI command in this repository.

wit-bindgen tiny-go ./wit# Generating "host.go"# Generating "host.c"# Generating "host.h"# Generating "host_component_type.o"

If your Go code usesresult oroption type, an additional Go filehost_types.go will be generated. This file contains the Go types that correspond to theresult andoption types in the WIT file.

An example of using the generated Go code would look like:

Initialize Go:

go mod init example.com

Create your Go main file:

// my-component.gopackage mainimport (api"example.com/api")funcinit() {a:=HostImpl{}api.SetHost(a)}typeHostImplstruct {}func (eHostImpl)Run() {api.HostPrint("Hello, world!")}//go:generate wit-bindgen tiny-go wit --out-dir=apifuncmain() {}

This setup allows you to invokego generate, which generates the bindings for the Go code into anapi directory. Afterward, you can compile your Go code into a WASI module using the TinyGo compiler. Lastly you can componentize the module usingwasm-tools:

go generate# generate bindings for Gotinygo build -target=wasi -o main.wasm my-component.go# compilewasm-tools component embed --world host ./wit main.wasm -o main.embed.wasm# create a componentwasm-tools component new main.embed.wasm --adapt wasi_snapshot_preview1.command.wasm -o main.component.wasmwasm-tools validate main.component.wasm --features component-model

Other languages such as JS, Ruby, Python, etc, are hoped to be supported one daywithwit-bindgen or with components in general. It's recommended to reach outonzulip if you're intersted in contributing a generator for one of theselangauges. It's worth noting, however, that turning an interpreted language intoa component is significantly different from how compiled languages currentlywork (e.g. Rust or C/C++). It's expected that the first interpreted languagewill require a lot of design work, but once that's implemented the others canideally relatively quickly follow suit and stay within the confines of thefirst design.

To install the CLI for this tool (which isn't the only way it can be used), runthe following cargo command. This will let you generate the bindings for anysupported language.

cargo install wit-bindgen-cli

This CLIIS NOT stable and may change, do not expect it to be or rely on itbeing stable. Please reach out to us onzulip if you'd like to depend on it,so we can figure out a better alternative for your use case.

Thewit-bindgen project is intended to facilitate in generating a component,but once a component is in your hands the next thing to do is to actuallyexecute that somewhere. This is not under the purview ofwit-bindgen itselfbut these are some resources and runtimes which can help you work withcomponents:

• Rust: thewasmtime crate is an implementation ofa native component runtime that can run any WITworld. It additionally comeswith abindgen!macrowhich acts similar to thegenerate! macro in this repository. This macrotakes aWIT package as input and generatestrait-based bindings for theruntime to implement and use.

• JS: thejco project can be used to execute components in JSeither on the web or outside the browser in a runtime such asnode. Thisproject generates a polyfill for a single concrete component to execute in aJS environment by extracting the core WebAssembly modules that make up acomponent and generating JS glue to interact between the host and thesemodules.

• Python: thewasmtimeprojecton PyPI has abindgen modethat works similar to the JS integration. Given a concrete component this willgenerate Python source code to interact with the component using an embeddingof Wasmtime for its core WebAssembly support.

• Tooling: thewasm-tools project can be used to inspect and modifylow-level details of components. For example as previously mentioned you caninspect the WIT-based interface of a component withwasm-tools component wit. You can link two components together withwasm-tools compose as well.

Note that the runtimes above are generally intended to work with arbitrarycomponents, not necessarily only those created bywit-bindgen. This is alsonot necessarily an exhaustive listing of what can execute a component.

To build the cli:

cargo build

Learn more how to run the tests in thetesting document.

This repository's crates and CLI are all currently versioned at0.X.Y whereY is frequently0 andX increases most of the time with publishes. Thismeans that changes are published as possibly-API-breaking changes as developmentcontinues here.

Also, this repository does not currently have a strict release cadence. Releasesare done on an as-needed basis. If you'd like a release done please feel free toreach out onZulip, file an issue, leave a comment on a PR, or otherwisecontact a maintainer.

For maintainers, the release process looks like:

• Go tothis link
• Click on "Run workflow" in the UI.
• Use the defaultbump argument and hit "Run workflow"
• Wait for a PR to be created by CI. You can watch the "Actions" tab for ifthings go wrong.
• When the PR opens, close it then reopen it. Don't ask questions.
• Review the PR, approve it, then queue it for merge.

That should be it, but be sure to keep an eye on CI in case anything goes wrong.

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

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in this project by you, as defined in the Apache-2.0 license,shall be licensed as above, without any additional terms or conditions.