• Stars
    star
    110
  • Rank 316,770 (Top 7 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created about 3 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A language binding generator for `wai` (a precursor to WebAssembly interface types)

WebAssembly Interfaces

A language bindings generator for wai

A Wasmer project building on wai

build status supported rustc stable

About

Note: Unfortunately, the maintainers behind wit-bindgen didn’t want to add support for Wasmer upstream, so we had to do a hard-fork in order to make things work with Wasmer.

This project is a bindings generator framework for WebAssembly programs and embeddings of WebAssembly. This works with *.wai files which describe the interface of a module, either imported or exported. For example this project can be used in cases such as:

  • Your language (say, Rust) is compiled to WebAssembly and you'd like to import WASI. This project will generate Rust bindings to import WASI APIs that are described with *.wai.

  • Your runtime (say, Wasmer) wants to then provide WASI functionality to guest programs. This project will generate a Rust trait for you to implement for the WASI interface.

  • You're consuming a WebAssembly module (say, in a browser) and you don't want to deal with funky ABI details. You'd use this project to generate JS bindings which give you a TypeScript interface dealing with native JS types for the WebAssembly module described by *.wai.

This project is based on the interface types proposal. This repository will be following upstream changes. The purpose of wai is to provide a forwards-compatible toolchain and story for interface types and a canonical ABI. Generated language bindings all use the canonical ABI for communication, enabling WebAssembly modules to be written in any language with support and for WebAssembly modules to be consumed in any environment with language support.

Demo

View generated bindings online!

If you're curious to poke around and see what generated bindings look like for a given input *.wai, you can explore the generated code online to get an idea of what's being generated and what the glue code looks like.

Usage

At this time a CLI tool is provided mostly for debugging and exploratory purposes. It can be used easily with the wasmer CLI.

// browser.wai

record person {
  name: string,
  age: u32,
}

// Say hello to either the specified person or the current user
hello: func(who: option<person>) -> string
$ wasmer run wasmer/wai-bindgen-cli --dir=. -- js --import browser.wai
Generating "browser.d.ts"
Generating "browser.js"
Generating "intrinsics.js"

This tool is not necessarily intended to be integrated into toolchains. For example usage in Rust would more likely be done through procedural macros and Cargo dependencies. Usage in a Web application would probably use a version of wai-bindgen compiled to WebAssembly and published to NPM.

For now, though, you can explore what bindings look like in each language through the CLI. Again if you'd like to depend on this if you wouldn't mind please reach out on Slack so we can figure out a better story than relying on the CLI tool for your use case.

Supported Languages

First here's a list of supported languages for generating a WebAssembly binary which uses interface types. This means that these languages support *.wai-defined imports and exports.

  • rust-wasm - this is for Rust compiled to WebAssembly, typically using either the wasm32-wasi or wasm32-unknown-unknown targets depending on your use case. In this mode you'd probably depend on the wai-bindgen-rust crate (located at crates/rust-wasm) and use the import! and export! macros to generate code.

  • c - this is for C compiled to WebAssembly, using either of the targets above for Rust as well. With C the wai-bindgen CLI tool will emit a *.h and a *.c file to be compiled into the wasm module.

This repository also supports a number of host languages/runtimes which can be used to consume WebAssembly modules that use interface types. These modules need to follow the canonical ABI for their exports/imports:

  • wasmer - this is for Rust users using the wasmer crate. This generator is used through the wai-bindgen-wasmer crate (located at crates/wasmer) and, like the compiled-to-wasm Rust support, has an import! and an export! macro for generating code.

  • js - this is for JavaScript users executing WebAssembly modules. This could be in a browser, Node.js, or Deno. In theory this covers browser use cases like web workers and such as well. In this mode the wai-bindgen CLI tool will emit a *.js and a *.d.ts file describing the interface and providing necessary runtime support in JS to implement the canonical ABI. Note that the intended long-term integration of this language is to compile wai-bindgen itself to WebAssembly and publish NPM packages for popular JS build systems to integrate wai-bindgen into JS build processes.

  • wasmer-py - this is for Python users using the wasmer PyPI package. This uses Wasmer under the hood but you get to write Python in providing imports to WebAssembly modules or consume modules using interface types. This generates a *.py file which is annotated with types for usage in mypy or other type-checkers.

All generators support the --import and --export flags in the wai-bindgen CLI tool:

$ wasmer run wasmer/wai-bindgen-cli --dir=. -- js --import browser.wai
$ wasmer run wasmer/wai-bindgen-cli --dir=. -- rust-wasm --export my-interface.wai
$ wasmer run wasmer/wai-bindgen-cli --dir=. -- wasmer --import host-functions.wai

Here "import" means "I want to import and call the functions in this interface" and "export" means "I want to define the functions in this interface for others to call".

Finally in a sort of "miscellaneous" category the wai-bindgen CLI also supports:

  • markdown - generates a *.md and a *.html file with readable documentation rendered from the comments in the source *.wai file.

Note that the list of supported languages here is a snapshot in time and is not final. The purpose of the interface-types proposal is to be language agnostic both in how WebAssembly modules are written as well as how they are consumed. If you have a runtime that isn't listed here or you're compiling to WebAssembly and your language isn't listed here, it doesn't mean that it will never be supported! A language binding generator is intended to be not the hardest thing in the world (but unfortunately also not the easiest) to write, and the crates and support in this repository mostly exist to make writing generators as easy as possible.

Some other languages and runtimes, for example, that don't have support in wai-bindgen today but are possible in the future (and may get written here too) are:

  • wasmer-go - same as for wasmer-py but for Go. Basically for Go users using the wasmer-go package who want to work with interface types rather than raw pointers/memories/etc.

  • wasmer-ruby - same as for wasmer-py but for Ruby. Basically for Go users using the wasmer-ruby package who want to work with interface types rather than raw pointers/memories/etc.

Note that this is not an exclusive list, only intended to give you an idea of what other bindings could look like. There's a plethora of runtimes and languages that compile to WebAssembly, and interface types should be able to work with all of them and it's theoretically just some work-hours away from having support in wai-bindgen.

More Repositories

1

wasmer

🚀 The leading Wasm Runtime supporting WASIX, WASI and Emscripten
Rust
16,915
star
2

wasmer-go

🐹🕸️ WebAssembly runtime for Go
Go
2,679
star
3

wasmer-python

🐍🕸 WebAssembly runtime for Python
Rust
1,999
star
4

wasmer-php

🐘🕸️ WebAssembly runtime for PHP
PHP
964
star
5

winterjs

Winter is coming... ❄️
JavaScript
844
star
6

wasmer-js

Monorepo for Javascript WebAssembly packages by Wasmer
Rust
828
star
7

kernel-wasm

Sandboxed kernel mode WebAssembly runtime.
C
702
star
8

wasmer-java

☕ WebAssembly runtime for Java
Java
544
star
9

awesome-wasi

😎 Curated list of awesome things regarding WebAssembly WASI ecosystem.
476
star
10

wasmer-ruby

💎🕸 WebAssembly runtime for Ruby
Rust
462
star
11

wasmer-postgres

💽🕸 Postgres library to run WebAssembly binaries.
Rust
392
star
12

wapm-cli

📦 WebAssembly Package Manager (CLI)
Rust
368
star
13

webassembly.sh

Open-source and installable PWA terminal powered by WebAssembly, WAPM, and Wasmer-JS 🖥
JavaScript
269
star
14

wasmer-rust-example

Example of WebAssembly embedding in Rust using Wasmer
Rust
163
star
15

ate

Distributed immutable data store with strong encryption and authentication
Rust
129
star
16

vscode-wasm

WebAssembly extension for VSCode
Rust
122
star
17

rusty_jsc

Rust bindings for the JavaScriptCore engine.
Rust
86
star
18

wasmer-c-api

Example of the C API to embed the Wasmer runtime
C
76
star
19

io-devices-lib

Library for interacting with the Wasmer Experimental IO Devices
WebAssembly
51
star
20

wasmer-pack

Rust
49
star
21

sonde-rs

A library to compile USDT probes into a Rust library
Rust
44
star
22

old-docs.wasmer.io

Wasmer Documentation (for standalone and embedded use cases)
WebAssembly
41
star
23

wasmer-install

Wasmer Binary Installer https://wasmer.io/
Shell
39
star
24

loupe

Profiling tool for Rust code.
Rust
35
star
25

c-wasm-simd128-example

Example C++ repo emitting Wasm SIMD 128 instructions
C++
30
star
26

wasmer-nginx-example

This is a simple example of Nginx running with wasmer
HTML
29
star
27

wasmer-ocaml

OCaml bindings for Wasmer
OCaml
28
star
28

cargo-wasmer

A cargo sub-command for publishing Rust crates to the WebAssembly Package Manager.
Rust
24
star
29

wasm-fuzz

Fuzzer for Wasm and Wasmer
JavaScript
22
star
30

wasmer.io

The Wasmer.io website
JavaScript
21
star
31

wasmer-bench

This is a repo for benchmarking Wasmer (compilation & runtime)
Rust
20
star
32

wcgi-wordpress-demo

PHP
15
star
33

wcgi-php-template

PHP
14
star
34

docs.wasmer.io

The Wasmer Docs Website (website deployed using Wasmer Edge)
MDX
14
star
35

setup-wasmer

GitHub action for setting up Wasmer
TypeScript
14
star
36

c-http-server

A very simple http server in c
JavaScript
13
star
37

rust-wasm-simd128-example

Example Rust repo emitting Wasm SIMD 128 instructions
Rust
10
star
38

wasm-debug

A runtime-independent crate for transforming Wasm-DWARF
Rust
9
star
39

wasmer-terminal-js

The WebAssembly terminal, revamped!
Rust
7
star
40

rust-cli-app-example

Example CLI app written in rust for Wasmer
Rust
7
star
41

wapm-publish

GitHub action for publishing to WAPM
TypeScript
7
star
42

wasmer-rust-customabi-example

An example repo to demonstrate how to create a module with a custom ABI to then use it from an embedder
Rust
6
star
43

wasm-interface-cli

A binary for verifying Wasm interfaces
Rust
6
star
44

interface-types

The `wasmer-interface-types` crate
Rust
5
star
45

ewasm-workshop

Ewasm workshow with Wasmer Metering
Rust
5
star
46

sgp4

Rust
5
star
47

llvm-custom-builds

Sandbox to produce custom LLVM builds for various platforms
Shell
5
star
48

sha2

A WebAssembly interface to Rust's sha2 crate
Rust
5
star
49

wasm-python-api

WebAssembly Python standard API prototype
Python
4
star
50

python-flask-example

Sample Python Flask server for Wasmer Edge
Python
4
star
51

shared-buffer

An abstraction over buffers backed by memory-mapped files or bytes in memory
Rust
3
star
52

wcgi-rust-template

Rust
3
star
53

wasmer-toml

Split out the wapm.toml parsing from wasmerio/wapm-cli
Rust
3
star
54

wasmer-nightly

Nightly releases of Wasmer
3
star
55

llvm-build

LLVM Distribution for being used with Wasmer
3
star
56

js-service-worker-example

Sample for a js service worker running on Wasmer Edge.
JavaScript
3
star
57

wasi-tests

Integration tests for WASI
Rust
2
star
58

.github

Github profile
2
star
59

wasmer-js-example

Wasmer-JS example
2
star
60

edge-react-starter

Wasmer Edge + Vite + React + TS starter template. Deploy it like it's hot 🚀
CSS
1
star
61

rustfft

Rustfft for WASM, published on WAPM
Rust
1
star
62

inline-c

Rust
1
star
63

speed.wasmer.io

Speed tracker of Wasmer
CSS
1
star
64

windows-llvm-build

Build of LLVM in Windows
1
star
65

wasmer-edge-support

1
star
66

zig2wapm

CI script to clone zig/zig to wapm.io
Shell
1
star
67

wasm4-on-wapm

This is a demo repo to showcase how to upload your WASM-4 games to WAPM
1
star
68

wai-hashids

Hashids demonstration with WAI
Rust
1
star
69

astro-starter-a1d

Astro
1
star
70

flask-starter-324

Python
1
star
71

wasmerio-flask-template

Python
1
star
72

wasmer-integration-tests

Integration tests between Edge and the backend
Rust
1
star