michaelfranzl.github.io

clang-wasm-browser-starterpack

Minimal working examples of C and C++ development targeting the web via WebAssembly.

Background

LLVM/Clang can directly emit WebAssembly since version 8. For simple scenarios, this allows a lean and direct development workflow targeting the web, omitting other SDKs like emscripten.

The wasi-sdk project is a cornerstone in this workflow. It contains no compiler or library code itself; it merely pulls in via git submodules the upstream clang tree, as well as the wasi-libc tree. It contributes a Makefile which compiles both projects using suitable flags (most notably disabling pthreads which is not yet supported in wasi-libc.

The other cornerstone in this workflow, wasi-libc is an implementation of the C standard library which compiles down to WASI syscalls (calls which would ‘normally’ be done into the an OS kernel). The implementation of the actually used syscalls have to be provided (in other words, imported) to the WebAssembly instance. Since we are targeting the web, the implementation is provided by the JavaScript library @wasmer/wasi via the browser.

After the building of wasi-sdk, the entire toolchain (version 12 of clang, clang++, wasm-ld, etc.) will be installed in the sub-directory ./wasi-sdk/build/install/opt/wasi-sdk.

The wasi-sdk project lacks examples that show how it can be used; the present project aims to fill that gap.

Motivation

Inspired by the awesome emscripten project, I wanted to understand the low-level mechanics of getting compiled C and C++ code to run in the browser, and to find the leanest possible workflow.

Instead of writing blog posts and code fragments, I decided to produce working examples, because I believe that working code is king. :)

Examples

You only need a modern browser to run the examples, which already contain pre-built WebAssembly code.

The examples start as simple as possible, and then add more and more complexity:

Plain C

C with Standard Library

Plain C++

C++ with Standard Library

Live examples

A copy of this repository is hosted on my GitHub Page where these examples are live.

To run the examples locally, simply serve the example directory using a static file server, e.g. you could use the built-in web server of the Ruby or Python 3 runtime:

cd examples
ruby -run -ehttpd . -p8000

Or

cd examples
python3 -m http.server 8000

Then visit http://localhost:8000.

Building

Install the dependencies listed below.

# Clone this repository
git clone https://github.com/michaelfranzl/clang-wasm-browser-starterpack.git
cd lang-wasm-browser-starterpack

# Build a specific commit of wasi-sdk
git clone --recurse-submodules https://github.com/WebAssembly/wasi-sdk.git # about 1.5 GB
cd wasi-sdk
git checkout a927856376271224d30c5d7732c00a0b359eaa45 # use llvm 12.0.0 release
make
cd ..

# Build the examples
make clean
make

# Serve the examples locally
cd examples
ruby -run -ehttpd . -p8000

Dependencies

To provide all these dependencies on Debian 11, simply run:

apt install build-essential binaryen wabt