Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 38 ยท The Text Format

WebAssembly Text Format (WAT) Basics

Learn the WebAssembly text format (WAT): S-expressions, modules, functions, flat and folded instructions, names, comments, and how to turn WAT into a .wasm file.

Writing bytes by hand taught you what a module is, but nobody would write a real program that way. The WebAssembly Text Format, WAT, is the human-readable form of the same program. It has the extension .wat, it maps one to one onto the binary format, and it is what you see when you open a .wasm file in a debugger, a disassembler or the browser's developer tools. You will use it to read compiler output, to write small hand-optimized routines, and to understand what is going on.

From text to binary

The browser and Node.js only run binary. They do not contain a text parser, so WebAssembly.compile('(module)') is an error. Text is converted by a tool, the assembler:

Tool Command
WABT wat2wasm add.wat -o add.wasm (and wasm2wat add.wasm goes back)
wasm-tools wasm-tools parse add.wat -o add.wasm (and wasm-tools print)
Binaryen wasm-as add.wat and wasm-dis add.wasm

Chapter 8 covers installing and using them. In this chapter every example shows the WAT source, and the runnable block next to it contains the exact bytes wat2wasm produced from that source, written as hex. That way you run real assembler output without installing anything.

S-expressions

WAT is written as S-expressions: nested lists in parentheses, where the first word names the kind of thing and the rest are its parts. If you have seen Lisp, the look is familiar. Whitespace and line breaks do not matter. There are two comment styles:

WAT
;; a line comment runs to the end of the line
(; a block comment (; can nest ;) ;)

Everything lives inside one module:

WAT
(module
  (func $add (export "add") (param $a i32) (param $b i32) (result i32)
    local.get $a
    local.get $b
    i32.add)
  (func (export "answer") (result i32)
    i32.const 42)
)

Take it apart:

  • (module ...) is the whole file. Inside are fields such as func, memory, global, table, data, import and export, in any order (the assembler puts them in binary order for you).
  • (func $add ...) defines a function. $add is an identifier: a name you invented that starts with $. Names exist only in the text and vanish in the binary (unless you ask for a name section).
  • (export "add") written inside the function header is shorthand for a separate export field. The string is the name JavaScript sees.
  • (param $a i32) declares a parameter, (result i32) a result, (local $t i32) a local variable. Parameters and locals share one index space: parameters first, then locals.
  • The instructions follow, one per line, written in flat style.

Flat and folded forms

A function body is a sequence of instructions for the stack machine. You can write them flat, as a plain list:

WAT
local.get $a
local.get $b
i32.add

or folded, where an instruction is a list that contains its own operands:

WAT
(i32.add (local.get $a) (local.get $b))

Folded form reads like an expression in C: the operation first, then its arguments. It is only syntax. The assembler flattens it, so both forms produce identical bytes. Use folded for arithmetic that reads well as a tree, and flat for stack manipulation. Mixing is fine.

flowchart LR
    A["Folded: (i32.add (local.get $a) (local.get $b))"] --> C["same bytes"]
    B["Flat: local.get $a / local.get $b / i32.add"] --> C

Names versus numbers

You can also write indexes directly: local.get 0 instead of local.get $a. The assembler converts names into numbers. Names are for people, so use them in source you maintain. When you read a disassembled module without a name section, you will see numbers such as func[3] and local.get 2, and you have to work out the meaning yourself.

Running real assembler output

Below is the module above with a second, folded function. The hex string is what wat2wasm produced for it (81 bytes). A tiny helper turns the hex into bytes.

Node.js Run the output of wat2wasm

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The two add functions behave identically because they compile to the same instructions. The names $a and $b are gone: only the export names survive.

Memory, globals and data in text

The same format declares the other parts of a module. The fields you met in chapter 2 look like this in WAT:

WAT
(memory (export "mem") 1)                 ;; one page, exported as "mem"
(global $count (mut i32) (i32.const 0))   ;; mutable i32 starting at 0
(data (i32.const 0) "WAT")                ;; write "WAT" at address 0

(mut i32) marks a mutable global; a constant one is just i32. A data field's string can contain escapes such as \00 (a hexadecimal byte) and \n. A table is (table 4 funcref) and (elem (i32.const 0) $f $g) fills it. Here they are in a working module:

WAT
(module
  (memory (export "mem") 1)
  (global $count (mut i32) (i32.const 0))
  (func (export "next") (result i32)
    (global.set $count (i32.add (global.get $count) (i32.const 1)))
    (global.get $count))
  (data (i32.const 0) "WAT")
)
Node.js Memory, a global and a data segment in WAT

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Common mistakes

  • Putting export or param after the instructions. Declarations such as param, result and local must come before the first instruction.
  • Forgetting that i32.const needs an operand. i32.const alone is an error; write i32.const 42.
  • Using the wrong type name. Types are lowercase: i32, i64, f32, f64.
  • Unbalanced parentheses. One missing ) ends up as a confusing error far from the cause. Most editors can match parentheses; use them.

When something does not assemble, simplify: delete everything but one function and add pieces back. Error messages from wat2wasm report a line and column, and are usually right.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Can you pass WAT text directly to WebAssembly.compile()?

    Engines only accept the binary format. Tools like wat2wasm convert text to binary.
  2. 2. What is the difference between flat and folded instructions?

    Folded form is syntactic sugar for the flat sequence; the assembler produces identical binary.
  3. 3. What happens to the identifier $count in the binary?

    Binary uses numeric indexes. Names are only kept in the optional name custom section for debugging.
  4. 4. In (func (param $a i32) (local $t i32) ...), what index does $t have?

    Parameters are numbered first, so $a is local 0 and the first declared local $t is local 1.

Summary

  • WAT is the readable form of the binary format; engines only run binary, so a tool (wat2wasm, wasm-tools parse) assembles it.
  • A module contains fields (func, memory, global, table, data, import, export) written as S-expressions.
  • Instructions can be written flat or folded; both give identical bytes.
  • $names are for humans and disappear from the binary unless you keep a name section.
  • Parameters and locals share one index space, parameters first.

Next: The Stack Machine and Instructions