Easier to read with cream paper, a tint, more contrast or larger text? Choose your colours and text, once, for every page.

Free lesson

WebAssembly outside the browser

After this lesson: I can explain what a WebAssembly module contains by reading its bytes.

60 min lesson4 commandsWebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

One small file that runs anywhere

WebAssembly, or Wasm, is a compact binary format for programs, and a runtime turns it into machine code on whatever computer it lands on. Outside the browser it runs plugins, serverless functions and command-line tools in a sandbox.

Today you run a module with Wasmtime and read its bytes one by one.

By the end of this lesson

Note

I can explain what a WebAssembly module contains by reading its bytes.

Key words

WordWhat it meansExample
WebAssemblya portable binary format for programs
Moduleone compiled WebAssembly programadd.wasm
Runtimethe program that loads and runs a modulewasmtime
Sandboxa fence the program cannot reach past
Importa function the host must hand to the module
Sectionone labelled part of a .wasm file

The cells students fill in are left blank in this preview.

Why run WebAssembly outside the browser?

A native program is built for one processor and one operating system. A WebAssembly module is built once, and the runtime compiles it for the machine in front of it, Arm or Intel, Linux or Windows.

It also starts in milliseconds and is small. That is why it suits plugins and functions that start often. Wasmtime, from the Bytecode Alliance, is the runtime in your lab.

Ask Wasmtime its version

Command
docker exec wasm wasmtime --version

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Run a first WASI program

Command
docker exec wasm wasmtime run hello.wat

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

A module only reaches what it imports

A module has its own block of memory and nothing else. It cannot open a file, read the clock or send a byte unless the host hands it a function to do so. Those functions are its imports.

hello.wat imports one function, fd_write, from WASI, the WebAssembly System Interface. With that one import it can write text, and nothing more.

Worked example: what hello.wat asks for

PartIn hello.watWhat it means
Importfd_write from wasi_snapshot_preview1The host lets it write to a stream
Memoryone page of 64 KiBIts own memory, nobody else's
DataHello from WebAssemblyThe text, stored in that memory
Export_startWhere a WASI program begins

The cells students fill in are left blank in this preview.

What is inside a .wasm file?

A .wasm file starts with four magic bytes, 00 61 73 6d, which spell a zero and asm. Four bytes of version follow.

Then come sections. Each one is an id byte, its size, and its body. Sizes are written as LEB128: seven bits a byte, with the top bit set while more bytes follow. The lab built add.wasm byte by byte with wasmbin.py.

Read add.wasm section by section

Command
docker exec tools python3 steps/sections.py add.wasm

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Worked example: the sections of add.wasm

IdSectionSizeWhat the bytes say
1type7 bytesone function type: two i32 in, one i32 out
3function2 bytesone function, of type 0
7export7 bytesexport function 0 as add
10code9 byteslocal.get 0, local.get 1, i32.add, end

The cells students fill in are left blank in this preview.

A common mistake

Warning

Many people think a WebAssembly module is a small container. A container carries files of an operating system and calls the kernel directly. A module carries no operating system and can call nothing but its imports, so the host decides everything it may do.

Run the hand-built add.wasm

Command
docker exec wasm wasmtime run --invoke add add.wasm 2 3

Shown here, not run. Press Start lab to type it into your own lab’s terminal.

Try it: write numbers as LEB128

Code: python
def uleb(n):
    # Seven bits in each byte; the top bit says "another byte follows".
    out = []
    while True:
        low = n % 128
        n = n // 128
        if n > 0:
            out.append(low + 128)
        else:
            out.append(low)
            return out

for number in [5, 127, 128, 300]:
    text = ""
    for byte in uleb(number):
        text = text + format(byte, "02x") + " "
    print(number, "is written as", text)
# Add 1000 to the list. How many bytes does it need?

About this lab and its source: WebAssembly lab: Wasmtime, WASI capabilities, WIT components and plugin limits

Teaching a class? Set this module for your students with a teacher guide, marked assignments and a lab for every student.