Qt for Webassembly lets you to run Qt applications on the web.
WebAssembly (abbreviated Wasm) is a binary instruction format intended to be executed in a virtual machine, for example in a web browser.
With Qt for WebAssembly, you can distribute your application as a web application that runs in a browser sandbox. This approach is suitable for web distributed applications that do not require full access to host device capabilities.
注意： Qt for WebAssembly is a supported platform, but some modules are not yet supported or are in Tech Preview. See Supported Qt Modules .
Building Qt applications for WebAssembly is similar to building Qt for other platforms. You need to install an SDK (Emscripten), install Qt (or build Qt from source), and finally, build the application. Some differences exist, for example, Qt for WebAssambly supports fewer modules and less features than other Qt builds.
Emscripten is a toolchain for compiling to WebAssembly. It lets you run Qt on the web at near-native speed without browser plugins.
参考 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:
使用
emsdk
去安装特定
Emscripten
versions. For example, to install it for Qt 6.5 enter:
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.
把 Qt 配置成交叉编译构建为
wasm-emscripten
platform. This sets the
-static
,
-no-feature-thread
，和
-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
注意：
configure always uses the
Ninja
generator and build tool if a
ninja
executable is available. Ninja is cross-platform, feature-rich, performant, and recommended on all platforms. The use of other generators might work but is not officially supported.
On Windows, make sure you have MinGW in your
PATH
并配置如下：
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.
注意： Emscripten produces relatively large .wasm files at the "-g" debug level. Consider linking with "-g2" for debug builds.
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.
Emscripten provides the emrun utility for test-running applications. Emrun starts a web server, launches a browser, and will also capture and forward stdout/stderr (which will normally go to the JavaScript console).
/path/to/emscripten/emrun --browser=firefox appname.html
Another option is to start a development web server and then launch the web browser separately. One of the simplest options is http.server from Python:
python -m http.server
Note that this is only a simple webserver and does not support SharedArrayBuffer required for threading, as the required COOP and COED headers mentioned below are not sent.
Qt provides a developer web server which uses mkcert to generate https certificates. This allows testing web features which require a secure context . Note that delivery over http://localhost is also considered secure, without requiring a certificate.
The web server also sets the COOP and COEP headers to values which enables support for SharedArrayBuffer and multi-threading.
The qtwasmserver script starts one server which binds to localhost by default. You may add additional addresses using the -a command-line argument, or use --all to bind to all available addresses.
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).
| 生成的文件 | 简要描述 |
|---|---|
| app.html | HTML 容器 |
| qtloader.js | JavaScript API for loading Qt apps |
| app.js | 用于加载 Qt APP 的 JS API |
| app.wasm | app binary |
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:
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 for WebAssembly supports a subset of the Qt modules and features. Tested modules are listed below, other modules may or may not work.
In all cases, module support may not be complete and there may be additional limitations, either due to the browser sandbox or due to incompleteness of the Qt platform port. See Developing with Qt for WebAssembly for further info.
Qt for WebAssembly Technology Preview modules and features. These features may require to reconfigure and build Qt. They may contain features that are still experimental in the browsers or Emscripten.
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 | WebGL |
|---|---|
| OpengL ES 2 | WebGL 1 |
| OpengL ES 3 | WebGL 2 |
OpenGL ES 2 and OpenGL ES 3 are enabled by default, and can be selected through the QSurfaceFormat::setMajorVersion () 函数。
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 spesifics 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:
Emscripten supports WebAssembly SIMD , which provides 128-bit SIMD types and operations for WebAssembly.
Build Qt from source and configure with the -feature-wasm-simd128 flag to enable; this will pass the -msimd128 flag at compile and link time. Note that Qt does not contain wasm-simd optimized code paths at this point, however enabling wasm-simd will enable compiler auto-vectorization where the compiler can use the SIMD instructions.
You can target WebAssembly SIMD directly using either GCC/Clang SIMD Vector Extensions or WASM SIMD128 intrinsics. For more information, see the Emscripten SIMD documentation .
In addition, Emscripten supports emulating/translating x86 SSE instructions to Wasm SIMD instructions. Qt does not use this emulation, as the use of SSE SIMD instructions that have no native Wasm SIMD equivalent may cause reduced performance.
Note that SIMD-enabled binaries are incompatible with browsers that do not support WebAssembly SIMD, also if the SIMD code paths are not called at run-time. SIMD support may need to be enabled in the browsers advanced configurations, such as 'about:config' or 'chrome:flags'
Qt provides limited support for networking. In general, network protocols which are already in use on the web can be use also from Qt, while others are not directly available due to the web sandbox.
The following protocols are supported:
All other network protocols are not supported.
File system access is sandboxed on the web, and this has implications for how the application works with files. The Web platform provides APIs for accessing the local file system in a way which is under user control, as well as APIs for accessing persistent storage. Emscripten and Qt wraps these features and provides APIs which are easier to use from C++ and Qt-based applications.
The web platform provides features for accessing local files and persistent storage:
Emscripten provides several file systems with a POSIX like API. These include:
Emscripten mounts a temporary MEMFS filesystem to "/" at app startup. This means that QFile can be used, and will read and write files to memory by default. Qt provides other API as well:
Qt supports copying and pasting text to the system clipboard, with some differences due to the web sandbox. In general clipboard access require user permission, which can be obtained by handling an input event (e.g. CTRL+c), or by using the Clipboard API .
Browsers that support the Clipboard API are preferred. Note that a requirement for this API is that the web page is served over a secure connection (e.g. https), and that some browsers my require changing configuration flags.
见 caniuse for which browsers currently support the Clipboard API. The following versions are known to work:
dom.events.asyncClipboard.read dom.events.asyncClipboard.clipboardItem
The Qt WASM module contains 3 embedded fonts: "Bitstream Vera Sans" (fallback font), "DejaVu Sans", "DejaVu Sans Mono".
These fonts provide a limited character set. Qt provides several options for adding additional fonts:
One is using FontLoader in QML, which can either fetch a font by URL or using Qt 资源系统 (the same way the usual desktop apps work).
The other way to use font is to add it via QFontDatabase::addApplicationFontFromData .
Qt for WebAssembly supports the standard Qt startup approach, where the application creates a QApplication object and calls the exec function:
int main(int argc, char **argc) { QApplication app(argc, argv); QWindow appWindow; return app.exec(); }
The exec() call above normally blocks and processes events until application shutdown. Unfortunately this is not possible on the web platform where blocking the main thread is not allowed. Instead, control must be returned to the browser's event loop after processing each event.
Qt works around this by making exec() return main thread control to the browser, while preserving the stack. From the point of view of application code, the exec() function is entered and event processing happens as usual. However, the exec() call never returns, also not on application exit.
This behavior is usually acceptable since the browser will free up application memory at app shutdown time. It does mean that shutdown code does not run, since the application object is leaked and its destructor does not run.
You can avoid this by rewriting main() to be asynchronous, which is possible since Emscripten does not exit the runtime when main() returns. Application code then omits making the exec() call, and can shut down Qt cleanly by deleting the top-level window and application objects.
QApplication *g_app = nullptr; AppWindow *g_appWindow = nullptr; int main(int argc, char **argc) { g_app = new QApplication(argc, argv); g_appWindow = new AppWindow(); return 0; }
The default build of Qt for WebAssembly does not support reentering the event loop, for example by calling QEventLoop::exec () 或 QDialog::exec (), due to restrictions of the web platform.
Emscripten's asyncify feature lifts these restrictions by allowing synchronous calls (like QEventLoop::exec () 和 QDialog::exec ()) to yield to the event loop. Nested calls are not supported, and for this reason asyncify is not used for the top-level QApplication::exec () 调用。
Features that require asyncify are:
As of Qt 6.4, Asyncify support is enabled in the binary package, but needs to be enabled for applications by adding -sASYNCIFY -Os to linker options:
CMake:
set target_link_options(<target> PUBLIC -sASYNCIFY -Os)
qmake:
QMAKE_LFLAGS += -sASYNCIFY -Os
Enabling asyncify adds overhead in the form of increased binary sizes and increased CPU usage. Build with optimizations enabled to minimize the overhead.
Wasm debugging is done on browser JavaScript console, debugging applications on Wasm directly within Qt Creator is not possible.
You can add more verbosity to help debug using Emscripten linker arguments:
Using cmake:
target_link_options(<your target> PRIVATE "SHELL:-s LIBRARY_DEBUG=1")
Using qmake:
QMAKE_LFLAGS_DEBUG += -s LIBRARY_DEBUG=1
Qt is built without exception support by default, where throwing an exception will abort the program. WebAssembly exceptions can be enabled by building from source and passing the -feature-wasm-exceptions flag to Qt configure. This will pass the -fwasm-exceptions flag to the compiler at compile and link time. Qt does not support enabling Emscripten's support for the earlier JavaScript-based exception implementation.
Note that calling QApplication::exec () is not supported when exceptions are enabled, due to internal implementation details. Instead, write main() in the form where it returns early and does not call exec(), as described in Application Startup and the Event Loop .
The following configure options are relevant when building Qt for WebAssembly from source.
| Configure Argument | 简要描述 |
|---|---|
| -feature-thread | Multi-threaded wasm |
| -feature-wasm-simd128 | Enables WebAssembly SIMD support. |
| -feature-wasm-exceptions | Enables WebAssembly exceptions support. |
| -feature-opengles3 | Use opengles3 in addition to the default opengles2 |
| -device-option QT_EMSCRIPTEN_ASYNCIFY=1 | Use asyncify |
Expected footprint (download size): Wasm modules as produced by the compiler can be large, but compress well:
| 范例 | gzip | brotli |
|---|---|---|
| helloglwindow ( QtCore + QtGui ) | 2.8M | 2.1M |
| wiggly widget ( QtCore + QtGui + QtWidgets) | 4.3M | 3.2M |
| SensorTag ( QtCore + QtGui + QtWidgets + QtQuick + QtCharts ) | 8.6M | 6.3M |
Compression is typically handled on the web server side, using standard compression features: the server compresses automatically or picks up pre-compressed versions of the files. There's generally no need to have special handling of wasm files.
Qt for WebAssembly 在商业许可下是可用的来自 Qt 公司 。此外，它是可用的根据 GNU GPL (一般公共许可) 第 3 版 。见 Qt 许可 进一步了解细节。
