Qt for WebAssembly

Emscripten is a toolchain for compiling to WebAssembly. It lets you run Qt on the web at near-native speed without browser plugins.

Refer to the Emscripten documentation for more information about installing the Emscripten SDK.

After installation, you should have the Emscripten compiler in your path. Check this with the following command:

em++ --version

Each minor version of Qt targets a specific Emcsripten version, which remains unchanged in patch releases. Qt's binary packages are built using the target Emscripten version. Applications should use the same version since Emscripten does not guarantee ABI compatibility between versions.

The Emcsripten versions are:

• Qt 6.2: 2.0.14

• Qt 6.3: 3.0.0

• Qt 6.4: 3.1.14

• Qt 6.5: 3.1.25

Use emsdk to install specific Emscripten versions. For example, to install it for Qt 6.5 enter:

• ./emsdk install 3.1.25

• ./emsdk activate 3.1.25

On Windows, Emscripten is in your path after installation. On macOS or Linux you need to add it to your path, like this:

source /path/to/emsdk/emsdk_env.sh

Check this with the following command:

em++ --version

You can build Qt from source if you require more flexibility when selecting the Emcsripten version. In this case the versions above are minimum versions. Later versions are expected to work but may introduce behavior changes which require making changes to Qt.

Download Qt from the Downloads section of your Qt account. We provide builds for Linux, macOS, and Windows as development platforms.

The binary builds are designed to run on as many browsers as possible, and come in single-threaded and multi-threaded versions. Non-standard features such as wasm SIMD and wasm exceptions are not supported by the binary builds.

Building from source lets you set Qt configuration options such as thread support, OpenGL ES level, or SIMD support. Download the Qt sources from the Downloads section of your Qt account.

Configure Qt as a cross-compile build for the wasm-emscripten platform. This sets the -static, -no-feature-thread, and -no-make examples configure options. You can enable thread support with the -feature-thread, configure option. Shared library builds are not supported.

You need a host build of the same version of Qt and specify that path in the QT_HOST_PATH CMake variable or by using the -qt-host-path configure argument.

Although it should be detected, you may optionally set the CMAKE_TOOLCHAIN_FILE CMake variable to the Emscripten.cmake toolchain file that comes with Emscripten SDK. This can be done by setting the environment variable CMAKE_TOOLCHAIN_FILE or by passing CMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake to configure.

./configure -qt-host-path /path/to/Qt -platform wasm-emscripten -prefix $PWD/qtbase

On Windows, make sure you have MinGW in your PATH and configure with the following:

configure -qt-host-path C:\Path\to\Qt -no-warnings-are-errors -platform wasm-emscripten -prefix %CD%\qtbase

Then build the required modules:

cmake --build . -t qtbase -t qtdeclarative [-t another_module]

Qt for WebAssembly supports building applications using qmake and make, or CMake with ninja or make.

$ /path/to/qt-wasm/qtbase/bin/qt-cmake .
$ cmake --build .

Building the application generates several output files, including a .wasm file that contains the application and Qt code (statically linked), a .html file that can be opened in the browser to run the application.

Running the application requires a web server. The build output files are all static content, so any web server will do. Some use cases might require special server configuration, such as providing https certificates or setting http headers required to enable multithreading support.

Emrun▲

/path/to/emscripten/emrun --browser=firefox appname.html

Python http.server▲

python -m http.server

qtwasmserver▲

python /path/to/qtbase/util/wasm/qtwasmserver/qtwasmserver.py --all

Setting Up Qt Creator for WebAssembly.

Building an application generates several files (substitute "app" with the application name in the following table).

You can deploy app.html as-is, or discard it in favor of a custom html file. Smaller adjustments, such as changing the splash screen image from the Qt logo to the app logo, is also possible. In both cases, qtloader.js provides a JavaScript API for loading the application.

We recommend compressing the wasm file using e.g. gzip or brotli before deployment, as this can provide a significant reduction in file size.

Enabling certain features, such as multi-threading and SIMD, produces .wasm binaries that are incompatible with browsers that do not support the enabled feature. It is possible to work around this limitation by building multiple .wasm files and then use JavaScript feature detection to select the correct one, but note that Qt does not provide any functionality for doing this.

Qt for WebAssembly is developed and tested on the following browsers:

• Chrome

• Firefox

• Safari

• Edge

Qt should run if the browser supports WebAssembly. Qt has a fixed WebGL requirement, even if the application itself does not use hardware accelerated graphics. Browsers that support WebAssembly often support WebGL, though some browsers blacklist older or unsupported GPUs. s/qtloader.js provides APIs to check if WebGL is available.

Qt does not make direct use of operating system features and it makes no difference if, for example, FireFox runs on Windows or macOS. Qt does use some operating system adaptations, for example for ctrl/cmd key handling on macOS.

Qt for WebAssembly applications runs on mobile browsers such as mobile Safari and Android Chrome.

Qt requires WebGL, also for applications which do not use OpenGL directly. All relevant browsers support WebGL, but note that some browsers blacklist certain older GPUs. The Qt loader will detect this and display an error message.

Qt detects WebGL as OpenGL ES, with the following version mapping:

OpenGL ES 2 and OpenGL ES 3 are enabled by default, and can be selected through the QSurfaceFormat::setMajorVersion() function.

Web and Desktop OpenGL differences are documented in WebGL and OpenGL Differences. There are additional differences between WebGL 1.0 and WebGL 2.0, documented in the WebGL 2.0 Specification.

A WebGL-friendly subset of ES2 (and ES3) is used by default. If you need to use glDrawArrays and glDrawElements without bound buffers, you can enable full ES2 support by adding

target_link_options(<your target> PRIVATE "SHELL:-s FULL_ES2=1")

and/or full ES3 emulation by adding

target_link_options(<your target> PRIVATE "SHELL:-s FULL_ES3=1")

to your project's CMakeLists.txt.

Qt for WebAssembly supports multithreading using Emscripten's Pthreads support, where each thread is backed by a web worker. Enable multithreading by installing the "WebAssembly (multi-threaded)" component from the Qt Maintenance Tool, or by building Qt from source and passing the "-feature-thread" flag to configure.

Existing threading code can generally be reused, but may need to be modified to work around specifics of the pthread implementation. Some Emscripten and Qt features are not supported, this includes the thread proxying feature and the Qt Quick threaded render loop.

Be aware that it is especially important to not block the main thread on Qt for WebAssembly, since the main thread might be required to service requests from secondary threads. For example, all timers in Qt are scheduled on the main thread, and will not fire if the main thread is blocked. Another example is that creating a new web worker (for a thread) can only be done from the main thread.

Emscripten provides some mitigations for this. Short-term waits such as acquiring a mutex lock is supported by busy-waiting and processing events while waiting for the lock. Longer waits on the main thread should be avoided. In particular, the common practice of calling QThread::wait() or pthread_join() to wait for a secondary thread will not work, unless the application can guarantee that the thread (and web worker) has already been started, and will be able to complete without assistance from the main thread at the time that the wait() or join() call is made.

The multithreading feature requires browser support for the SharedArrayBuffer API. (Normally, Emscripten stores the heap in an ArrayBuffer object. For multithreading, the heap must be shared with web workers and a SharedArrayBuffer is needed) This API is generally available in all modern browsers, but may be disabled if certain security requirements are not met. WebAssembly binaries with thread support enabled will then fail to run, also if the binary does not actually start a thread.

Enabling SharedArrayBuffer requires a secure browsing context (where the page is served over https:// or http://localhost), and that the page is in cross-origin isolated mode. The latter can be done by setting the so called COOP and COEP headers on the web server:

• Cross-Origin-Opener-Policy: same-origin

• Cross-Origin-Embedder-Policy: require-corp

Emscripten supports