witgen

witgen is a library and a CLI that helps you generate wit definitions in a wit file for WebAssembly. Using this lib in addition to wit-bindgen will help you to import/export types and functions from/to wasm module. This project currently supports the wit parser at version 0.2.0 see here.

Getting started

Goal: Generate a .wit file writing only Rust.

You will need both the library and the CLI.

Preliminaries

Create a new library project and move to it.

$ cargo new my_wit
$ cd my_wit

Add witgen as a dependency in your Cargo.toml. Note: must have cargo-edit installed to add dependencies from CLI, e.g. cargo install cargo-edit.

$ cargo add witgen

Install cargo witgen CLI.

$ cargo install cargo-witgen

Writing code

Replace the content of your lib.rs by:

use witgen::witgen;

#[witgen]
use other_crate::*;

/// Doc strings are supported!
#[witgen]
struct TestStruct {
    /// Even for fields!
    inner: String,
}

#[witgen]
enum TestEnum {
    Unit,
    Number(u64),
    StringVariant(String),
}

#[witgen]
fn test(other: Vec<u8>, test_struct: TestStruct, other_enum: TestEnum) -> Result<(String, i64), String> {
    // The following code is not part of the generated `.wit` file.
    // You may add an example implementation or just satisfy the compiler with a `todo!()`.
    Ok((String::from("test"), 0i64))
}

#[witgen]
impl AResource {
  /// Can convert custom attributes to doc strings
  #[custom_attribute]
  pub fn foo(&self) {}
  /// Have special mutable attribute
  pub fn faa(&mut self) {}

  pub fn fee() {}
}

Then you can launch the CLI (at the root of your package):

cargo witgen generate

It will generate a index.wit file at the root of your package:

use * from other-crate

/// Doc strings are supported!
record test-struct {
  /// Even for fields!
  inner: string
}

variant test-enum {
  unit,
  number(u64),
  string-variant(string),
}

test : func(other: list <u8>, test-struct: test-struct, other-enum: test-enum) -> expected<tuple<string, s64>>

resource a-resource {
  /// Can convert custom attributes to doc strings
  /// @custom_attribute
  foo: func()
  /// Have special mutable attribute
  /// @mutable
  faa: func()
  static fee: func()
}

You can find more complete examples here

Limitations

For now using #[witgen] have some limitations:

You can use the proc macro #[witgen] only on struct, enum, type alias, function, impl, and use
Generic parameters or lifetime annotations are not supported, except for HashMap, which is interpreted as list<tuple<key, value>>.
Type &str is not supported (but you can use String)
References, Box, Rc, Arc and all types of smart pointers are not supported
There is no semantic analysis, which means if your function, struct or enum uses a non scalar type, you have to add #[witgen] where this type is declared (it won't fail at the compile time)

Development