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
| Word | What it means | Example |
|---|---|---|
| WebAssembly | a portable binary format for programs | |
| Module | one compiled WebAssembly program | add.wasm |
| Runtime | the program that loads and runs a module | wasmtime |
| Sandbox | a fence the program cannot reach past | |
| Import | a function the host must hand to the module | |
| Section | one 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
docker exec wasm wasmtime --versionShown here, not run. Press Start lab to type it into your own lab’s terminal.
Run a first WASI program
docker exec wasm wasmtime run hello.watShown 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
| Part | In hello.wat | What it means |
|---|---|---|
| Import | fd_write from wasi_snapshot_preview1 | The host lets it write to a stream |
| Memory | one page of 64 KiB | Its own memory, nobody else's |
| Data | Hello from WebAssembly | The text, stored in that memory |
| Export | _start | Where 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
docker exec tools python3 steps/sections.py add.wasmShown here, not run. Press Start lab to type it into your own lab’s terminal.
Worked example: the sections of add.wasm
| Id | Section | Size | What the bytes say |
|---|---|---|---|
| 1 | type | 7 bytes | one function type: two i32 in, one i32 out |
| 3 | function | 2 bytes | one function, of type 0 |
| 7 | export | 7 bytes | export function 0 as add |
| 10 | code | 9 bytes | local.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
docker exec wasm wasmtime run --invoke add add.wasm 2 3Shown here, not run. Press Start lab to type it into your own lab’s terminal.
Try it: write numbers as LEB128
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?