From 872beb7ac11f3dccfb1d94a74bda65a044180a3b Mon Sep 17 00:00:00 2001 From: Kyle Brown Date: Wed, 16 Mar 2022 21:26:00 -0400 Subject: [PATCH] Initial sketch of per-language support summaries --- docs/OVERVIEW.md | 27 +++++++++++++++++++++++++ docs/langs/CPP.md | 3 +++ docs/langs/GO.md | 3 +++ docs/langs/JS.md | 8 ++++++++ docs/langs/PYTHON.md | 6 ++++++ docs/langs/RUST.md | 48 ++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 95 insertions(+) create mode 100644 docs/OVERVIEW.md create mode 100644 docs/langs/CPP.md create mode 100644 docs/langs/GO.md create mode 100644 docs/langs/JS.md create mode 100644 docs/langs/PYTHON.md create mode 100644 docs/langs/RUST.md diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md new file mode 100644 index 000000000..4cfe63324 --- /dev/null +++ b/docs/OVERVIEW.md @@ -0,0 +1,27 @@ +# Overview +WIT Bindgen + +## Host Bindings Support +Host bindings in a language allows code in that language to talk to WASM modules using bindings generated from a WIT interface. This requires that that language has the ability to either embed a WASM runtime like `wasmtime` or interact with one built in to the language runtime (like V8). + +## Guest Bindings Support +Guest bindings in a language allow WASM modules written in that language to implement interfaces defined by WIT interfaces. This requires that the language can be compiled to WASM. + +# WIT Support Table + + + +| Language | Host Bindings | Guest Bindings | +| - | - | - | +| Rust | ✔️ ([details](./langs/RUST.md#host-bindings))| ✔️ ([details](./langs/RUST.md#guest-bindings))| +| JS | ✔️ ([details](./langs/JS.md)) | ❌ | +| Python | ✔️ ([details](./langs/PYTHON.md)) | ❌ | +| Go | ⏳ ([details](./langs/GO.md)) | ❌ | +| C++ | ⏳ ([details](./langs/CPP.md)) | ❌ | + +## Key +| Symbol | Description | +| - | - | +| ✔️ | Support for WIT | +| ⏳ | Partial/WIP support for WIT | +| ❌ | No support for WIT | diff --git a/docs/langs/CPP.md b/docs/langs/CPP.md new file mode 100644 index 000000000..7afacbe54 --- /dev/null +++ b/docs/langs/CPP.md @@ -0,0 +1,3 @@ +## Cpp Host Bindings ⏳ + +again the same as for wasmtime-py, but for users of the wasmtime-cpp header file to use interface types from C++. \ No newline at end of file diff --git a/docs/langs/GO.md b/docs/langs/GO.md new file mode 100644 index 000000000..203540c00 --- /dev/null +++ b/docs/langs/GO.md @@ -0,0 +1,3 @@ +## Go Host Bindings ⏳ + +same as for wasmtime-py but for Go. Basically for Go users using the wasmtime-go package who want to work with interface types rather than raw pointers/memories/etc. \ No newline at end of file diff --git a/docs/langs/JS.md b/docs/langs/JS.md new file mode 100644 index 000000000..1a07d5a5b --- /dev/null +++ b/docs/langs/JS.md @@ -0,0 +1,8 @@ +# JavaScript + +## Host Bindings ✔️ +JavaScript code run in the browser, Node.js, or Deno may be able to execute WebAssembly modules since those runtimes provide WebAssembly support. In theory this covers browser use cases like web workers and such as well. + +The wit-bindgen CLI tool can emit a `*.js` and `*.d.ts` file describing the interface and providing necessary runtime support in JS to implement the canonical ABI. + +**Note:** The intended long-term integration of this language is to compile wit-bindgen itself to WebAssembly and publish NPM packages for popular JS build systems to integrate wit-bindgen into JS build processes. \ No newline at end of file diff --git a/docs/langs/PYTHON.md b/docs/langs/PYTHON.md new file mode 100644 index 000000000..7aecf7c53 --- /dev/null +++ b/docs/langs/PYTHON.md @@ -0,0 +1,6 @@ +# Python + +## Host Bindings ✔️ +The [`wasmtime`](https://github.com/bytecodealliance/wasmtime-py) PyPI package provides an API for embedding the `wasmtime` runtime within a Python program. It allows you to write Python code to provide as module imports or use to consume modules. + +You can use `wit-bindgen` to generate a `*.py` file which is annotated with types for usage in mypy or other type-checkers. diff --git a/docs/langs/RUST.md b/docs/langs/RUST.md new file mode 100644 index 000000000..ca5ea8800 --- /dev/null +++ b/docs/langs/RUST.md @@ -0,0 +1,48 @@ +# Rust + +## Host Bindings +The [`wasmtime`](https://github.com/bytecodealliance/wasmtime/tree/main/crates/wasmtime) crate provides an API for embedding the `wasmtime` runtime within a Rust program. + +Users of the `wasmtime` crate can use the [`wit-bindgen-wasmtime`](https://github.com/bytecodealliance/wit-bindgen/tree/main/crates/wasmtime) crate to generate Rust code for instantiating and invoking modules that implement WIT interfaces. + +### Example +```rs +// Bindgen +wit_bindgen_wasmtime::import!("../foobar.wit"); + +pub use foobar::{Foobar, FoobarData}; + +// Setup WASMTIME +let engine = Engine::default(); +let mut linker = Linker::new(&engine); +let mut store = Store::new(&engine, FoobarData {}); + +// Load and initialize our module +let module_bytes = ... +let module = Module::new(&engine, module_bytes).unwrap(); +let (interface, instance) = Foobar::instantiate( + &mut store, &module, &mut linker, get_whole_store + ).unwrap(); + +// Call interface +interface.do_foo(&mut store, "bar").unwrap(); +``` + +## Guest Bindings +Rust can be compiled to WASM using its compiler `rustc` with either the `wasm32-wasi` or `wasm32-unknown-unknown` target. + +The [`wit-bindgen-rust`](https://github.com/bytecodealliance/wit-bindgen/tree/main/crates/rust-wasm) crate provides `import!` and `export!` macros that can be used by a module implementation to bind to imports and exports defined by WIT interfaces. + +### Example + +```rs +wit_bindgen_rust::export!("../foobar.wit"); + +struct Foobar {} + +impl foobar::Foobar for Foobar { + fn do_foo(bar: String) -> parser1::Output { + ... + } +} +``` \ No newline at end of file