WebAssembly has an S-expression-based textual representation, an intermediate form designed to be exposed in text editors, browser developer tools, etc. This article explains a little bit about how it works, and how to use available tools to covert text format files to the
.wasm assembly format.
Note: Text format files are usually saved with a
.wat extension; sometimes
.wast is also used, which refers to files containing extra testing commands allowed in such files that don't turn into
.wasm upon conversion — assertions, etc.
A first look at the text format
Let’s look at a simple example of this — the following program imports a function called
imported_func from a module called
imports, and exports a function called
(module (func $i (import "
imported_func") (param i32)) (func (export "exported_func") i32.const 42 call $i ) )
The WebAssembly function
imported_func, which is run with the value (42) provided as a parameter.
Converting the text .wat into a binary .wasm file
Let’s have a go at converting the above wat text representation example into wasm assembly format.
- To start with, make a copy of the above listing inside a text file; call it
- We need to assemble this textual representation into the assembly language the browser actually reads before we can use it. To do this, we can use the wabt tool, which includes compilers to convert between WebAssembly’s text representation and wasm, and vice versa, plus more besides. Go to https://github.com/webassembly/wabt — follow the instructions on this page to set the tool up.
- Once you’ve got the tool built, add the
/wabt/outdirectory to your system
- Next, execute the wast2wasm program, passing it the path to the input file, followed by an
-oparameter, followed by the path to the output file:
wast2wasm simple.wat -o simple.wasm
This will output the wasm into a file called simple.wasm, which contains the
.wasm assembly code.
Note: You can also convert the assembly back into the text representation using the wasm2wast tool; for example
wasm2wast simple.wasm -o text.wat.
Viewing the assembly output
Because the output file is assembly-based, it can’t be viewed in a normal text editor. You can however view it using the wast2wasm tool’s
-v option. Try this:
wast2wasm simple.wat -v
This will give you an output in your terminal like the following:
- Understanding WebAssembly text format — detailed explanation of the text format syntax.
- Text format — more explanation of the text format, on the WebAssembly GitHub repo.