Appendix B: Tools
This appendix collects the commands used in the book, and a few more, grouped by tool. The versions the book was checked against are:
wat2wasm --version
wasm-opt --version
node --version | cut -d. -f1
python3 -c "import wasmtime, importlib.metadata as m; print('wasmtime', m.version('wasmtime'))"
1.0.39 wasm-opt version 132 (version_132) v22 wasmtime 50.0.1
#wabtB.1
The WebAssembly Binary Toolkit: small, focused tools that follow the
specification closely. npm install wabt gives builds compiled to
WebAssembly; native builds are on GitHub.
| Command | Does |
|---|---|
wat2wasm in.wat -o out.wasm |
assemble the text format |
wat2wasm -v in.wat -o out.wasm |
the same, printing an annotated byte dump on stderr |
wat2wasm --debug-names in.wat |
keep $names in a name section |
wasm2wat in.wasm |
disassemble to the text format |
wasm2wat --fold-exprs in.wasm |
disassemble to the folded form |
wasm-objdump -h in.wasm |
list the sections and their sizes |
wasm-objdump -x in.wasm |
print every section's details |
wasm-objdump -d in.wasm |
disassemble the code, with bytes |
wasm-objdump -s in.wasm |
print each section's raw contents |
wasm-objdump -j Code -x in.wasm |
only one section |
wasm-validate in.wasm |
validate |
wasm-interp in.wasm --run-all-exports |
run every export that takes no arguments |
wasm-interp in.wasm -r f -a i32:5 |
call f(5) |
wasm-interp in.wasm --run-all-exports --trace |
the same, printing each instruction and the stack |
wasm-strip in.wasm |
remove every custom section |
wasm-decompile in.wasm |
a C-like rendering, easier to skim than the text format |
wasm2c in.wasm -o out.c |
translate to C, for running a module natively |
Most tools accept --enable-<feature> and --enable-all for features
that are not on by default.
#BinaryenB.2
A compiler infrastructure and optimiser for WebAssembly, used by
Emscripten, wasm-pack, Kotlin, Dart and many others. npm install
binaryen gives the tools and a JavaScript API.
| Command | Does |
|---|---|
wasm-opt -O3 in.wasm -o out.wasm |
optimise for speed |
wasm-opt -Oz in.wasm -o out.wasm |
optimise for size |
wasm-opt -g ... |
keep the name section |
wasm-opt --print in.wasm |
print Binaryen's view of the module |
wasm-opt --func-metrics in.wasm |
sizes and instruction counts per function |
wasm-opt --fuzz-exec in.wasm |
run the exports before and after optimising, and compare |
wasm-opt random.bin -ttf -o fuzz.wasm |
turn random bytes into a valid module, for fuzzing |
wasm-reduce |
shrink a module while it still shows a bug |
wasm-merge a.wasm a b.wasm b -o out.wasm |
link modules into one |
wasm-split |
split a module into a primary and a lazily loaded secondary |
wasm-metadce |
remove code unreachable from a given set of roots |
wasm2js in.wasm |
translate to JavaScript, for very old browsers |
wasm-as, wasm-dis |
Binaryen's own assembler and disassembler |
Binaryen's tools take --enable-<feature> and --all-features.
#wasm-toolsB.3
The Bytecode Alliance's toolkit, built on the same crates as Wasmtime.
Install with cargo install wasm-tools, or from release binaries.
| Command | Does |
|---|---|
wasm-tools parse in.wat -o out.wasm |
assemble |
wasm-tools print in.wasm |
disassemble |
wasm-tools validate in.wasm |
validate, with every standard feature |
wasm-tools dump in.wasm |
an annotated dump of every byte |
wasm-tools objdump in.wasm |
list the sections |
wasm-tools strip in.wasm |
remove custom sections |
wasm-tools smith < random.bin > out.wasm |
generate a random valid module |
wasm-tools shrink |
reduce a module while a predicate holds |
wasm-tools wast script.wast |
parse and validate a WAST script |
wasm-tools addr2line in.wasm 0x2d |
map a code offset to a source line, through DWARF |
#WasmtimeB.4
A standalone engine, compiled ahead of time with Cranelift. Useful as a second engine for differential testing.
| Command | Does |
|---|---|
wasmtime run in.wasm |
run a WASI command module |
wasmtime run --invoke f in.wasm 1 2 |
call an export with arguments |
wasmtime wast script.wast |
run a WAST script |
wasmtime compile in.wasm |
compile ahead of time to a .cwasm |
pip install wasmtime |
the Python bindings: wasmtime.wat2wasm, and a full embedding API |
#Node and V8B.5
| Command | Does |
|---|---|
node --liftoff-only script.mjs |
run WebAssembly only in the baseline tier |
node --no-liftoff script.mjs |
compile everything with TurboFan up front |
node --experimental-wasm-<feature> |
enable a proposal not yet on by default |
node --stack-size=N |
change the stack limit, in KiB |
node --prof script.mjs |
a CPU profile, including WebAssembly frames |
node --inspect-brk script.mjs |
debug in Chrome's DevTools |
#This book's scriptsB.6
| Command | Does |
|---|---|
python3 scripts/book.py test |
run every example in the book |
python3 scripts/book.py test 06* |
run the examples in matching chapters |
python3 scripts/book.py test --accept |
update expected outputs that changed |
python3 scripts/book.py build |
build the HTML and PDF editions |
node scripts/run.mjs m.wasm --invoke "f 1 2" |
the book's host |
python3 scripts/wast.py script.wast |
run a WAST script in V8 |
python3 scripts/opcodes.py |
print Appendix A's tables |