Compiling to WASM with llvm on macOS#

howto-wasm-minimal by Zalka Ernő (my fork here) is a neat demo of a minimal WASM module. It uses C++ to define functions for simple image manipulation including blurring an image, compiles it to WASM using llvm/clang++, then uses JavaScript to run those functions against an image loaded into a <canvas> element.

I decided to try compiling it myself:

1
cd /tmp
2
git clone https://github.com/ern0/howto-wasm-minimal
3
cd howto-wasm-minimal
4
./build.sh

This gave me the following error:

1
error: unable to create target: 'No available targets are compatible with triple "wasm32"'

Searching for the error lead me to this comment:

You need to install llvm from Homebrew. Xcode’s clang doesn’t have support for WebAssembly.

So I installed llvm from Homebrew:

1
% brew install llvm
2
...
3
To use the bundled libc++ please add the following LDFLAGS:
4
  LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
5

6
llvm is keg-only, which means it was not symlinked into /usr/local,
7
because macOS already provides this software and installing another version in
8
parallel can cause all kinds of trouble.
9

10
If you need to have llvm first in your PATH, run:
11
  echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> ~/.zshrc
12

13
For compilers to find llvm you may need to set:
14
  export LDFLAGS="-L/usr/local/opt/llvm/lib"
15
  export CPPFLAGS="-I/usr/local/opt/llvm/include"
16
...

I’ve quoted the relevant output. I’m not ready to permanently replace the system llvm with the one from Homebrew, so I ran the build script like this instead:

1
% PATH="/usr/local/opt/llvm/bin:$PATH" ./build.sh
2
0000000 00 61 73 6d 01 00 00 00 01 14 04 60 00 00 60 01

That created a inc.wasm file in my current folder.

I tried opening index.html in Firefox and got the following error:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///private/tmp/howto-wasm-minimal/inc.wasm. (Reason: CORS request not http).

So I ran a localhost web server instead using this Python one-liner:

1
% python3 -m http.server 8004
2
Serving HTTP on :: port 8004 (http://[::]:8004/) ...

This worked! http://localhost:8004/ displayed the working demo:

For reference, here’s that build.sh script in full:

1
#!/bin/bash
2
set -e
3

4
clang++ \
5
  --target=wasm32 \
6
  -nostdlib \
7
  -O3 \
8
  -Wl,--no-entry \
9
  -Wl,--export-all \
10
  -Wl,--lto-O3 \
11
  -Wl,--allow-undefined \
12
  -Wl,--import-memory \
13
  -o inc.wasm \
14
  inc.cpp
15

16
hexdump inc.wasm | head -n 1
17
#wasm-objdump -x inc.wasm

Bonus: Web Assembly Binary Toolkit#

The last commented-out line of that script caught my attention:

1
wasm-objdump -x inc.wasm

I searched, and wasm-objdump is part of the tools provided by the WebAssembly Binary Toolkit .

You can install that with Homebrew by running brew install wabt.

Then this worked:

1
% wasm-objdump -x inc.wasm
2

3
inc.wasm:  file format wasm 0x1
4

5
Section Details:
6

7
Type[4]:
8
 - type[0] () -> nil
9
 - type[1] (i32) -> i32
10
 - type[2] (i32, i32) -> nil
11
 - type[3] (i32, i32, i32) -> nil
12
Import[1]:
13
 - memory[0] pages: initial=2 <- env.memory
14
Function[7]:
15
 - func[0] sig=0 <__wasm_call_ctors>
16
 - func[1] sig=1 <inc>
17
 - func[2] sig=0 <incmem>
18
 - func[3] sig=2 <gray>
19
 - func[4] sig=2 <swaprg>
20
 - func[5] sig=3 <swap_red>
21
 - func[6] sig=2 <blur>
22
Global[7]:
23
 - global[0] i32 mutable=1 <__stack_pointer> - init i32=66560
24
 - global[1] i32 mutable=0 <__dso_handle> - init i32=1024
25
 - global[2] i32 mutable=0 <__data_end> - init i32=1024
26
 - global[3] i32 mutable=0 <__global_base> - init i32=1024
27
 - global[4] i32 mutable=0 <__heap_base> - init i32=66560
28
 - global[5] i32 mutable=0 <__memory_base> - init i32=0
29
 - global[6] i32 mutable=0 <__table_base> - init i32=1
30
Export[13]:
31
 - func[0] <__wasm_call_ctors> -> "__wasm_call_ctors"
32
 - func[1] <inc> -> "inc"
33
 - func[2] <incmem> -> "incmem"
34
 - func[3] <gray> -> "gray"
35
 - func[4] <swaprg> -> "swaprg"
36
 - func[5] <swap_red> -> "swap_red"
37
 - func[6] <blur> -> "blur"
38
 - global[1] -> "__dso_handle"
39
 - global[2] -> "__data_end"
40
 - global[3] -> "__global_base"
41
 - global[4] -> "__heap_base"
42
 - global[5] -> "__memory_base"
43
 - global[6] -> "__table_base"
44
Code[7]:
45
 - func[0] size=2 <__wasm_call_ctors>
46
 - func[1] size=7 <inc>
47
 - func[2] size=69 <incmem>
48
 - func[3] size=101 <gray>
49
 - func[4] size=215 <swaprg>
50
 - func[5] size=1332 <swap_red>
51
 - func[6] size=615 <blur>
52
Custom:
53
 - name: "name"
54
 - func[0] <__wasm_call_ctors>
55
 - func[1] <inc>
56
 - func[2] <incmem>
57
 - func[3] <gray>
58
 - func[4] <swaprg>
59
 - func[5] <swap_red>
60
 - func[6] <blur>
61
 - global[0] <__stack_pointer>
62
Custom:
63
 - name: "producers"

Also fun: wasm-decompile to “decompile a wasm binary into readable C-like syntax”:

1
% wasm-decompile inc.wasm
2
import memory env_memory;
3

4
global stack_pointer:int = 66560;
5
export global dso_handle:int = 1024;
6
export global data_end:int = 1024;
7
export global global_base:int = 1024;
8
export global heap_base:int = 66560;
9
...

And wasm-opcodecnt to “count opcode usage for instructions”:

1
% wasm-opcodecnt inc.wasm
2
Total opcodes: 1188
3

4
Opcode counts:
5
local.get: 263
6
i32.const: 240
7
i32.add: 172
8
local.set: 88
9
...

More in the README: https://github.com/WebAssembly/wabt/blob/main/README.md

Newsletter

Compiling to WASM with llvm on macOS#

Bonus: Web Assembly Binary Toolkit#