Build for WebAssembly
./build.sh --wasm compiles the same C#, lib/ and zerocore to WebAssembly modules for WASI. The
source doesn't change: the samples that run natively run under wasmtime and print the same output,
apart from what depends on the platform. This guide covers the setup, the build, running the modules,
and what differs. Run it on WebAssembly is the short version.
Get the toolchain
bflat can't target WebAssembly, so the last steps use other tools. Download them once:
./setup.sh --wasm
This puts three tools into tools/wasm, pinned in env.sh:
| Tool | Version | Job |
|---|---|---|
| NativeAOT-LLVM | 10.0.0-rc.1.26357.1 | compiles IL to LLVM bitcode |
| WASI SDK | 34.0 | its clang compiles the bitcode and links the module |
| wasmtime | 50.0.1 | runs the module |
They take about 900 MB unpacked, mostly the WASI SDK. They are Linux builds; on macOS they run in the
build container, like bflat. To keep them elsewhere, set WASM_TOOLS; on macOS it has to be a
directory inside the repository, or the container can't see it.
Build
./build.sh --wasm # every sample, into bin/wasm/*.wasm
./build.sh --wasm Arena # just one
Each module goes through three compilers:
- bflat compiles the sample to IL against
bin/BflatLib.dll, exactly as for the native build. - NativeAOT-LLVM compiles the IL to LLVM bitcode against zerocore's WebAssembly build (zerocore
compiled with
-d WASM).[DllImport("libc")]and[DllImport("libm.so.6")]are bound at link time to WASI's C library. - The WASI SDK's clang compiles the bitcode and links it with
wasm/runtime.cand WASI's C library.runtime.cis zerocore's native half on WebAssembly: the entry point, the shadow stack and the transitions NativeAOT-LLVM's code calls. Allocation, casts and interface calls are zerocore's C#, the same code as on Linux.
The modules are stripped. They range from about 16 KB (Tiny) to about 80 KB (Collections and Strings); build.sh prints
each module's size when it finishes.
build.sh builds the programs listed in its ALL_SAMPLES. To build a new file in samples/, add its
name there.
Run
./run.sh --wasm Arena
./run.sh --wasm Quiz < answers.txt
run.sh --wasm runs bin/wasm/<Sample>.wasm with the wasmtime from tools/wasm, passing any further
arguments to the program. Standard input reaches the program, so In.ReadLine works as it does
natively. The exit code is the program's.
To check every sample against the native output:
./test.sh --wasm
What's different
- 32-bit pointers. Structs that hold pointers are smaller, so code that prints sizes prints smaller
numbers: the arena byte counts in Arena and Collections differ, and
test.shchecks only their exit codes on WebAssembly. - No SIMD. Instruction sets report
IsSupported == false, so Simd and Kernels take their scalar paths. WebAssembly has 128-bit SIMD, butlib/Kernels.cshas no path for it yet. - One thread. zerocore's WebAssembly build is its single-threaded 32-bit build.
- Clocks. Simd and Kernels call
clock_gettime(1, ...), Linux's numericCLOCK_MONOTONIC. In WASI's C library a clock ID is a pointer, so this reads the clock ID from address 1, which is zero: the realtime clock. That still measures durations. - Exit codes. Modules are linked for WASI 0.1 (
wasm32-wasip1), which passes exit codes through. WASI 0.2 only reports success or failure, and the samples report failed checks in their exit code. - Stacks. The link sets a 1 MB stack, and
wasm/runtime.creserves a 1 MB shadow stack, where managed code keeps the locals WebAssembly's own stack can't address. - Not supported: callbacks from native code into C# (
[UnmanagedCallersOnly]reverse P/Invoke inside a running program), andbuild.ps1on Windows.
Running elsewhere
A module is linked for WASI 0.1 against WASI's C library, so it needs a runtime with WASI 0.1. The
repository runs modules only with wasmtime 50.0.1 (in run.sh and test.sh), so that is the one
that is tested. On Linux you can call it without run.sh; <arch> is x86_64 or aarch64:
tools/wasm/wasmtime-v50.0.1-<arch>-linux/wasmtime run bin/wasm/Arena.wasm
Watch out for
- Treat the versions as a set.
wasm/runtime.cand zerocore implement NativeAOT-LLVM's internal runtime functions (RhpNewArray,RhpResolveInterfaceDispatchand others), whose names and signatures were read from the compiler's output, not from documentation. A changed signature fails the link, becausebuild.shturnswasm-ld's signature warnings into errors. A changed meaning only shows when a program runs. After changing any version inenv.sh, rerun the samples and compare their output with the native build. - It still needs bflat.
build.sh --wasmcompiles zerocore,lib/and the sample to IL with the bflat fork first, so the fork has to be installed as for the native build.
See also: How the targets work, Build for DOS, which starts from the same bitcode, and Limits.