Targeting WASM
The framework supports targeting WASM as a platform. This guide will help you set up everything to be able to easily deploy to WASM.
To compile to WASM, you will need to install Emscripten, which is a toolchain for building C/C++ applications that can run on the web.
You need to manually install Emscripten, using the following commands:
user $ git clone https://github.com/emscripten-core/emsdk.git
user $ cd emsdk
user $ git pull
user $ ./emsdk install latest
user $ ./emsdk activate latest
user $ source ./emsdk_env.sh
On Windows, you need to have Python 3 installed. After that, run the following commands:
> git clone https://github.com/emscripten-core/emsdk.git
> cd emsdk
> git pull
> emsdk.bat install latest
> emsdk.bat activate latest
> emsdk_env.bat
On macOS, you can install Emscripten through homebrew:
user $ brew install emscripten
Once you have everything installed, run emcc --version to check if everything is set up correctly. If everything is fine, you can try compiling a project.
To compile a project, do the following:
- Create a new folder for building under the root project directory, for example:
wasm-build - Enter the folder
- Run
emcmake cmake .. - Compile using the provided generated build system. For example, with
emmake:emmake make -j <number of compile jobs> - Serve the compiled files:
emrun <project name>.html - Open the served URL in your browser
If built successfully, you should be presented with a page, similar to this:
When shipping an application for production, you might want to provide a custom HTML file. To do that, you can use the following base template code:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
</head>
<body>
<canvas id="canvas" oncontextmenu="event.preventDefault()"></canvas>
<script type='text/javascript'>
var Module = {
canvas: (function() { return document.getElementById('canvas'); })()
};
</script>
<script src="<project name>.js"></script>
</body>
</html>Make sure to replace <project name>.js with your own project's Javascript file.
After that, you can disable the USE_HTML_GENERATION option in your Config/cmake/<project name>.cmake file, like this:
set(USE_HTML_GENERATION OFF)To enabled pre- and post-javascript, simply enable the following options in your Config/cmake/<your project>.cmake file, like this:
set(ENABLE_PRE_SCRIPT ON)
set(ENABLE_POST_SCRIPT ON)The 2 Javascript files in question can be found under the Config/WASM/ folder.
More information on when pre- and post-javascript files are called can be found here.