@thi.ng/wasm-api 0.10.0 → 0.12.0

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { BigType, FloatType, Fn, Fn2 } from "@thi.ng/api";
+import type { BigType, FloatType, Fn, IDeref, ILength, IObjectOf } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
 export declare const PKG_NAME = "@thi.ng/wasm-api";
 export declare const EVENT_MEMORY_CHANGED = "memory-changed";
@@ -132,9 +132,9 @@ export interface CoreAPI extends WebAssembly.ModuleImports {
     printI32: Fn<number, void>;
     printU32: Fn<number, void>;
     printU32Hex: Fn<number, void>;
-    _printI64: Fn2<number, number, void>;
-    _printU64: Fn2<number, number, void>;
-    _printU64Hex: Fn2<number, number, void>;
+    printI64: Fn<bigint, void>;
+    printU64: Fn<bigint, void>;
+    printU64Hex: Fn<bigint, void>;
     printF32: Fn<number, void>;
     printF64: Fn<number, void>;
     _printI8Array: (addr: number, len: number) => void;
@@ -150,6 +150,9 @@ export interface CoreAPI extends WebAssembly.ModuleImports {
     _printStr0: (addr: number) => void;
     _printStr: (addr: number, len: number) => void;
     debug: () => void;
+    _panic: (addr: number, len: number) => void;
+    timer: () => number;
+    epoch: () => bigint;
 }
 export interface WasmTypeBase {
     /**
@@ -172,6 +175,9 @@ export declare type WasmUint = "u8" | "u16" | "u32" | "u64";
 export declare type WasmFloat = FloatType;
 export declare type WasmPrim = WasmInt | WasmUint | WasmFloat;
 export declare type WasmPrim32 = Exclude<WasmPrim, BigType>;
+export declare type ReadonlyWasmString = IDeref<string> & ILength & {
+    readonly addr: number;
+};
 export declare type TypeColl = Record<string, TopLevelType>;
 export interface TypeInfo {
     /**
@@ -206,6 +212,14 @@ export interface TopLevelType extends TypeInfo {
      * Type / kind
      */
     type: "struct" | "enum";
+    /**
+     * Optional object of user provided source codes to be injected into the
+     * generated type. Keys are language IDs (same name as respective codegen).
+     *
+     * @remarks
+     * Currently only supported by the {@link ZIG} codegen, ignored otherwise.
+     */
+    body?: IObjectOf<string>;
 }
 export interface Struct extends TopLevelType {
     type: "struct";
@@ -217,11 +231,18 @@ export interface Struct extends TopLevelType {
     /**
      * If true, struct fields will be re-ordered in descending order based on
      * their {@link TypeInfo.__align} size. This might result in overall smaller
-     * structs due to minimizing inter-field padding.
+     * structs due to minimizing implicit inter-field padding caused by
+     * alignment requirements. **If this option is enabled, then the struct MUST
+     * NOT contain any padding fields!**
      *
      * @defaultValue false
      */
     auto?: boolean;
+    /**
+     * Optional qualifier for the kind of struct to be emitted (codegen specific
+     * interpretation, currently only used by {@link ZIG}).
+     */
+    tag?: "extern" | "packed";
 }
 export interface StructField extends TypeInfo {
     /**
@@ -261,7 +282,13 @@ export interface StructField extends TypeInfo {
      */
     type: WasmPrim | "string" | "opaque" | string;
     /**
-     * TODO currently unsupported & ignored!
+     * Const qualifier (default is true for `string`, false for all other
+     * types). Only used for pointers or slices.
+     */
+    const?: boolean;
+    /**
+     * Currently only supported for {@link ZIG} arrays & slices, otherwise
+     * ignored!
      */
     sentinel?: number;
     /**
@@ -269,14 +296,23 @@ export interface StructField extends TypeInfo {
      */
     len?: number;
     /**
-     * TODO currently unsupported & ignored!
+     * Currently only supported for {@link ZIG} scalar & string values,
+     * otherwise ignored!
      */
-    default?: any;
+    default?: number;
+    /**
+     * If defined and > 0, the field will be considered for padding purposes only and
+     * the value provided is the number of bytes used.
+     */
+    pad?: number;
 }
 export interface Enum extends TopLevelType {
     type: "enum";
     /**
-     * No i64/u64 support, due to Typescript not supporting bigint enum values
+     * No i64/u64 support, due to Typescript not supporting bigint enum values.
+     * For C compatibility only i32 or u32 is allowed.
+     *
+     * @defaultValue "i32"
      */
     tag: Exclude<WasmPrim32, FloatType>;
     /**
@@ -299,27 +335,75 @@ export interface EnumValue {
      */
     doc?: string;
 }
+export interface CodeGenOptsBase {
+    /**
+     * Optional string to be injected before generated type defs (but after
+     * codegen's own prelude, if any)
+     */
+    pre: string;
+    /**
+     * Optional string to be injected after generated type defs (but before
+     * codegen's own epilogue, if any)
+     */
+    post: string;
+}
+/**
+ * Global/shared code generator options.
+ */
+export interface CodeGenOpts extends CodeGenOptsBase {
+    /**
+     * Identifier how strings are stored on WASM side, e.g. in Zig string
+     * literals are slices (8 bytes), in C just plain pointers (4 bytes).
+     *
+     * @defaultValue "slice"
+     */
+    stringType: "slice" | "ptr";
+    /**
+     * If true (default), forces uppercase enum identifiers
+     *
+     * @defaultValue true
+     */
+    uppercaseEnums: boolean;
+    /**
+     * Unless set to false, the generated output will be prefixed with a header
+     * line comment of generator meta data
+     */
+    header: boolean;
+    /**
+     * If true, codegens MAY generate various additional struct & struct field
+     * analysis functions (sizes, alignment, offsets etc.).
+     *
+     * @defaultValue false
+     */
+    debug: boolean;
+    /**
+     * Target line width for word wrapping doc strings
+     *
+     * @defaultValue 80
+     */
+    lineWidth: number;
+}
 export interface ICodeGen {
     /**
      * Optional prelude source, to be prepended before any generated type defs.
      */
-    pre?: string;
+    pre?: Fn<CodeGenOpts, string>;
     /**
      * Optional source code to be appended after any generated type defs.
      */
-    post?: string;
+    post?: Fn<CodeGenOpts, string>;
     /**
      * Docstring codegen
      */
-    doc: (doc: string, indent: string, acc: string[], topLevel?: boolean) => void;
+    doc: (doc: string, acc: string[], opts: CodeGenOpts, topLevel?: boolean) => void;
     /**
      * Codegen for enum types.
      */
-    enum: (type: Enum, types: TypeColl, acc: string[]) => void;
+    enum: (type: Enum, types: TypeColl, acc: string[], opts: CodeGenOpts) => void;
     /**
      * Codegen for struct types.
      */
-    struct: (type: Struct, types: TypeColl, acc: string[]) => void;
+    struct: (type: Struct, types: TypeColl, acc: string[], opts: CodeGenOpts) => void;
 }
 /**
  * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.

package/bin/wasm-api.mjs_

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { spawn } from "child_process";
+import { realpathSync } from "fs";
+import { join } from "path";
+const [node, toolsDir, ...args] = process.argv;
+
+const cli = join(realpathSync(toolsDir), "..", "..", "cli.js");
+
+const child = spawn(node, ["--loader", "ts-node/esm", cli, ...args]);
+
+child.stderr.on("data", (d) => {
+	const dStr = d.toString().trim();
+	!dStr.includes("ExperimentalWarning") ? console.log(dStr) : "";
+});
+child.on("exit", (err) => process.exit(err));
+child.stdout.pipe(process.stdout);

package/bridge.d.ts

@@ -1,7 +1,17 @@
 /// <reference types="node" />
 import type { Event, INotify, Listener, NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-import { BigIntArray, CoreAPI, IWasmAPI, WasmExports, IWasmMemoryAccess } from "./api.js";
+import { BigIntArray, CoreAPI, IWasmAPI, IWasmMemoryAccess, WasmExports } from "./api.js";
+export declare const Panic: {
+    new (msg?: string | undefined): {
+        name: string;
+        message: string;
+        stack?: string | undefined;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
 export declare const OutOfMemoryError: {
     new (msg?: string | undefined): {
         name: string;

package/bridge.js

@@ -2,10 +2,10 @@ import { __decorate } from "tslib";
 import { INotifyMixin } from "@thi.ng/api/mixins/inotify";
 import { defError } from "@thi.ng/errors/deferror";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
-import { U16, U32, U64HL, U8 } from "@thi.ng/hex";
+import { U16, U32, U64BIG, U8 } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
 import { EVENT_MEMORY_CHANGED, } from "./api.js";
-const B32 = BigInt(32);
+export const Panic = defError(() => "Panic");
 export const OutOfMemoryError = defError(() => "Out of memory");
 /**
  * The main interop API bridge between the JS host environment and a WebAssembly
@@ -34,18 +34,18 @@ let WasmBridge = class WasmBridge {
         this.api = {
             printI8: logN,
             printU8: logN,
-            printU8Hex: (x) => this.logger.debug(`0x${U8(x)}`),
             printI16: logN,
             printU16: logN,
-            printU16Hex: (x) => this.logger.debug(`0x${U16(x)}`),
             printI32: logN,
             printU32: (x) => this.logger.debug(x >>> 0),
-            printU32Hex: (x) => this.logger.debug(`0x${U32(x)}`),
-            _printI64: (hi, lo) => this.logger.debug((BigInt(hi) << B32) | BigInt(lo)),
-            _printU64: (hi, lo) => this.logger.debug((BigInt(hi >>> 0) << B32) | BigInt(lo >>> 0)),
-            _printU64Hex: (hi, lo) => this.logger.debug(`0x${U64HL(hi, lo)}`),
+            printI64: (x) => this.logger.debug(x),
+            printU64: (x) => this.logger.debug(x),
             printF32: logN,
             printF64: logN,
+            printU8Hex: (x) => this.logger.debug(`0x${U8(x)}`),
+            printU16Hex: (x) => this.logger.debug(`0x${U16(x)}`),
+            printU32Hex: (x) => this.logger.debug(`0x${U32(x)}`),
+            printU64Hex: (x) => this.logger.debug(`0x${U64BIG(x)}`),
             _printI8Array: logA(this.getI8Array.bind(this)),
             _printU8Array: logA(this.getU8Array.bind(this)),
             _printI16Array: logA(this.getI16Array.bind(this)),
@@ -61,6 +61,11 @@ let WasmBridge = class WasmBridge {
             debug: () => {
                 debugger;
             },
+            _panic: (addr, len) => {
+                throw new Panic(this.getString(addr, len));
+            },
+            timer: () => performance.now(),
+            epoch: () => BigInt(Date.now()),
         };
     }
     /**
@@ -210,7 +215,7 @@ let WasmBridge = class WasmBridge {
         const addr = this.exports._wasm_allocate(numBytes);
         if (!addr)
             throw new OutOfMemoryError(`unable to allocate: ${numBytes}`);
-        this.logger.debug(`allocated ${numBytes} bytes @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
+        this.logger.fine(`allocated ${numBytes} bytes @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
         this.ensureMemory();
         clear && this.u8.fill(0, addr, addr + numBytes);
         return addr;
@@ -229,7 +234,7 @@ let WasmBridge = class WasmBridge {
      * @param numBytes
      */
     free(addr, numBytes) {
-        this.logger.debug(`freeing memory @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
+        this.logger.fine(`freeing memory @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
         this.exports._wasm_free(addr, numBytes);
     }
     getI8(addr) {

package/cli.js

@@ -1,15 +1,22 @@
-import { flag, oneOfMulti, parse, ParseError, string, strings, usage, } from "@thi.ng/args";
+import { flag, oneOf, oneOfMulti, parse, ParseError, string, strings, usage, } from "@thi.ng/args";
 import { isArray, isPlainObject } from "@thi.ng/checks";
 import { illegalArgs } from "@thi.ng/errors";
-import { readJSON, writeText } from "@thi.ng/file-io";
+import { readJSON, readText, writeJSON, writeText } from "@thi.ng/file-io";
 import { ConsoleLogger } from "@thi.ng/logger";
-import { resolve } from "path";
+import { mutIn } from "@thi.ng/paths";
+import { dirname, resolve } from "path";
 import { generateTypes } from "./codegen.js";
+import { C11 } from "./codegen/c11.js";
 import { TYPESCRIPT } from "./codegen/typescript.js";
-import { isWasmPrim, isWasmString } from "./codegen/utils.js";
+import { isPadding, isWasmPrim, isWasmString } from "./codegen/utils.js";
 import { ZIG } from "./codegen/zig.js";
-const GENERATORS = { ts: TYPESCRIPT, zig: ZIG };
+const GENERATORS = { c11: C11, ts: TYPESCRIPT, zig: ZIG };
 const argOpts = {
+    analytics: string({
+        alias: "a",
+        hint: "FILE",
+        desc: "output file path for raw codegen analytics",
+    }),
     config: string({
         alias: "c",
         hint: "FILE",
@@ -27,6 +34,11 @@ const argOpts = {
         delim: ",",
     }),
     out: strings({ alias: "o", hint: "FILE", desc: "output file path" }),
+    string: oneOf(["slice", "ptr"], {
+        alias: "s",
+        hint: "TYPE",
+        desc: "Force string type implementation",
+    }),
 };
 export const INSTALL_DIR = resolve(`${process.argv[2]}/..`);
 export const PKG = readJSON(`${INSTALL_DIR}/package.json`);
@@ -63,6 +75,16 @@ const addTypeSpec = (ctx, path, coll, spec) => {
         invalidSpec(path, `${spec.name} type: ${spec.type}`);
     if (coll[spec.name])
         invalidSpec(path, `duplicate name: ${spec.name}`);
+    if (spec.body) {
+        if (!isPlainObject(spec.body))
+            invalidSpec(path, `${spec.name}.body must be an object`);
+        for (let lang in spec.body) {
+            const src = spec.body[lang];
+            if (src[0] === "@") {
+                spec.body[lang] = readText(src.substring(1), ctx.logger);
+            }
+        }
+    }
     ctx.logger.debug(`registering ${spec.type}: ${spec.name}`);
     coll[spec.name] = spec;
     spec.__path = path;
@@ -72,7 +94,10 @@ const validateTypeRefs = (coll) => {
         if (spec.type !== "struct")
             continue;
         for (let f of spec.fields) {
-            if (!(isWasmPrim(f.type) || isWasmString(f.type) || coll[f.type])) {
+            if (!(isPadding(f) ||
+                isWasmPrim(f.type) ||
+                isWasmString(f.type) ||
+                coll[f.type])) {
                 invalidSpec(spec.__path, `structfield ${spec.name}.${f.name} of unknown type: ${f.type}`);
             }
         }
@@ -127,13 +152,30 @@ try {
     }
     const ctx = {
         logger: new ConsoleLogger("wasm-api", opts.debug ? "DEBUG" : "INFO"),
-        config: {},
+        config: { global: {} },
         opts,
     };
     if (opts.config) {
-        ctx.config = readJSON(resolve(opts.config), ctx.logger);
+        opts.config = resolve(opts.config);
+        ctx.config = readJSON(opts.config, ctx.logger);
+        for (let id in ctx.config) {
+            const conf = ctx.config[id];
+            if (conf.pre && conf.pre[0] === "@") {
+                conf.pre = readText(resolve(dirname(opts.config), conf.pre.substring(1)), ctx.logger);
+            }
+            if (conf.post && conf.post[0] === "@") {
+                conf.post = readText(resolve(dirname(opts.config), conf.post.substring(1)), ctx.logger);
+            }
+        }
+    }
+    opts.debug && mutIn(ctx, ["config", "global", "debug"], true);
+    opts.string && mutIn(ctx, ["config", "global", "stringType"], opts.string);
+    const types = parseTypeSpecs(ctx, rest);
+    generateOutputs(ctx, types);
+    if (ctx.opts.analytics) {
+        // always write analytics, even if dry run
+        writeJSON(resolve(ctx.opts.analytics), types, undefined, "\t", ctx.logger);
     }
-    generateOutputs(ctx, parseTypeSpecs(ctx, rest));
 }
 catch (e) {
     if (!(e instanceof ParseError))

package/codegen/c.d.ts

@@ -0,0 +1,33 @@
+import type { ICodeGen } from "../api.js";
+/**
+ * Zig code generator options.
+ */
+export interface COpts {
+    /**
+     * If true, generates various struct & struct field analysis functions
+     * (sizes, alignment, offsets etc.).
+     *
+     * @defaultValue false
+     */
+    debug: boolean;
+    /**
+     * Optional prelude
+     */
+    pre: string;
+    /**
+     * Optional postfix (inserted after the generated code)
+     */
+    post: string;
+}
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export declare const C11: (opts?: Partial<COpts>) => ICodeGen;
+//# sourceMappingURL=c.d.ts.map

package/codegen/c.js

@@ -0,0 +1,100 @@
+import { isString } from "@thi.ng/checks/is-string";
+import { isPadding, isStringSlice, prefixLines, withIndentation, } from "./utils.js";
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export const C11 = (opts = {}) => {
+    const { debug } = { debug: false, ...opts };
+    const INDENT = "    ";
+    const SCOPES = [/\{$/, /\}\)?[;,]?$/];
+    const gen = {
+        pre: (opts) => `#pragma once
+#include <stddef.h>
+#include <stdint.h>${opts.pre ? `\n${opts.pre}` : ""}`,
+        post: () => opts.post || "",
+        doc: (doc, acc) => {
+            acc.push(prefixLines("// ", doc));
+        },
+        enum: (e, _, acc) => {
+            const lines = [];
+            lines.push(`enum {`);
+            for (let v of e.values) {
+                let line;
+                if (!isString(v)) {
+                    v.doc && gen.doc(v.doc, lines);
+                    line = `${e.name}_${v.name}`;
+                    if (v.value != null)
+                        line += ` = ${v.value}`;
+                }
+                else {
+                    line = v;
+                }
+                lines.push(line + ",");
+            }
+            lines.push("};", "");
+            acc.push(...withIndentation(lines, INDENT, ...SCOPES));
+        },
+        struct: (struct, _, acc, opts) => {
+            const name = struct.name;
+            const res = [];
+            res.push(`typedef struct ${name} ${name};`, `struct ${name} {`);
+            const ftypes = {};
+            let padID = 0;
+            for (let f of struct.fields) {
+                // autolabel explicit padding fields
+                if (isPadding(f)) {
+                    res.push(`__pad${padID++}: [${f.pad}]u8,`);
+                    continue;
+                }
+                f.doc && gen.doc(f.doc, res);
+                let ftype = f.type === "string"
+                    ? isStringSlice(opts.stringType)
+                        ? f.const !== false
+                            ? "[]const u8"
+                            : "[]u8"
+                        : f.const !== false
+                            ? "[*:0]const u8"
+                            : "[*:0]u8"
+                    : f.type;
+                switch (f.tag) {
+                    case "array":
+                    case "vec":
+                        ftype = `[${f.len}]${ftype}`;
+                        break;
+                    case "slice":
+                        ftype = `[]${f.const ? "const " : ""}${ftype}`;
+                        break;
+                    case "ptr":
+                        ftype = `*${f.const ? "const " : ""}${f.len ? `[${f.len}]` : ""}${ftype}`;
+                        break;
+                    case "scalar":
+                    default:
+                }
+                ftypes[f.name] = ftype;
+                res.push(`${f.name}: ${ftype},`);
+            }
+            res.push("};");
+            if (debug) {
+                res.push("");
+                const fn = (fname, body) => res.push(`size_t __attribute__((used)) ${name}_${fname}() {`, `return ${body};`, `}`);
+                fn("align", `alignof(${name})`);
+                fn("size", `sizeof(${name})`);
+                for (let f of struct.fields) {
+                    fn(f.name + "_align", `alignof(${ftypes[f.name]})`);
+                    fn(f.name + "_offset", `offsetOf(${name}, "${f.name}")`);
+                    fn(f.name + "_size", `sizeof(${ftypes[f.name]})`);
+                }
+            }
+            res.push("");
+            acc.push(...withIndentation(res, INDENT, ...SCOPES));
+        },
+    };
+    return gen;
+};

package/codegen/c11.d.ts

@@ -0,0 +1,22 @@
+import type { CodeGenOptsBase, ICodeGen } from "../api.js";
+/**
+ * Zig code generator options.
+ */
+export interface C11Opts extends CodeGenOptsBase {
+    /**
+     * Optional name prefix for generated types, e.g. `WASM_`.
+     */
+    typePrefix: string;
+}
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export declare const C11: (opts?: Partial<C11Opts>) => ICodeGen;
+//# sourceMappingURL=c11.d.ts.map

package/codegen/c11.js

@@ -0,0 +1,125 @@
+import { isString } from "@thi.ng/checks/is-string";
+import { unsupported } from "@thi.ng/errors/unsupported";
+import { enumName, isPadding, isStringSlice, prefixLines, withIndentation, } from "./utils.js";
+const PRIM_ALIASES = {
+    i8: "int8_t",
+    u8: "uint8_t",
+    i16: "int16_t",
+    u16: "uint16_t",
+    i32: "int32_t",
+    u32: "uint32_t",
+    i64: "int64_t",
+    u64: "uint64_t",
+    f32: "float",
+    f64: "double",
+};
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export const C11 = (opts = {}) => {
+    const { typePrefix } = {
+        typePrefix: "",
+        ...opts,
+    };
+    const INDENT = "    ";
+    const SCOPES = [/\{$/, /^\}[ A-Za-z0-9_]*[;,]?$/];
+    const gen = {
+        pre: (opts) => `#pragma once
+${opts.debug ? "\n#include <stdalign.h>" : ""}
+#include <stddef.h>
+#include <stdint.h>${opts.pre ? `\n${opts.pre}` : ""}`,
+        post: () => opts.post || "",
+        doc: (doc, acc, opts) => {
+            acc.push(...prefixLines("// ", doc, opts.lineWidth));
+        },
+        enum: (e, _, acc, opts) => {
+            if (!(e.tag === "i32" || e.tag === "u32")) {
+                unsupported(`enum ${e.name} must be a i32/u32 in C, but got '${e.tag}'`);
+            }
+            const name = typePrefix + e.name;
+            const lines = [];
+            lines.push(`typedef enum {`);
+            for (let v of e.values) {
+                let line;
+                if (!isString(v)) {
+                    v.doc && gen.doc(v.doc, lines, opts);
+                    line = enumName(opts, v.name);
+                    if (v.value != null)
+                        line += ` = ${v.value}`;
+                }
+                else {
+                    line = enumName(opts, v);
+                }
+                lines.push(line + ",");
+            }
+            lines.push(`} ${name};`, "");
+            acc.push(...withIndentation(lines, INDENT, ...SCOPES));
+        },
+        struct: (struct, coll, acc, opts) => {
+            const name = typePrefix + struct.name;
+            const res = [];
+            res.push(`typedef struct ${name} ${name};`, `struct ${name} {`);
+            const ftypes = {};
+            let padID = 0;
+            for (let f of struct.fields) {
+                // autolabel explicit padding fields
+                if (isPadding(f)) {
+                    res.push(`uint8_t __pad${padID++}[${f.pad}];`);
+                    continue;
+                }
+                f.doc && gen.doc(f.doc, res, opts);
+                const fconst = f.const ? "const " : "";
+                let ftype = f.type === "string"
+                    ? isStringSlice(opts.stringType)
+                        ? __slice("char", fconst)
+                        : `${f.const !== false ? "const " : ""}char*`
+                    : PRIM_ALIASES[f.type] || f.type;
+                if (coll[ftype])
+                    ftype = typePrefix + ftype;
+                switch (f.tag) {
+                    case "array":
+                    case "vec":
+                        res.push(`${fconst}${ftype} ${f.name}[${f.len}];`);
+                        ftype = `${ftype}[${f.len}]`;
+                        break;
+                    case "slice":
+                        ftype = __slice(ftype, fconst);
+                        res.push(`${ftype} ${f.name};`);
+                        break;
+                    case "ptr":
+                        ftype = `${fconst}${ftype}*`;
+                        res.push(`${ftype} ${f.name};`);
+                        break;
+                    case "scalar":
+                    default:
+                        res.push(`${ftype} ${f.name};`);
+                }
+                ftypes[f.name] = ftype;
+            }
+            res.push("};");
+            if (opts.debug) {
+                const fn = (fname, body) => res.push("", `size_t __attribute__((used)) ${name}_${fname}() {`, `return ${body};`, `}`);
+                fn("align", `alignof(${name})`);
+                fn("size", `sizeof(${name})`);
+                for (let f of struct.fields) {
+                    if (isPadding(f))
+                        continue;
+                    fn(f.name + "_align", `alignof(${ftypes[f.name]})`);
+                    fn(f.name + "_offset", `offsetof(${name}, ${f.name})`);
+                    fn(f.name + "_size", `sizeof(${ftypes[f.name]})`);
+                }
+            }
+            res.push("");
+            acc.push(...withIndentation(res, INDENT, ...SCOPES));
+        },
+    };
+    return gen;
+};
+const __slice = (type, $const) => `struct { ${$const}${type} *ptr; size_t len; }`;