cpp-on-the-web

Compiling C++ to the Web using WebAssembly

This skill provides guidance for using Emscripten to target the modern web with C and C++. It focuses on ES6 module output, clean JS/C++ interop, and common pitfalls.

Quick Start

1. Installation: Use the Emscripten SDK (emsdk) as the quickest way to install.

   ./emsdk install latest
   ./emsdk activate latest
   source ./emsdk_env.sh
   

2. Environment: Ensure emcc is in your PATH.
3. Boilerplate: Use the hello-world template in assets/hello-world.
   • main.cpp: Basic Embind example.
   • index.html: Modern ES6 module loading.
   • Makefile: Recommended flags for modern web.

Recommended Compilation Flags

• -sSTRICT: Opt into modern Emscripten behavior.
• -sEXPORT_ES6: Output a modern ES6 module (this implies -sMODULARIZE).
• -sENVIRONMENT=web: For optimal codesize limit the output only run on the web.
• -Werror -Wall: Treat warnings as errors for safer C++ code.
• -Oz/-Os: To minimal the payload size use -Oz/-Os for release builds rather then -O2/O3.
• -flto: Use this flag when both compiling and linking in release mode to enable LTO for optimal performance.
• -sALLOW_MEMORY_GROWTH: Allow the WASM heap to grow (required for many real-world apps).
• --bind: Enable Embind for clean, class-based interop.

Best Practices

• Prefer standard flags: Use standard compiler flags (e.g., -pthread, -g, -O3) over Emscripten-specific -s flags where possible.
• Boolean flags: For boolean Emscripten flags (like -sSTRICT), omit the =1 suffix. Emscripten treats the presence of the flag as enabled.
• List-based flags: For flags that take lists (e.g., -sEXPORTED_FUNCTIONS), use the simple comma-separated form (e.g., main,malloc) rather than the more verbose JSON form.

Separate Compilation

For larger projects, always use separate compilation (compiling .cpp to .o files before linking). This allows for incremental builds and is the standard practice for C/C++ development.