#wasm-module #generate #cargo

witgen

witgen is a library to help you generate wit definitions in a wit file for WebAssembly

13 breaking releases

0.15.0 Jul 28, 2022
0.12.0 Apr 15, 2022
0.11.0 Mar 10, 2022
0.5.0 Dec 23, 2021

#416 in WebAssembly

Download history 250/week @ 2024-03-02 186/week @ 2024-03-09 264/week @ 2024-03-16 359/week @ 2024-03-23 367/week @ 2024-03-30 317/week @ 2024-04-06 365/week @ 2024-04-13 285/week @ 2024-04-20 300/week @ 2024-04-27 245/week @ 2024-05-04 259/week @ 2024-05-11 160/week @ 2024-05-18 310/week @ 2024-05-25 311/week @ 2024-06-01 205/week @ 2024-06-08 266/week @ 2024-06-15

1,124 downloads per month
Used in 6 crates (2 directly)

Custom license

38KB
727 lines

witgen

Rust Rust Version Docs.rs

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

It's a very minimal version, it doesn't already support all kinds of types but the main ones are supported. I made it to easily generate .wit files for my need. Feel free to create issues or pull-requests if you need something. I will be happy to help you!

Dependencies

~5MB
~138K SLoC