michaelfranzl / clang-wasm-browser-starterpack

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

Clang-WASM-Browser Starterpack

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

Background

Clang can directly emit WebAssembly since version 8. For simple scenarios, this allows a lean and direct software development workflow targeting the web, omitting more complete 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 llvm-project tree, as well as the wasi-libc tree. It contributes a Makefile which compiles these components using suitable flags.

wasi-libc is an implementation of the C standard library which compiles down to WASI syscalls (calls which would 'normally' be done into the OS kernel). The implementation of the actually used syscalls has 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.

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.

Running

Using Nix

nix run
# Wait for it:
# Serving HTTP on 127.0.0.1 port 8000 (http://127.0.0.1:8000/) ...

Manual

Download and extract or install wasi-sdk Release 22.

Set the path to the extracted or installed wasi-sdk as WASI_SDK (default: /opt/wasi-sdk) and run make in the examples subdirectory:

cd examples

WASI_SDK=/path/to/wasi-sdk make

# Start a generic web server:
python3 -m http.server 8000 --bind 127.0.0.1


# In a different terminal:
open http://localhost:8000/

The Examples

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

Plain C

• Example 1: Exports
• Example 2: Default imports
• Example 3: Renamed imports

C with Standard Library

• Example 4: printf("Hello World!\n")

String handling

• Example 5: Returning a string
• Example 6: Passing a string to a function
• Example 7: Calling int main(int argc, char* argv[])

Plain C++

• Example 10: Adding two numbers

C++ with Standard Library

• Example 11: Print a vector element

clang-wasm-browser-starterpack's Issues

Need help with compiling C++ to wasm

Hi Michael!

I am attempting to compile C++ to WebAssembly without using Emscripten or other alternative methods that would require modifications to my C++ code (such as adding macros). I saw your answer to this Stackoverflow question from 2021 and found this repo.

I attempted to compile the 11th example, but unfortunately encountered two error messages:

wasm-ld: error: unknown --unresolved-symbols value: import-functions
wasm-ld: error: unable to find library -lclang_rt.builtins-wasm32

Actually I'm curious if there have been any advancements or new methods for compiling C++ to wasm since then. If so, I would greatly appreciate any guidance or resources you could provide. Otherwise, I would be grateful for any assistance in overcome these error messages.

Thanks.