witgen is a library to generate .wit files for WebAssembly in Rust

Overview

witgen

Rust Rust Version Docs.rs

witgen is a library to help 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.

Getting started

  • Put this dependency in your Cargo.toml
witgen = "0.3"
  • Install cargo witgen CLI
$ cargo install cargo-witgen

Examples

  • Into your Rust code:
use witgen::witgen;

#[witgen]
struct TestStruct {
    inner: String,
}

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

#[witgen]
fn test(other: Vec<u8>, test_struct: TestStruct, other_enum: TestEnum) -> Result<(String, i64), String> {
    Ok((String::from("test"), 0i64))
}
  • Then you can launch (at the root of your package):
$ cargo witgen generate
  • It will generate a witgen.wit file at the root of your package:
record TestStruct {
    inner: string
}

variant TestEnum {
    Unit,
	Number(u64),
	String(string),
}

test : function(other: list <u8>, test_struct: TestStruct, other_enum: TestEnum) -> expected<tuple<string, s64>>

Development

It's a very minimal version, it doesn't already support all kinds of types but the main used 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 !

Comments
  • feat: separate out proc_macro from inner functions

    feat: separate out proc_macro from inner functions

    I am trying to incorporate this tool into another macro. At first I tried to generate code that used the macro, #[witegen]. However, this seems like an extra step when I can use the underlying parsing methods directly.

    This is also particularly useful because I can parse snippets of code that will never need to be compiled. For example, in NEAR's case a contract's impl is transformed to be external functions that initialize the state of the contract and then call the impl's corresponding method. However, the function that it generates has an empty signature and the generated function must deserialize the function arguments from a host function. This is all to say that I want to generate a new function with the args of the function a new struct being passed. (This is how the JS interface will end up passing arguments).

    So a long winded way of saying that this new generated function doesn't have a body and would fail to compile. So it is very handy to generate this function only to be parsed by witgen.

    I am not attached to the new renaming or any of the structure, but just require being able to access the inner methods for parsing and writing to the target wit file.

    opened by willemneal 6
  • feat: add support for named fields in variants

    feat: add support for named fields in variants

    Variants with fields are really just a special case of an unnamed field wrapping a record. So this PR adds a record with the name variant-type-name-field-name and transforms the field into an unnamed one.
    For example,

    enum Foo {
        NamedField { name: String }
    }
    
    

    becomes

    variant foo {
        named-field(foo-named-field)
    }
    
    record foo-named-field {
        name: string
    }
    
    opened by willemneal 5
  • feat: add HashMap support

    feat: add HashMap support

    Since wit does not have a map type, this PR add support for encoding HashMap's as a list of tuples of key/value pairs.

    See https://github.com/bytecodealliance/wit-bindgen/issues/108

    opened by willemneal 4
  • Feature request: Documentation support

    Feature request: Documentation support

    Thanks for the crate!

    I wanted to ask if there could be documentation support.

    Wit supports only comments and does not differentiate between documentation and code comments. But, when using wit-bindgen to transform to markdown, comments are part of the generated .md and correctly located.

    Proposal

    I propose to make use of this to pass over documentation comments in Rust as comments (using \\) to the generated .wit file. Code comments in the Rust file would be ignored.

    Use case

    At the end of the day, the objective is to generate the .wit file that people possibly outside of the Rust world can use, therefore it makes sense to me to generate the documentation also outside of the Rust world.

    I do not have experience in this type of macros, but I could do the research if needed.

    opened by saona-raimundo 4
  • feat!: Update `function` --> `func`

    feat!: Update `function` --> `func`

    Also fixes #31.

    Also looked into cargo-smart-release. This should work:

    cargo smart-release witgen --bump minor --no-changelog --update-crates-index
    

    Add --execute for it to actually do it.

    This PR ended up growing in scope. Updated:

    • wit-parser

    Added:

    • use (import statements) and resource (impls, however, they only support functions at this time); interface (trait, but this type is not well supported by wit yet).
    • impl's methods now support special attributes. e.g.
    impl Foo {
      #[special_attr]
      pub fn foo(){}
    }
    

    Becomes

    resource foo {
      ///@special_attr
      foo: func()
    }
    
    • resolver to pull in wit dependencies from use (still need to test multiple depths, currently okay with one)
    • clap-cargo-extra, a new crate a made for dealing with cargo CLI and metadata
    • k9 testing library which provides snapshotting

    I know you already approved, but if you could just leave a comment that should be enough ;-)

    opened by willemneal 3
  • Feat: depend on parser and update syntax

    Feat: depend on parser and update syntax

    This updates the generated wit to comply with the newest syntax.

    • f32/f64 --> float32/float64. (Not sure why this decision was made. Why make it longer?)
    • Multi-value returns are now tuples
    • Can no longer have recursive type definitions.
    opened by willemneal 2
  • Can not find the witgen subcommand

    Can not find the witgen subcommand

    run cargo install cargo-witgen In MacOS:

    ➜  my_wit git:(main) ✗ cargo witgen
    error: no such subcommand: `witgen`
    

    I rename ~/.cargo/bin/cargo_witgen to ~/.cargo/bin/cargo-witgen, and then ok.

    opened by developerworks 2
  • Feat: Make cargo-witgen into lib so that other CLI apps can reuse it

    Feat: Make cargo-witgen into lib so that other CLI apps can reuse it

    This creates a new Witgen struct that handles generating the wit string and its output. This way other applications (specifically witme) can use #[clap(flatten)] to inject it into their subcommand.

    opened by willemneal 2
  • fix(wit): remove extra spaces between keywords and generic

    fix(wit): remove extra spaces between keywords and generic

    From the format "spec" there are no spaces between keywords and generics. E.g. list<u8>.

    If this was a personal preference then perhaps it's worth adding another CLI option.

    opened by willemneal 2
  • [Feature] Add version of witgen to generated comment

    [Feature] Add version of witgen to generated comment

    Currently this comment is at the top of the final generated wit file. This line could also indicate which version of witgen was used to produce the file.

    // This is a generated file by witgen (https://github.com/bnjjj/witgen), please do not edit yourself, you can generate a new one thanks to cargo witgen generate command

    opened by willemneal 2
  • [bug/question] cargo add doesn't work

    [bug/question] cargo add doesn't work

    https://github.com/bnjjj/witgen/blob/411e1c0c534adb7973619d211b02b8492d4716fc/README.md?plain=1#L28

    cargo add --help
    

    returns

    error: no such subcommand: `add`
    
            Did you mean `d`?
    

    Version:

    cargo 1.58.0 (7f08ace4f 2021-11-24)
    

    Is this a subcommand you have to install?

    opened by willemneal 2
  • [BREAKING] Upgrade to wit-parser 0.1.0 and incorporate it into wit generation

    [BREAKING] Upgrade to wit-parser 0.1.0 and incorporate it into wit generation

    This issue outlines the current work in wit-bindgen: https://github.com/bytecodealliance/wit-bindgen/issues/201

    They also recently created a 0.1.0 tag for the project. I took this as an opportunity to publish aha-wit-parser, which has the same version just different name. It can be added like so:

    wit-parser = { version = "0.1.0", package = "aha-wit-parser" }
    
    opened by willemneal 0
  • Generating wit from dependencies

    Generating wit from dependencies

    First off, fantastic work! Worked out of the box and am excited to help with the project.

    One issue I ran into is trying to generate wit from a dependencies. Within the project worked wonders, but I'm guessing the the cli is only checking the source files of the current project.

    Without this, I'm wondering if there is a way to publish the wit with cargo?

    Again great work and look forward to getting this in the hands of devs working with NEAR smart contracts!

    opened by willemneal 5
Owner
Coenen Benjamin
Coenen Benjamin
A 3D bin packing library in Rust/WebAssembly.

packme-wasm Demo https://packme.vercel.app This repository hosts an implementation of Dube, E., & Kanavathy L. (2006). Optimizing Three-Dimensional Bi

Ade Yahya Prasetyo 17 Feb 25, 2024
Handy macro to generate C-FFI bindings to Rust for Haskell

hs-bindgen Handy macro to generate C-FFI bindings to Rust for Haskell. This library intended to work best in a project configured by cargo-cabal. N.B.

Yvan Sraka 32 Feb 16, 2023
WebAssembly implementation from scratch in Safe Rust with zero dependencies

wain wain is a WebAssembly INterpreter written in Rust from scratch with zero dependencies. An implementation of WebAssembly. Features: No unsafe code

Linda_pp 328 Jan 2, 2023
A notebook app integrated with todo lists utility. Developed with Rust, WebAssembly, Yew and Trunk.

Flow.er A notebook app integrated with todo-list utility. Project flow.er is a Rust WASM app running in browser. Taking advantage of Yew and Trunk, it

null 45 Dec 31, 2022
Build frontend browser apps with Rust + WebAssembly. Supports server side rendering.

Percy Build frontend browser apps with Rust + WebAssembly. Supports server side rendering. The Percy Book This README gives a light introduction to Pe

Chinedu Francis Nwafili 2.1k Jan 1, 2023
plugy empowers you to construct agnostic dynamic plugin systems using Rust and WebAssembly.

plugy plugy is a plugin system designed to enable the seamless integration of Rust-based plugins into your application. It provides a runtime environm

Geoffrey Mureithi 22 Aug 12, 2023
Let's pretend that life-before-main exists for Rust targeting WebAssembly

Let's pretend that life-before-main exists for Rust targeting WebAssembly. Installation Add a dependency on wasm-init. This crate intentionally provid

Ruan Pearce-Authers 7 Aug 29, 2023
Code for my workshop "Production-ready WebAssembly with Rust" presented at RustLab 2023 in Florence

Workshop: Production-ready WebAssembly with Rust A workshop on Rust for WebAssembly by Alberto Schiabel (@jkomyno). ?? This workshop was first present

Alberto Schiabel 14 Nov 23, 2023
zzhack-cli is a Command Tool to help you quickly generate a WASM WebApp with simple configuration and zero code

English | 中文文档 zzhack-cli is a Command Tool that can help you quickly generate a WASM WebApp with simple configuration and zero code. It's worth menti

null 17 Feb 9, 2023
A macro to generate constructor to instanicate structs from JsValue using duck-typing.

ducktor ducktor is a Rust crate that allows you to create types from wasm_bindgen::JsValue using duck typing. With ducktor, you can define a struct th

Muhammad Hamza 6 Jun 23, 2023
NPM package distributing biscuit in WebAssembly for web components

Biscuit playground This is an example application for Biscuit tokens, where you can manipulate tokens and their verification in your browser. build wi

null 0 Dec 30, 2021
`wasm-snip` replaces a WebAssembly function's body with an `unreachable`

wasm-snip wasm-snip replaces a Wasm function's body with an unreachable instruction. API Docs | Contributing | Chat Built with ?? ?? by The Rust and W

Rust and WebAssembly 177 Dec 28, 2022
WebAssembly (Wasm) interpreter.

Continuous Integration Test Coverage Documentation Crates.io wasmi- WebAssembly (Wasm) Interpreter wasmi was conceived as a component of parity-ethere

Parity Technologies 1k Jan 4, 2023
Dependency solver for Elm, made in WebAssembly

Dependency solver for Elm, made in WebAssembly This repo holds a dependency solver for the elm ecosystem compiled to a WebAssembly module. The wasm mo

Matthieu Pizenberg 3 Jun 16, 2022
A simple code for checking crate 'prost' on WebAssembly (🦀 + 🕸️ = 💖)

rust-wasm-prost This repository is a simple code for checking crate 'prost' on WebAssembly ( ?? + ??️ = ?? ). What is prost? prost is a Protocol Buffe

Chris Ohk 6 Apr 5, 2022
Version of Clue made to be compilable in WebAssembly (WIP)

Clue is a programming language that compiles into Lua code with a syntax similar to languages like C or Rust. Clue tries to be almost as simple as Lua

Clue 2 Jun 16, 2022
Vite + Webassembly starter project

Vite + Typescript+ Webassembly A starter project for you to create a blazingly fast web application Before getting started You need to get these prere

Saugi 9 Aug 18, 2022
Mod_wasm - an extension module for the Apache HTTP Server (httpd) that enables the usage of WebAssembly (Wasm).

mod_wasm is an extension module for the Apache HTTP Server (httpd) that enables the usage of WebAssembly (Wasm). This module will allow to execute certain tasks in the backend in a very efficient and secure way.

VMware  Labs 67 Dec 21, 2022
Low level tooling for WebAssembly in JavaScript using wasm-tools

js-wasm-tools js-wasm-tools compiles some of the API of wasm-tools to JavaScript and WebAssembly via wasm-bindgen. This offers low level tooling for W

Dominic Elm 59 Dec 19, 2022