The framework supports targeting WASM as a platform. This guide will help you set up everything to be able to easily deploy to WASM.

Note

Be aware of the limitations of WASM.

Installing Emscripten

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.

Linux and other Unixes

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 $ https://madladsquad.com/emsdk install latest
user $ https://madladsquad.com/emsdk activate latest
user $ source https://madladsquad.com/emsdk_env.sh

Windows

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

macOS

On macOS, you can install Emscripten through homebrew:

user $ brew install emscripten

Test compilation

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:

  1. Create a new folder for building under the root project directory, for example: wasm-build
  2. Enter the folder
  3. Run emcmake cmake ..
  4. Compile using the provided generated build system. For example, with emmake: emmake make -j <number of compile jobs>
  5. Serve the compiled files: emrun <project name>
  6. Open the served URL in your browser

If built successfully, you should be presented with a page, similar to this:

Using a custom HTML template, pre-js and post-js

Custom HTML

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)

Custom Javascript

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.