emnudge / watlings

Learn WebAssembly by writing small programs!

Watlings

Learn the WebAssembly Text Format
by fixing a bunch of small programs!

Usage

This project uses Node 16+ & NPM for compilation and testing.

Clone the repository and install dependencies with:

git clone [email protected]:EmNudge/watlings.git
cd watlings
npm install

Complete lessons by following the instructions in each exercise within the exercises directory.

Test your answer to an exercise with the start command:

npm start 001_hello

If you'd like to view the solution to an exercise, use the show command:

npm run show 001_hello

To apply it directly to the exercise, use solve instead of show:

npm run solve 001_hello

Recommended Editor

We recommend using VSCode with the WATI extension.

This should provide syntax highlighting, intellisense, and other helpful features as you work through the exercises.

Using Wat2Wasm Directly (Recommended)

To compile your WAT code, we use NPM WABT.

For syntax highlighting and up-to-date builds, you can optionally use the official WebAssembly Binary Toolkit which will provide you with a wat2wasm CLI tool. If it is found on your path as wat2wasm, it will be used instead.

While it is strictly optional, it can help with debugging.

Motivations

I've found just diving in to be the best way to build experience with programming.

Rustlings & Ziglings have both had tremendous returns to my journeys with both languages.

WebAssembly (and by extension WAT) has a more sparse educational landscape than most and I was hoping to fill some of the gaps by building a project with the same sort of structure.

Pedagogical Philosophy

Outlined here are some thoughts on what makes a good teaching experience.

Typing Over Reading

The goal is to learn by doing. Comments on each file outline a task and some background. However, a lot about a language can be gleaned by its syntax alone. We should be adding as little explanation as possible.

Occasional gaps in knowledge can be filled by consistent exposure to the syntax within different contexts. Certain things can therefore be learned without any mention.

Introduction text is superfluous. Words add visual noise, so we should be careful with our count. Coding itself should supplement ambiguities in the text.

If you find a text confusing or too verbose, please create a discussion post!

Create Struggle

Studies have shown that one cannot learn effectively without effort. This applies to practically every domain of knowledge. These projects should be educational, not easy.

This does not mean we should make the education itself elusive. We should not make learning more difficult, but instead more intentional.

When introducing a lot of new syntax, keep the problem scope small, but force the user to read a bit. If the syntax is not new, increase the problem scope. Maybe many variations of the same task.

Credits

• rustlings
• Ziglings

watlings's Issues

[feature] Add "tooling" section to readme

As the puzzles get more advanced, we'll want to have a section for recommended tooling to the readme.

My current best pick is Visual Studio Code + WATI extension.

[feature] Add optional wat2wasm shell support

We're currently using the npm wabt package for compilation from wat to wasm. It is managed by AssemblyScript, but it is always going to be (and currently is) out of date.

The CLI tool wat2wasm from the wabt toolkit has much better descriptive errors and is managed by the WebAssembly org.

I don't have the time nor the expertise to maintain my own fork, so a good option might be to support using a local install of wat2wasm over the wabt npm package for compilation. This should improve error logs.

This would be an optional feature, not necessary to get up and running. I'd like to remove the friction of configuring yet another binary to get started with this project.

Move to wasm-tools

We currently use WABT's wat2wasm for converting to web assembly.

Recently, the Bytecode Alliance has recently published wasm-tools which seem to cover everything WABT does plus a bunch more.

I think this can also be an opportunity to delve into the debugging side of WASM by making a lesson specifically around wasm-tools.

It also has the advantage of using Rust, which means I can probably reuse code for a language server.

009_data test fails due to improper call to `TextDecoder.decode`

At

watlings/tests/009_data.test.js

Line 25 in ef4d776

loggedStrings.push(new TextDecoder().decode(byteSlice, "utf-8"));

and line 42, we attempt to decode a text buffer with new TextDecoder().decode(byteSlice, "utf-8"). This fails with

TypeError: The "options" argument must be of type object. Received type string ('utf-8')

As per documentation at https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder/decode, this failure should be expected; the second argument to decode should be an options argument with the only valid key stream. To modify the behavior of the decoder, we instead should specify the label in the constructor (new TextDecoder('utf-8)). This is, however, unnecessary as utf-8 is the default decoder configuration.

Changing the line as follows allows this test to pass when the corresponding 009_data.wat file is updated to emit three different strings:

loggedStrings.push(new TextDecoder().decode(byteSlice));

Windows support

The readme doesn't mention that, but the npm run things use bash under the hood, and that is not supported in Windows. If Windows supported is not intended, it should be explicit especially when VSCode is mentioned.

watch mode support

It would be nice if the tests could be run in watch mode, also having a way to pick an exercise in CLI rather than type their names out - or even automatically progressing to the next exercise.