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 minimum Emcsripten version, which will not change for the lifetime of that minor version. Qt's binary packages are built using this version of the Emscripten SDK. Install the minimum Emcsripten version that corresponds to the Qt version you use, especially if you use the binary packages.

Later versions of Emscripten may work (and often do), but may introduce behavior changes which require changes to Qt.

The minimum versions are:

• Qt 6.2: 2.0.14

• Qt 6.3: 3.1.6

Use emsdk to install specific emscripten versions. For example, to install it for Qt 6.2 enter:

• ./emsdk install 2.0.14

• ./emsdk activate 2.0.14

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

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 do not enable features such as threads or SIMD support.

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