{"id":13625920,"url":"https://github.com/jedisct1/witx-codegen","last_synced_at":"2025-05-16T03:06:43.697Z","repository":{"id":40771816,"uuid":"257726152","full_name":"jedisct1/witx-codegen","owner":"jedisct1","description":"WITX code and documentation generator for AssemblyScript, Zig, Rust and more. ","archived":false,"fork":false,"pushed_at":"2025-03-05T12:31:14.000Z","size":425,"stargazers_count":140,"open_issues_count":1,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-28T10:05:15.363Z","etag":null,"topics":["assemblyscript","code-generator","interface-types","wasm","webassembly","wit","witx","zig"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jedisct1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-21T22:02:36.000Z","updated_at":"2025-04-06T01:52:23.000Z","dependencies_parsed_at":"2023-02-04T06:46:33.044Z","dependency_job_id":"d6a53085-c4f1-4603-9581-7a13f4d51151","html_url":"https://github.com/jedisct1/witx-codegen","commit_stats":{"total_commits":197,"total_committers":7,"mean_commits":"28.142857142857142","dds":"0.045685279187817285","last_synced_commit":"b7f42105ba274637a1a55fcac4f86315084eb7b5"},"previous_names":["jedisct1/as-witx"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fwitx-codegen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fwitx-codegen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fwitx-codegen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jedisct1%2Fwitx-codegen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jedisct1","download_url":"https://codeload.github.com/jedisct1/witx-codegen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459088,"owners_count":22074605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assemblyscript","code-generator","interface-types","wasm","webassembly","wit","witx","zig"],"created_at":"2024-08-01T21:02:05.589Z","updated_at":"2025-05-16T03:06:38.688Z","avatar_url":"https://github.com/jedisct1.png","language":"Rust","readme":"![WITX code generator](logo.png)\n================================\n\n![CI status](https://github.com/jedisct1/witx-codegen/actions/workflows/ci.yml/badge.svg)\n[![crates.io](https://img.shields.io/crates/v/witx-codegen.svg)](https://crates.io/crates/witx-codegen)\n\n# WITX-CodeGen: A WITX code and documentation generator\n\nWITX is a way to describe types and function interfaces for WebAssembly modules.\n\nFrom this, code generators can produce code to access data, call or implement functions from different languages using the same layout and calling conventions.\n\nWITX-CodeGen doesn't do transformations when functions are called. Instead, it exposes types that have the same layout in all languages, like a zero-copy serialization format. Data can thus be easily shared between guests and hosts without any overhead.\n\nThe generated code is compatible with the WebAssembly standard APIs ([WASI](https://wasi.dev)).\n\nThis tool uses the next (as on June 9th, 2021) revision of the format definition, that will eventually be required for interface types.\n\n`witx-codegen` is currently written in Rust, but it is totally language-agnostic. It is also compatible with all WebAssembly runtimes. The generated code is optimized for simplicity and readability.\n\nThe tool can also produce different documentation formats.\n\n`witx-codegen` supersedes `as-witx`, `zig-witx`, `witx-docgen`, `witx-overview-docgen` and `witx-generate-raw`.\n\n## Installation\n\n* Via `cargo`:\n\n```sh\ncargo install witx-codegen\n```\n\n* Precompiled binaries: tarballs and Debian/Ubuntu packages are available [here](https://github.com/jedisct1/witx-codegen/releases/latest).\n\n## Usage\n\n```text\nWITX code generator for WebAssembly guest modules\n\nUSAGE:\n    witx-codegen [FLAGS] [OPTIONS] \u003cwitx_files\u003e...\n\nFLAGS:\n    -h, --help            Prints help information\n    -H, --skip-header     Do not generate a header\n    -I, --skip-imports    Ignores imported types and functions\n    -V, --version         Prints version information\n\nOPTIONS:\n    -m, --module-name \u003cmodule_name\u003e\n            Set the module name to use instead of reading it from the witx file\n\n    -o, --output \u003coutput_file\u003e         Output file, or - for the standard output\n    -t, --output-type \u003coutput_type\u003e\n            Output type. One in: {assemblyscript, zig, rust, overview, markdown}\n            [default: assemblyscript]\n\nARGS:\n    \u003cwitx_files\u003e...    WITX files\n```\n\n## Backends\n\n* [X] Markdown documentation ([example](https://github.com/jedisct1/witx-codegen/blob/master/example-output/markdown.md))\n* [X] API Overview ([example](https://github.com/jedisct1/witx-codegen/blob/master/example-output/overview.txt))\n* [X] AssemblyScript ([example](https://github.com/jedisct1/witx-codegen/blob/master/example-output/assemblyscript.ts))\n* [X] Zig ([example](https://github.com/jedisct1/witx-codegen/blob/master/example-output/zig.zig))\n* [X] Rust ([example](https://github.com/jedisct1/witx-codegen/blob/master/example-output/rust.rs))\n* [X] C++ ([example](https://github.com/jedisct1/witx-codegen/blob/master/example-output/cpp.h)) - Experimental\n* [ ] TinyGo\n* [ ] Swift\n* [ ] HTML documentation\n\nSupport for additional languages is more than welcome!\n\n## Example inputs\n\nSee the [`tests`](https://github.com/jedisct1/witx-codegen/tree/master/tests) folder for examples of WITX input files.\n\nOther input formats may also be eventually supported, as well as extensions to produce more structured documentation.\n\n## WITX format\n\n### Basic types\n\n`bool`, `char`, `u8`, `u16`, `u32`, `u64`, `s8`, `s16`, `s32`, `s64`\n\n### Other types\n\n* `string`: a read-only string.\n* `(in-buffer u8)`: a read-only buffer whose elements are of type `u8`.\n* `(out-buffer u8)`: a buffer whose elements are of type `u8`.\n* `(@witx const_pointer u8)`: a read-only `u8` pointer.\n* `(@witx pointer u8)`: a `u8` pointer.\n* `(@witx usize)`: an object size.\n\n### Type aliases\n\n* `(typename $status_code u16)`\n* `(typename $size (@witx usize))`\n\nNote that returned values from function must all be aliases, not raw types.\n\n### Handles\n\nHandles are opaque references to objects managed by the host.\n\nIn order to use handles, a \"resource\" has to be declared:\n\n```\n(resource $http_handle)\n```\n\nA \"resource\" represent a group of handles. The same resource can be shared by all handle types from the same module.\n\nEach handle type can then be declared as aliases:\n\n```\n(typename $query (handle $http_handle))\n(typename $response_handle (handle $http_handle))\n```\n\n### Constants\n\n```\n(typename $big_int u64)\n(@witx const $big_int $zero 0)\n(@witx const $big_int $a_hundred 100)\n(@witx const $big_int $a_big_value 0xff00000000000000)\n(@witx const $big_int $a_bigger_value 0xffffffffffffffff)\n```\n\n### Structures\n\n```\n(typename $example_structure\n  (record\n    (field $first_member bool)\n    (field $second_member u8)\n    (field $third_member string)\n  )\n)\n```\n\nStructures that only contain booleans are encoded as bit sets.\n\n### Tuples\n\n```\n(typename $test_tuple (tuple $test_bool $test_medium_int $big_int))\n```\n\n### Tagged unions\n\n```\n(typename $test_tagged_union\n  (variant (@witx tag u16)\n    (case $first_choice u8)\n    (case $second_choice string)\n    (case $third_choice f32)\n    (case $empty_choice)\n  )\n)\n```\n\nThis defines a union with a tag representing the active member. The example above generates a structure equivalent to:\n\n```zig\nstruct {\n    tag: u16,\n    member: union {\n        first_choice: u8,\n        second_choice: string,\n        third_choice: f32,\n        empty_choice: (),\n    }\n}\n```\n\n### Imports\n\nImport some aliases, or all of them, from `common.witx`:\n\n```\n(use $some_type, $some_other_type from $common)\n(use * from $common)\n```\n\n### Modules\n\nOnly one module can be present in a file, whose name must match the module name. A module is defined as follows:\n\n```\n(module $module_name\n...\n)\n```\n\nIt contains everything: types, handles, functions and imports.\n\n### Functions\n\n```\n(@interface func (export \"symmetric_key_generate\")\n (param $algorithm string)\n (param $options $opt_options)\n (result $error (expected $symmetric_key (error $crypto_errno)))\n)\n```\n\nThis declares a `symmetric_key_generate` function, with two input parameters (`algorithm` and `options` of type `string` and `opt_options`).\n\nThe function returns an error code of type `$crypto_errno`. Or, if no error occurred, the function returns a value of type `$symmetric_key`.\n\nIn Rust, an equivalent function would be:\n\n```rust\nfn symmetric_key_generate(algorithm: \u0026str, options: OptOptions)\n  -\u003e Result\u003cSymmetricKey, CryptoErrno\u003e;\n```\n\nReturning multiple values:\n\n```\n(@interface func (export \"symmetric_key_id\")\n  (param $key $symmetric_key)\n  (param $key_id (@witx pointer u8))\n  (param $key_id_max_len $size)\n  (result $error (expected (tuple $size $version) (error $crypto_errno)))\n)\n```\n\nThe function returns either an error, or two values, of type `$size` and `$version`.\n\nThe above example is eauivalent to a declaration like that one in Rust:\n\n```rust\nfn symmetric_key_id(key: SymmetricKey, key_id: *mut u8, key_id_max_len: usize)\n  -\u003e Result\u003c(Size, Version), CryptoErrno\u003e;\n```\n","funding_links":[],"categories":["Rust","Tool development"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedisct1%2Fwitx-codegen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjedisct1%2Fwitx-codegen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjedisct1%2Fwitx-codegen/lists"}