Jaccwabyt: JavaScript ⇄ C Struct Communication via WASM Byte Arrays

This repository is the home of Jaccwabyt, a single-file JavaScript library which creates JS-side bindings of WebAssembly-compiled C structs, such that changes made to a struct in JS are visible in C and vice versa. The API is described in detail in its docs.

This project also maintains a documented, tested, copy/pastable mini-library intended to replace much of the Emscripten glue code (simply for the sake of reducing dependencies on any given WASM environment).

Platform compatibility: it's developed and tested in recent Firefox and Chrome versions and requires a recent browser. It in no way attempts to accommodate JS versions older than ES6 (JS 2015) and some features require capabilities newer (and less widespread) than that (like BigInt, which all of the latest browsers have but which any browsers older than 2018 definitely lack). Though Jaccwabyt is essentially platform-independent, it makes no specific attempts to account for non-browser JS environments like node.js. Contributions to make it more portable are welcomed so long as they do not limit it with regards to full-featured platforms.

Formalities

• License: Public Domain
• Author: Stephan Beal. Contributors are welcomed so long as they're willing to work with the Fossil SCM (i don't do github).

Downloading

This site is a Fossil SCM repository and can be cloned in full to obtain the whole source tree:

$ fossil clone https://fossil.wanderinghorse.net/r/jaccwabyt
$ cd jaccwabyt
$ ls -la

But the only two files one really needs for using Jaccwabyt is jaccwabyt.js and its documentation, which can be read online here or downloaded for local use here.

Building and Testing

Jaccwabyt itself does not depend on any given 3rd-party tools and is specifically designed to be able to be used with an any given WASM toolchain. However, this repository requires the following for building and running the test and demo code:

• The Emscripten SDK (with emcc in the $PATH) and/or the wasi-sdk (build expects it at /opt/wasi-sdk).
• GNU Make. The supplied makefile will not work with lesser make-wannabes.
• A Unix-style build environment.

Contributions of files for other build systems and OSes would be welcomed.

To reiterate, though: Jaccwabyt itself does not depend on those things, nor are they necessary for obtaining a working copy of Jaccwabyt (simply copy jaccwabyt.js).

With both GNU Make the Emscripten SDK installed and in the $PATH, simply run "make" (or, on some platforms, "gmake") to build the test and demo code. Because WASM code cannot be loaded from file:// URLs in some browsers, the test apps (testing-*.html) require that it be served from an HTTP server. There are many options for doing so, but one of the simplest (for Unix-like systems) is to build althttpd, add it to the $PATH, then run:

$ althttpd -page testing-emcc.html
# or:
$ althttpd -page testing-wasi-sdk.html
# or:
$ make www

The test output all goes to the browser dev console, so be sure to open the dev tools. The results for the tests must be the same for each build environment but they live in different HTML files because each requires different bootstrapping steps to get the module loaded and the test environment bootstrapped. Hypothetically they could all live in one page, and maybe that will happen one day, but it currently seems like it would just cause confusion in the test output.