WebAssembly comes in two forms: there's a binary form, which is what the interpreting engines will actually execute, and there's also a text form, which expresses the same concepts as the binary form using more verbose text that humans can more readily read, debug, and understand (debatable). Browsers will transparently convert between the two forms whenever you try to examine and run WebAssembly code.
This repository contains code in the WebAssembly text format which was, against all advice, written by hand instead of compiled as intended. It was also then wrapped in a Markdown file and heavily annotated using a verbose coding style called literate programming, which treats source code like written material intended for humans instead of instructions intended for execution by computers. (For more on literate programming, see the
lit.sh repository.) I did this both as an exercise to help me learn how WebAssembly works under the hood, and also because it is ridiculous.
Before the annotated code can be executed, it must first be compiled twice. Those two compilation tasks are:
- parse the Markdown and strip the annotations, leaving behind pure WebAssembly code
In order to parse the Markdown, you'll first need to install
lit.sh, a tool that helps with literate programming. To get it, navigate to the project directory in your terminal and run this line of code:
# install lit.sh $ curl https://raw.githubusercontent.com/vijithassar/lit/master/lit.sh > lit.sh && chmod +x lit.sh
# install npm dependencies $ npm install
Now you're ready to run the code.
$ npm run test
The test script will itself run the
npm run assemble script, which performs the two compilation tasks described above. Afterwards, you'll see two additional artifacts in the directory, both of them
add.watis the WebAssembly code in text format
add.wasmis the WebAssembly code in binary format; this is what will actually be executed
The "execution" command is really just a wrapper around a couple of unit tests, so it won't show you anything interesting unless something goes wrong, but if the tests pass then you can be certain the annotated WebAssembly code actually works as expected.