WITX-CodeGen: 一个 WITX 代码和文档生成器

WITX 是一种描述 WebAssembly 模块类型和函数接口的方式。

据此，代码生成器可以生成代码以访问数据，调用或实现使用相同布局和调用约定从不同语言使用的函数。

WITX-CodeGen 在调用函数时不会进行转换。相反，它暴露了所有语言中具有相同布局的类型，如零拷贝序列化格式。因此，数据可以在客户端和主机之间轻松共享，而无需任何开销。

生成的代码与 WebAssembly 标准API（WASI）兼容。

此工具使用 2021 年 6 月 9 日之前的格式定义的下一个修订版，该修订版最终将用于接口类型。

witx-codegen 目前用 Rust 编写，但它完全与语言无关。它还与所有 WebAssembly 运行时兼容。生成的代码针对简洁和可读性进行了优化。

此工具还可以生成不同的文档格式。

witx-codegen 取代了 as-witx、zig-witx、witx-docgen、witx-overview-docgen 和 witx-generate-raw。

安装

• 通过 cargo

cargo install witx-codegen

• 预编译的二进制文件：tarballs 和 Debian/Ubuntu 软件包可在 此处 获取。

用法

WITX code generator for WebAssembly guest modules

USAGE:
    witx-codegen [FLAGS] [OPTIONS] <witx_files>...

FLAGS:
    -h, --help            Prints help information
    -H, --skip-header     Do not generate a header
    -I, --skip-imports    Ignores imported types and functions
    -V, --version         Prints version information

OPTIONS:
    -m, --module-name <module_name>
            Set the module name to use instead of reading it from the witx file

    -o, --output <output_file>         Output file, or - for the standard output
    -t, --output-type <output_type>
            Output type. One in: {assemblyscript, zig, rust, overview, markdown}
            [default: assemblyscript]

ARGS:
    <witx_files>...    WITX files

后端

• Markdown 文档（示例）
• API 概述（示例）
• AssemblyScript（示例）
• Zig（示例）
• Rust（示例）
• TinyGo
• C/C++
• Swift
• HTML 文档

欢迎为支持其他语言做出贡献！

示例输入

请参阅 test 文件夹以获取 WITX 输入文件的示例。

将来也可能支持其他输入格式，以及生成更多结构化文档的扩展。

WITX 格式

请参阅 test 目录以获取一些示例。

基本类型

bool、char、u8、u16、u32、u64、s8、s16、s32、s64

其他类型

• string：只读字符串。
• (in-buffer u8)：元素类型为 u8 的只读缓冲区。
• (out-buffer u8)：元素类型为 u8 的缓冲区。
• (@witx const_pointer u8)：只读的 u8 指针。
• (@witx pointer u8)：u8 指针。
• (@witx usize)：对象大小。

类型别名

• (typename$status_code u16)
• (typename$size (@witxusize))

请注意，函数返回的值必须是别名，而不是原始类型。

句柄

句柄是主机管理的对象的不可见引用。

为了使用句柄，必须声明一个 "资源"。

(resource $http_handle)

"资源" 代表一组句柄。同一资源可以被同一模块的所有句柄类型共享。

然后可以声明每种句柄类型为别名

(typename $query (handle $http_handle))
(typename $response_handle (handle $http_handle))

常量

(typename $big_int u64)
(@witx const $big_int $zero 0)
(@witx const $big_int $a_hundred 100)
(@witx const $big_int $a_big_value 0xff00000000000000)
(@witx const $big_int $a_bigger_value 0xffffffffffffffff)

结构体

(typename $example_structure
  (record
    (field $first_member bool)
    (field $second_member u8)
    (field $third_member string)
  )
)

只包含布尔值的结构体被编码为位集。

元组

(typename $test_tuple (tuple $test_bool $test_medium_int $big_int))

有标签的联合体

(typename $test_tagged_union
  (variant (@witx tag u16)
    (case $first_choice u8)
    (case $second_choice string)
    (case $third_choice f32)
    (case $empty_choice)
  )
)

这定义了一个具有表示活动成员的标签的联合体。上面的例子生成一个与以下结构体等效的结构体

struct {
    tag: u16,
    member: union {
        first_choice: u8,
        second_choice: string,
        third_choice: f32,
        empty_choice: (),
    }
}

导入

从 common.witx 导入一些别名，或所有别名。

(use $some_type, $some_other_type from $common)
(use * from $common)

模块

文件中只能有一个模块，其名称必须与模块名称匹配。模块定义如下

(module $module_name
...
)

它包含一切：类型、句柄、函数和导入。

函数

(@interface func (export "symmetric_key_generate")
 (param $algorithm string)
 (param $options $opt_options)
 (result $error (expected $symmetric_key (error $crypto_errno)))
)

这声明了一个具有两个输入参数（类型为 string 的 algorithm 和 options 以及类型为 opt_options）的 symmetric_key_generate 函数。

函数返回一个类型为 $crypto_errno 的错误代码。如果没有发生错误，函数返回一个类型为 $symmetric_key 的值。

在 Rust 中，等效的函数将是

fn symmetric_key_generate(algorithm: &str, options: OptOptions)
  -> Result<SymmetricKey, CryptoErrno>;

返回多个值

(@interface func (export "symmetric_key_id")
  (param $key $symmetric_key)
  (param $key_id (@witx pointer u8))
  (param $key_id_max_len $size)
  (result $error (expected (tuple $size $version) (error $crypto_errno)))
)

函数返回错误或两个类型为 $size 和 $version 的值。

上述示例与Rust中的类似声明等效

fn symmetric_key_id(key: SymmetricKey, key_id: *mut u8, key_id_max_len: usize)
  -> Result<(Size, Version), CryptoErrno>;