Build for the Web with Emscripten

SLProject can be built to run in a web browser. We use the Emscripten toolchain, which compiles C/C++ code to a binary instruction format called WebAssembly. The generated Wasm module can be loaded by ordinary JavaScript at runtime. The browser then compiles the instructions to native machine code and runs it, making it possible to run high-performance code in the browser. To access OpenGL functions, browsers expose the WebGL API, which Emscripten wraps in standard OpenGL headers. SLProject uses WebGL 2, which is based on OpenGL 3.0 ES. Not all scenes from app-Demo-SLProject can run in the browser because OpenGL 4.0 functions are not available or because some OpenCV modules can't be compiled for WebAssembly. For more background on our integration see the Emscripten page in our online documentation.

Installation

1. Clone the Emscripten SDK:

   git clone https://github.com/emscripten-core/emsdk.git
   

2. Install and activate the latest SDK version:

   cd emsdk
   ./emsdk install latest
   ./emsdk activate latest
   

Building

Terminal

1. Set up the Emscripten environment:

   . <emsdk>/emsdk_env
   

2. Go into the SLProject directory and check out the develop branch:

   cd <SLProject>
   git checkout develop
   

3. Create the build directory:

   mkdir cmake-build-emscripten-debug
   

4. CMake by itself doesn't recognize the Emscripten toolchain. However, Emscripten provides a CMake wrapper (emcmake) which adds additional arguments to the CMake command to make it use the Emscripten toolchain. Run CMake with this wrapper:

   cd cmake-build-emscripten-debug
   emcmake cmake -DSL_BUILD_WAI=OFF ..
   

5. Build the demo:

   cmake --build . --target app-demo
   

CLion

1. Go into the SLProject directory and check out the develop branch:

   cd <SLProject>
   git checkout develop
   

2. Open the SLProject directory in CLion:
3. Register the Emscripten toolchain:
   • Go to File > Settings > Build, Execution, Deployment > Toolchains
   • Add a new system toolchain and name it Emscripten
   • Set C compiler to <emsdk>/upstream/emscripten/emcc.sh (<emsdk> being the path to your Emscripten SDK)
   • Set C++ compiler to <emsdk>/upstream/emscripten/em++.sh (<emsdk> being the path to your Emscripten SDK)
4. Register the Emscripten Debug profile:
   • Go to File > Settings > Build, Execution, Deployment > CMake
   • Add a new profile and name it Debug-Emscripten
   • Set the toolchain to Emscripten
   • Set the following CMake options: -DCMAKE_TOOLCHAIN_FILE=<emsdk>/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -DSL_BUILD_WAI=OFF (<emsdk> being the path to your Emscripten SDK)
5. Build the project with the Debug-Emscripten profile

Running

1. Run the server script:

   # On macOS and Linux:
   cd <SLProject>/cmake-build-emscripten-debug
   python3 serve-app-demo.py
   
   # On Windows:
   cd <SLProject>/cmake-build-emscripten-debug
   python serve-app-demo.py
   

2. Open your browser and enter http://localhost:8080

To run a different app than the demo app, use the server script with the name serve-.