Qt for WebAssembly: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(clarified known good versions of emscripten for multithreading)
(Make it clearer that the Qt documentation is the authoritative documentation.)
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Qt for WebAssembly makes it possible to build Qt applications for the web platform.
Qt for WebAssembly makes it possible to build Qt applications for the web platform.


Qt for WebAssembly is currently in development. Qt 5.12 featured Qt for WebAssembly as a tech preview. From Qt 5.13 onwards, Qt for WebAssembly is a supported platform.


''Note:'' The [https://doc.qt.io/qt-5/wasm.html Qt documentation] is the authoritative source on Qt for WebAssembly. This page contains additional platform notes.


=== Licensing ===
 
 
 
'''<big>''Note:'' Please see the [https://doc.qt.io/qt-5/wasm.html Qt documentation] for instructions on how to get started with Qt for WebAssembly. This page is preserved as a historical reference.</big>'''
 
 
 
 
 
<br />
===Licensing===


Qt for WebAssembly is available for commercial usage under the Qt Commercial license, and for open source usage under the [https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3]. For more information, please check the [https://www.qt.io/licensing/ general licensing information] of Qt.
Qt for WebAssembly is available for commercial usage under the Qt Commercial license, and for open source usage under the [https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License version 3]. For more information, please check the [https://www.qt.io/licensing/ general licensing information] of Qt.


=== Getting Started ===
===Getting Started===
Qt-based applications are built for WebAssembly using the Emscripten SDK. Supported host/build platforms are Linux, macOS, and [https://docs.microsoft.com/en-us/windows/wsl/install-win10 Windows Subsystem for Linux] . Qt 5.13 will in addition support Windows with MinGW.  
Qt-based applications are built for WebAssembly using the Emscripten SDK. Supported host/build platforms are Linux, macOS, and [https://docs.microsoft.com/en-us/windows/wsl/install-win10 Windows Subsystem for Linux] . Qt 5.13 will in addition support Windows with MinGW.  


The getting started steps are:
The getting started steps are:
# Install the Emscripten SDK
# Build Qt from source
# Build and run applications


==== Install the Emscripten SDK ====
#Install the Emscripten SDK
#Build Qt from source
#Build and run applications
 
====Install the Emscripten SDK====
Install [http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html Emscripten] according to instructions.
Install [http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html Emscripten] according to instructions.


Line 23: Line 32:


{| class="wikitable"
{| class="wikitable"
|+ Known-good versions
|+Known-good versions
!Qt Version ||Singlethreading ||Multithreading ||Additional info
!Qt Version||Singlethreading||Multithreading||Additional info
|-
|-
|5.12       ||1.38.16         ||NA             ||
|5.12||1.38.16||NA||
|-
|-
|5.13       ||1.38.27         ||1.38.30       ||
|5.13||1.38.27||1.38.30||
|-
|-
|5.14       ||1.38.27         ||1.38.30       ||see "Emsdk version for Qt 5.14" below
|5.14||1.38.27||1.38.30||see "Emsdk version for Qt 5.14" below
|-
|-
|5.15       ||colspan="2"|1.39.8               ||tentative; 1.38.x/fasctcomp is no longer supported
|5.15|| colspan="2" |1.39.8||tentative; 1.38.x/fasctcomp is no longer supported
|-
|-
|}
|}


Use emsdk to install specific emscripten versions (example):
Use emsdk to install specific emscripten versions (example):
* ./emsdk install sdk-fastcomp-1.38.27-64bit or (was)  sdk-1.38.16-64bit
 
* ./emsdk activate --embedded sdk-fastcomp-1.38.27-64bit or (was) sdk-1.38.16-64bit
*./emsdk install sdk-fastcomp-1.38.27-64bit or (was)  sdk-1.38.16-64bit
*./emsdk activate --embedded sdk-fastcomp-1.38.27-64bit or (was) sdk-1.38.16-64bit
 
You may want to install multiple versions of the SDK, in which case the "-embedded" option is useful. It locates all configuration and cache files inside the SDK dir so that multiple versions do not conflict. The "64bit" in the SDK version refers to the host bit-ness.
You may want to install multiple versions of the SDK, in which case the "-embedded" option is useful. It locates all configuration and cache files inside the SDK dir so that multiple versions do not conflict. The "64bit" in the SDK version refers to the host bit-ness.


===== Emsdk version for Qt 5.14 =====
=====Emsdk version for Qt 5.14=====
The Qt 5.14 binary packagers are produced with emsdk 1.38.27: make sure to use that version when using the binary package.
The Qt 5.14 binary packagers are produced with emsdk 1.38.27: make sure to use that version when using the binary package.


Starting with emsdk 1.39.0, the emcc compiler no longer compiles via asm.js, but instead generates wasm bytecode directly. Support for the 1.39.x series is in scope for Qt 5.14. However, be aware that the build flags are still tailored for the previous compiler, where minimizing the size of the intermediate asm.js was important.
Starting with emsdk 1.39.0, the emcc compiler no longer compiles via asm.js, but instead generates wasm bytecode directly. Support for the 1.39.x series is in scope for Qt 5.14. However, be aware that the build flags are still tailored for the previous compiler, where minimizing the size of the intermediate asm.js was important.


==== Build Qt from source ====
====Build Qt from source====
The Qt sources can be downloaded from your Qt Account, in the Downloads section. For the latest revision of the code, you can also check it out from our git repositories directly: http://code.qt.io/cgit/qt/qt5.git/
The Qt sources can be downloaded from your Qt Account, in the Downloads section. For the latest revision of the code, you can also check it out from our git repositories directly: http://code.qt.io/cgit/qt/qt5.git/


Line 58: Line 69:
<blockquote>make module-qtbase module-qtdeclarative [other modules] </blockquote>
<blockquote>make module-qtbase module-qtdeclarative [other modules] </blockquote>


==== Build and run applications ====
====Build and run applications====
We support the qmake build system. Run qmake from the Qt for WebAssembly build in the directory which contains the applications .pro file:<blockquote>/path/to/qtbase/bin/qmake && make</blockquote>
We support the qmake build system. Run qmake from the Qt for WebAssembly build in the directory which contains the applications .pro file:<blockquote>/path/to/qtbase/bin/qmake && make</blockquote>


Line 82: Line 93:
You can also use:<blockquote>/path/to/emscripten/emrun --browser=firefox appname.html</blockquote>Debug and logging output go to the browser's debug console. If you are using Firefox, you can use CTRL+SHIFT+K to open the debug console.
You can also use:<blockquote>/path/to/emscripten/emrun --browser=firefox appname.html</blockquote>Debug and logging output go to the browser's debug console. If you are using Firefox, you can use CTRL+SHIFT+K to open the debug console.


=== Platform Notes ===
===Platform Notes===
The Qt for WebAssembly platform port has limitations; these are due to the sandboxed nature of the web platform, the platform APIs provided (or not provided), and the incomplete nature of the Qt port. This section describes several topics which may be of interest for application developers.
The Qt for WebAssembly platform port has limitations; these are due to the sandboxed nature of the web platform, the platform APIs provided (or not provided), and the incomplete nature of the Qt port. This section describes several topics which may be of interest for application developers.


==== Supported target browsers/devices ====
====Supported target browsers/devices====
Desktop:
Desktop:
* Chrome
 
* FireFox
*Chrome
* Safari
*Firefox
* Edge (Chrome)
*Safari
*Edge (Chrome)
 
If the browser supports WebAssembly then Qt should run. Note that Qt has fixed WebGL requirement, also for apps that do not use WebGL directly. Browsers often blacklist WebGL for older/unsupported GPUs.
If the browser supports WebAssembly then Qt should run. Note that Qt has fixed WebGL requirement, also for apps that do not use WebGL directly. Browsers often blacklist WebGL for older/unsupported GPUs.


Mobile:
Mobile:
* Android Browser
 
* Mobile Safari
*Android Browser
*Mobile Safari
 
'''Note:''' There is currently no support for text input using the virtual keyboard. Safari currently does not support wasm modules of the size Qt produces.
'''Note:''' There is currently no support for text input using the virtual keyboard. Safari currently does not support wasm modules of the size Qt produces.


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


==== Supported Qt Modules ====
====Supported Qt Modules====
Qt for WebAssembly supports a subset of the Qt modules. The currently supported modules are
Qt for WebAssembly supports a subset of the Qt modules. The currently supported modules are
* qtbase
 
* qtdeclarative
*qtbase
* qtquickcontrols2
*qtdeclarative
* qtwebsockets
*qtquickcontrols2
* qtsvg
*qtwebsockets
* qtcharts
*qtsvg
* qtmqtt
*qtcharts
*qtmqtt


Unsupported:
Unsupported:
* qtmultimedia
 
* qtwebview
*qtmultimedia
*qtwebview


Other modules are not tested and may or may not work.
Other modules are not tested and may or may not work.


==== Multithreading Support ====
====Multithreading Support====


Qt on WebAssembly supports multithreading, however support is disabled by default in order to be compatible with as many browsers as possible. Thread support can be enabled by building Qt from source and configuring with the "-feature-thread" flag. The WebAssembly binary packages do not support multithreading.
Qt on WebAssembly supports multithreading, however support is disabled by default in order to be compatible with as many browsers as possible. Thread support can be enabled by building Qt from source and configuring with the "-feature-thread" flag. The WebAssembly binary packages do not support multithreading.
Line 122: Line 139:
The minimum Emscripten SDK version is 1.38.30. The [https://emscripten.org/docs/porting/pthreads.html?highlight=pthreads Emscripten pthreads documentation] contains relevant documentation for multithreading.
The minimum Emscripten SDK version is 1.38.30. The [https://emscripten.org/docs/porting/pthreads.html?highlight=pthreads Emscripten pthreads documentation] contains relevant documentation for multithreading.


Threads are supported in some (but not all) browsers. Configuration changes may be required. The [https://www.qt.io/web-assembly-example-mandelbrot mandelbrot] demo can be used to determine if thread support is available. Note that it is the build mode which determines if browser thread support is required, not whether the application starts a thread or not.
Threads are supported in some (but not all) browsers. Configuration changes may be required. The [https://msorvig.github.io/qt-webassembly-mandelbrot/] demo can be used to determine if thread support is available. Note that it is the build mode which determines if browser thread support is required, not whether the application starts a thread or not.


'''Current Browser Status''':
'''Current Browser Status''':
* Chrome (and derivatives): supported
* Safari: not supported
* FireFox: can be enabled


'''On FireFox''', open about:config and make sure the following option is enabled:
*Chrome (and derivatives): supported
*Safari: not supported
*Firefox: supported since 79<ref>{{Cite web|url=https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/Planned_changes|title=MDN SharedArrayBuffer reference}}</ref>


*  javascript.options.shared_memory = true
In '''Firefox''' versions before 79, open about:config and make sure the following option is enabled:


Thread support is currently disabled in the release version of FireFox (v. 74 at time of writing). A future
*javascript.options.shared_memory = true
FireFox release will enabled thread support, provided that that the web server sets two additional headers:


* Cross-Origin-Opener-Policy: same-origin
Thread support will only be enabled provided that that the web server sets two additional headers:
* Cross-Origin-Embedder-Policy: require-corp
 
*Cross-Origin-Opener-Policy: same-origin
*Cross-Origin-Embedder-Policy: require-corp


(These are the COOP and COEP headers, respectively)
(These are the COOP and COEP headers, respectively)


Mozilla bug [https://bugzilla.mozilla.org/show_bug.cgi?id=1619649%20. 1619649] tracks the FireFox defaults change. In the mean
Mozilla bug [https://bugzilla.mozilla.org/show_bug.cgi?id=1619649%20. 1619649] tracks the Firefox defaults change. In the mean
time, its possible to manually bypass or enable the header check:
time, its possible to manually bypass or enable the header check:


FireFox Nightly or Beta - bypass header check:
FireFox Nightly or Beta - bypass header check:


* dom.postMessage.sharedArrayBuffer.bypassCOOP_COEP.insecure.enabled = true
*dom.postMessage.sharedArrayBuffer.bypassCOOP_COEP.insecure.enabled = true


FireFox Release - enable header check:
FireFox Release - enable header check:


* browser.tabs.remote.useCrossOriginEmbedderPolicy = true
*browser.tabs.remote.useCrossOriginEmbedderPolicy = true
* browser.tabs.remote.useCrossOriginOpenerPolicy = true
*browser.tabs.remote.useCrossOriginOpenerPolicy = true


After enabling the header check, make sure your web server sets the required headers. See [https://bugreports.qt.io/browse/QTBUG-79087 QTBUG-79087] for an example python-based  development server.
After enabling the header check, make sure your web server sets the required headers. See [https://bugreports.qt.io/browse/QTBUG-79087 QTBUG-79087] for an example python-based  development server.
Line 167: Line 184:
Qt sets TOTAL_MEMORY to 1GB by default (for -feature-thread enabled builds)
Qt sets TOTAL_MEMORY to 1GB by default (for -feature-thread enabled builds)


==== Files and local file system access ====
====Files and local file system access====


File system access is sandboxed, which has implications for how the application works with files. The Web platform provides API for accessing the local file system in a way which is under user control, as well as API for accessing persistent storage. Emscripten and Qt wraps these features and provides APIs which are easier to use from C++ and Qt-based applications.  
File system access is sandboxed, which has implications for how the application works with files. The Web platform provides API for accessing the local file system in a way which is under user control, as well as API for accessing persistent storage. Emscripten and Qt wraps these features and provides APIs which are easier to use from C++ and Qt-based applications.  


'''Web''' platform features:
'''Web''' platform features:
* <input type="file"> for showing a native open-file dialog where the user can pick a file.
 
* IndexedDB for persistent local storage (not accessible outside the browser)
*<input type="file"> for showing a native open-file dialog where the user can pick a file.
*IndexedDB for persistent local storage (not accessible outside the browser)


'''Emscripten''' provides file systems with a POSIX like [https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-memfs API]
'''Emscripten''' provides file systems with a POSIX like [https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-memfs API]
* MEMFS ephemeral file system  - files are stored in-memory
 
* IDBFS  persistent file system - files are stored using IndexedDB
*MEMFS ephemeral file system  - files are stored in-memory
*IDBFS  persistent file system - files are stored using IndexedDB
 
Emscripten mounts a MEMFS filesystem to "/" at app startup.
Emscripten mounts a MEMFS filesystem to "/" at app startup.


'''Qt''' uses Emscripten's file system and also provides other APIs:
'''Qt''' uses Emscripten's file system and also provides other APIs:
* QFile can be used as usual. Stored files go to MEMFS by default.
* QSettings has an IndexedDB-based backend; Note that QSettings is asynchronous  on WebAssembly. See usage example at [https://github.com/msorvig/qt-webassembly-examples/blob/master/gui_settings/main.cpp]
* [https://doc.qt.io/qt-5/qfiledialog.html#getOpenFileContent QFileDialog::getOpenFileContent()] opens a native file dialog where the user can pick a file
* [https://doc.qt.io/qt-5/qfiledialog.html#saveFileContent QFileDialog::saveFileContent()] saves a file to the local file system via file download


==== Clipboard Support ====
*QFile can be used as usual. Stored files go to MEMFS by default.
*QSettings has an IndexedDB-based backend; Note that QSettings is asynchronous  on WebAssembly. See usage example at [https://github.com/msorvig/qt-webassembly-examples/blob/master/gui_settings/main.cpp]
*[https://doc.qt.io/qt-5/qfiledialog.html#getOpenFileContent QFileDialog::getOpenFileContent()] opens a native file dialog where the user can pick a file
*[https://doc.qt.io/qt-5/qfiledialog.html#saveFileContent QFileDialog::saveFileContent()] saves a file to the local file system via file download
 
====Clipboard Support====
Qt supports copying and pasting text to the system clipboard
Qt supports copying and pasting text to the system clipboard
* Browsers that support the [https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API 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).
** Chrome supports the Clipboard API
** Firefox supports the Clipboard API behind a flag: dom.events.asyncClipboard.dataTransfer
* Browsers that will send clipboard events to Qt's canvas element are also supported
** This mode supports the CTRL+x/c/v keyboard shortcuts only
** Ongoing work. Firefox works well, other browsers have some hiccups.


==== Browser configuration and extensions ====
*Browsers that support the [https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API 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).
**Chrome supports the Clipboard API
**Firefox supports the Clipboard API behind a flag: dom.events.asyncClipboard.dataTransfer
*Browsers that will send clipboard events to Qt's canvas element are also supported
**This mode supports the CTRL+x/c/v keyboard shortcuts only
**Ongoing work. Firefox works well, other browsers have some hiccups.
 
====Browser configuration and extensions====
Web browsers configurable and extendible, sometimes with surprising side effects for WebAssembly-based applications:
Web browsers configurable and extendible, sometimes with surprising side effects for WebAssembly-based applications:
* JavaScript blockers may block JavaScript without enabling the NoScript. This means that <noscript> content is not displayed, and that the application appears to be stuck at the loading screen.
* Some ad-blockers block all .wasm files from github.com
* privacy.resistFingerprinting=true (FireFox) disables high-dpi support - the browser will appear to be running on a standard-dpi display.


==== General Notes ====
*JavaScript blockers may block JavaScript without enabling the NoScript. This means that <noscript> content is not displayed, and that the application appears to be stuck at the loading screen.
* Supported development host systems: Linux, MacOS, and Windows (MinGW)
*Some ad-blockers block all .wasm files from github.com
* Debugging: Qt debug and logging output is printed on the JavaScript console, which can be accessed via browser "Developer Tools" or similar.
*privacy.resistFingerprinting=true (FireFox) disables high-dpi support - the browser will appear to be running on a standard-dpi display.
* Nested event loops are not supported. Applications should not call e.g. QDialog::exec() or create a new QEventLoop object.
 
* Qt renders application content to a canvas element, and does not use (other) native DOM elements. This means accessibility (screen readers) are not supported and that text inputs won't trigger virtual keyboards.
====General Notes====
* WebGL is required, even for applications which do not use OpenGL themselves. 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.
 
* Mixing OpenGL and raster content is not supported
*Supported development host systems: Linux, MacOS, and Windows (MinGW)
** Child OpenGL windows are not supported. The window compositor (in the Qt for Wasm platform plugin) supports raster windows only.
*Debugging: Qt debug and logging output is printed on the JavaScript console, which can be accessed via browser "Developer Tools" or similar.
** QOpenGLWidget is not fully supported: https://bugreports.qt.io/browse/QTBUG-66944
*Nested event loops are not supported. Applications should not call e.g. QDialog::exec() or create a new QEventLoop object.
* To target WebAssembly version specifically in qmake, use emscripten as the platform name: emscripten { message("Building for WebAssembly") }
*Qt renders application content to a canvas element, and does not use (other) native DOM elements. This means accessibility (screen readers) are not supported and that text inputs won't trigger virtual keyboards.
* Qt will detect OpenGL support as OpenGL ES. In reality the browser will be providing WebGL. WebGL is based on ES and is very similar, but there are some incompatibilities. See [https://www.khronos.org/webgl/wiki/WebGL_and_OpenGL_Differences WebGL and OpenGL Differences]
*WebGL is required, even for applications which do not use OpenGL themselves. 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.
* Applications do not have access to system fonts. Font files must be distributed with the application, for example in Qt resources. Qt for WebAssembly itself embeds one such font.
*Mixing OpenGL and raster content is not supported
* High-DPI and scaling: High-DPI rendering is supported, and so is setting the overall UI visual size using the browser zoom feature. Browser font size (and type) settings have no effect on Qt applications.
**Child OpenGL windows are not supported. The window compositor (in the Qt for Wasm platform plugin) supports raster windows only.
* There may be artifacts of uninitialized graphics memory on some Qt Quick Controls 2 components, such as checkboxes.
**QOpenGLWidget is not supported: https://bugreports.qt.io/browse/QTBUG-66944
* Network access: The web sandbox limits network access to a subset of what is available for native apps.
*To target WebAssembly version specifically in qmake, use emscripten as the platform name: emscripten { message("Building for WebAssembly") }
** QNetworkAccessManager http requests to the web page origin server, or to a server which supports CORS.
*Qt will detect OpenGL support as OpenGL ES. In reality the browser will be providing WebGL. WebGL is based on ES and is very similar, but there are some incompatibilities. See [https://www.khronos.org/webgl/wiki/WebGL_and_OpenGL_Differences WebGL and OpenGL Differences]
** QWebScoket connections to any host.
*Applications do not have access to system fonts. Font files must be distributed with the application, for example in Qt resources. Qt for WebAssembly itself embeds one such font.
** TCP and UDP socked tunneling using over WebSockets using a websockify server [implemented by Emscripten, not tested].  
*High-DPI and scaling: High-DPI rendering is supported, and so is setting the overall UI visual size using the browser zoom feature. Browser font size (and type) settings have no effect on Qt applications.
*** [https://github.com/novnc/websockify Websockify] v0.8.0 can be used to tunnel TCP connections with QT5.12 but it is '''MANDATORY''' to specify the ''base64'' or ''binary'' subprotocols before calling ''QWebSocket::open()''. For example:
*There may be artifacts of uninitialized graphics memory on some Qt Quick Controls 2 components, such as checkboxes.
*Network access: The web sandbox limits network access to a subset of what is available for native apps.
**QNetworkAccessManager http requests to the web page origin server, or to a server which supports CORS.
**QWebSocket connections to any host.
**TCP and UDP socked tunneling using over WebSockets using a websockify server [https://github.com/novnc/websockify].  
***[https://github.com/novnc/websockify Websockify] v0.8.0 can be used to tunnel TCP connections with QT5.12 but it is '''MANDATORY''' to specify the ''base64'' or ''binary'' subprotocols before calling ''QWebSocket::open()''. For example:
<blockquote>QWebSocket socket;</blockquote>
<blockquote>QWebSocket socket;</blockquote>
<blockquote>QUrl url{QString("ws://server:port")};</blockquote>
<blockquote>QUrl url{QString("ws://server:port")};</blockquote>
Line 225: Line 249:
<blockquote>request.setRawHeader("Sec-WebSocket-Protocol", "binary");</blockquote>
<blockquote>request.setRawHeader("Sec-WebSocket-Protocol", "binary");</blockquote>
<blockquote>socket.open(request);</blockquote>
<blockquote>socket.open(request);</blockquote>
* Link-time warnings of the form: "cannot represent a NaN literal '0x7fdae4bde910' with custom bit pattern", are expected.
 
* Expected footprint (download size): Wasm modules as produced by the compiler can be large, but compress well.  
*Link-time warnings of the form: "cannot represent a NaN literal '0x7fdae4bde910' with custom bit pattern", are expected.
*Expected footprint (download size): Wasm modules as produced by the compiler can be large, but compress well.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Example !! gzip !! brotli
!Example!!gzip!!brotli
|-
|-
| helloglwindow (QtCore + QtGui) || 2.8M || 2.1M
|helloglwindow (QtCore + QtGui)||2.8M||2.1M
|-
|-
| wiggly widget (QtCore + QtGui + QtWidgets) || 4.3M || 3.2M
|wiggly widget (QtCore + QtGui + QtWidgets)||4.3M||3.2M
|-
|-
| SensorTag (QtCore + QtGui + QtWidgets + QtQuick + QtCharts) || 8.6M || 6.3M
|SensorTag (QtCore + QtGui + QtWidgets + QtQuick + QtCharts)||8.6M||6.3M
|-
|-
| Qt Quick 3D HelloCube || 6.2M || 4.5M
|Qt Quick 3D HelloCube||6.2M||4.5M
|}
|}


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.
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 Development ====
====Qt Development====
The main development tracking bug is https://bugreports.qt.io/browse/QTBUG-63917.
The main development tracking bug is https://bugreports.qt.io/browse/QTBUG-63917.
<references />

Latest revision as of 13:22, 28 May 2021

Qt for WebAssembly makes it possible to build Qt applications for the web platform.




Note: Please see the Qt documentation for instructions on how to get started with Qt for WebAssembly. This page is preserved as a historical reference.




Licensing

Qt for WebAssembly is available for commercial usage under the Qt Commercial license, and for open source usage under the GNU General Public License version 3. For more information, please check the general licensing information of Qt.

Getting Started

Qt-based applications are built for WebAssembly using the Emscripten SDK. Supported host/build platforms are Linux, macOS, and Windows Subsystem for Linux . Qt 5.13 will in addition support Windows with MinGW.

The getting started steps are:

  1. Install the Emscripten SDK
  2. Build Qt from source
  3. Build and run applications

Install the Emscripten SDK

Install Emscripten according to instructions.

Each Qt minor release supports a known-good Emscripten version. This version has been tested to work well with the given Qt minor version, and will continue to be supported for the lifetime of that Qt version. We aim to make Qt work with newer Emscripten versions as well. Older Emscripten versions are not supported.

Known-good versions
Qt Version Singlethreading Multithreading Additional info
5.12 1.38.16 NA
5.13 1.38.27 1.38.30
5.14 1.38.27 1.38.30 see "Emsdk version for Qt 5.14" below
5.15 1.39.8 tentative; 1.38.x/fasctcomp is no longer supported

Use emsdk to install specific emscripten versions (example):

  • ./emsdk install sdk-fastcomp-1.38.27-64bit or (was) sdk-1.38.16-64bit
  • ./emsdk activate --embedded sdk-fastcomp-1.38.27-64bit or (was) sdk-1.38.16-64bit

You may want to install multiple versions of the SDK, in which case the "-embedded" option is useful. It locates all configuration and cache files inside the SDK dir so that multiple versions do not conflict. The "64bit" in the SDK version refers to the host bit-ness.

Emsdk version for Qt 5.14

The Qt 5.14 binary packagers are produced with emsdk 1.38.27: make sure to use that version when using the binary package.

Starting with emsdk 1.39.0, the emcc compiler no longer compiles via asm.js, but instead generates wasm bytecode directly. Support for the 1.39.x series is in scope for Qt 5.14. However, be aware that the build flags are still tailored for the previous compiler, where minimizing the size of the intermediate asm.js was important.

Build Qt from source

The Qt sources can be downloaded from your Qt Account, in the Downloads section. For the latest revision of the code, you can also check it out from our git repositories directly: http://code.qt.io/cgit/qt/qt5.git/

Configure Qt as a cross-compile build for the "wasm-emscripten" platform. This will implicitly set the "-static" and "-no-feature-thread" options. The Qt examples are not built by default in order to minimize build size and time. Pass the "-compile-examples" option to enable examples.

./configure -xplatform wasm-emscripten -nomake examples -prefix $PWD/qtbase

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

configure -no-warnings-are-errors -xplatform wasm-emscripten -platform win32-g++ -nomake examples -prefix %CD%\qtbase

Build required modules:

make module-qtbase module-qtdeclarative [other modules]

Build and run applications

We support the qmake build system. Run qmake from the Qt for WebAssembly build in the directory which contains the applications .pro file:

/path/to/qtbase/bin/qmake && make

The build process will produce several files: (with "appname" substituted for the actual application name)

Name Description
appname.wasm Main application binary
appname.js Emscripten JavaScript runtime
appname.html Html container
qtloader.js Qt JavaScript runtime

Run the application by loading the appname.html file in a web browser. The files must be served by a web server using http(s). Start a web server (e.g. "python3 -m http.server"), open e.g. localhost:8000/app.html in a web browser. We test on Chrome, Firefox, and Safari (all desktop). Wasm compiling and loading performance wary between the browsers; test several and find one which works for you.

You can also use:

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

Debug and logging output go to the browser's debug console. If you are using Firefox, you can use CTRL+SHIFT+K to open the debug console.

Platform Notes

The Qt for WebAssembly platform port has limitations; these are due to the sandboxed nature of the web platform, the platform APIs provided (or not provided), and the incomplete nature of the Qt port. This section describes several topics which may be of interest for application developers.

Supported target browsers/devices

Desktop:

  • Chrome
  • Firefox
  • Safari
  • Edge (Chrome)

If the browser supports WebAssembly then Qt should run. Note that Qt has fixed WebGL requirement, also for apps that do not use WebGL directly. Browsers often blacklist WebGL for older/unsupported GPUs.

Mobile:

  • Android Browser
  • Mobile Safari

Note: There is currently no support for text input using the virtual keyboard. Safari currently does not support wasm modules of the size Qt produces.

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

Supported Qt Modules

Qt for WebAssembly supports a subset of the Qt modules. The currently supported modules are

  • qtbase
  • qtdeclarative
  • qtquickcontrols2
  • qtwebsockets
  • qtsvg
  • qtcharts
  • qtmqtt

Unsupported:

  • qtmultimedia
  • qtwebview

Other modules are not tested and may or may not work.

Multithreading Support

Qt on WebAssembly supports multithreading, however support is disabled by default in order to be compatible with as many browsers as possible. Thread support can be enabled by building Qt from source and configuring with the "-feature-thread" flag. The WebAssembly binary packages do not support multithreading.

The minimum Emscripten SDK version is 1.38.30. The Emscripten pthreads documentation contains relevant documentation for multithreading.

Threads are supported in some (but not all) browsers. Configuration changes may be required. The [1] demo can be used to determine if thread support is available. Note that it is the build mode which determines if browser thread support is required, not whether the application starts a thread or not.

Current Browser Status:

  • Chrome (and derivatives): supported
  • Safari: not supported
  • Firefox: supported since 79[1]

In Firefox versions before 79, open about:config and make sure the following option is enabled:

  • javascript.options.shared_memory = true

Thread support will only be enabled provided that that the web server sets two additional headers:

  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp

(These are the COOP and COEP headers, respectively)

Mozilla bug 1619649 tracks the Firefox defaults change. In the mean time, its possible to manually bypass or enable the header check:

FireFox Nightly or Beta - bypass header check:

  • dom.postMessage.sharedArrayBuffer.bypassCOOP_COEP.insecure.enabled = true

FireFox Release - enable header check:

  • browser.tabs.remote.useCrossOriginEmbedderPolicy = true
  • browser.tabs.remote.useCrossOriginOpenerPolicy = true

After enabling the header check, make sure your web server sets the required headers. See QTBUG-79087 for an example python-based development server.

Build Settings: Applications may need to add two settings to its .pro file when enabling threads:

Thread Pool Size Applications should set the expected number of concurrent threads at build time. This can be done by setting QMAKE_WASM_PTHREAD_POOL_SIZE in the .pro file (maps to Emscripten PTHREAD_POOL_SIZE). Applications can exceed PTHREAD_POOL_SIZE, provided they return main thread control to the browser before waiting on the new thread, for example by returning from the event handler that started the new thread. This allows the browser to start another web worker. Immediately waiting for the new thread on the main thread (using QThread::wait() or similar) will deadlock. Qt sets PTHREAD_POOL_SIZE to 4 by default.

Heap Memory Size Applications should set the heap memory size at build time, since growing the heap is not supported with pthreads enabled. This can be be done by setting QMAKE_WASM_TOTAL_MEMORY in the .pro file (maps to Emscripten TOTAL_MEMORY). Browsers typically limit the initial WASM memory allocation size to 1GB. Qt sets TOTAL_MEMORY to 1GB by default (for -feature-thread enabled builds)

Files and local file system access

File system access is sandboxed, which has implications for how the application works with files. The Web platform provides API for accessing the local file system in a way which is under user control, as well as API for accessing persistent storage. Emscripten and Qt wraps these features and provides APIs which are easier to use from C++ and Qt-based applications.

Web platform features:

  • <input type="file"> for showing a native open-file dialog where the user can pick a file.
  • IndexedDB for persistent local storage (not accessible outside the browser)

Emscripten provides file systems with a POSIX like API

  • MEMFS ephemeral file system - files are stored in-memory
  • IDBFS persistent file system - files are stored using IndexedDB

Emscripten mounts a MEMFS filesystem to "/" at app startup.

Qt uses Emscripten's file system and also provides other APIs:

  • QFile can be used as usual. Stored files go to MEMFS by default.
  • QSettings has an IndexedDB-based backend; Note that QSettings is asynchronous on WebAssembly. See usage example at [2]
  • QFileDialog::getOpenFileContent() opens a native file dialog where the user can pick a file
  • QFileDialog::saveFileContent() saves a file to the local file system via file download

Clipboard Support

Qt supports copying and pasting text to the system clipboard

  • 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).
    • Chrome supports the Clipboard API
    • Firefox supports the Clipboard API behind a flag: dom.events.asyncClipboard.dataTransfer
  • Browsers that will send clipboard events to Qt's canvas element are also supported
    • This mode supports the CTRL+x/c/v keyboard shortcuts only
    • Ongoing work. Firefox works well, other browsers have some hiccups.

Browser configuration and extensions

Web browsers configurable and extendible, sometimes with surprising side effects for WebAssembly-based applications:

  • JavaScript blockers may block JavaScript without enabling the NoScript. This means that <noscript> content is not displayed, and that the application appears to be stuck at the loading screen.
  • Some ad-blockers block all .wasm files from github.com
  • privacy.resistFingerprinting=true (FireFox) disables high-dpi support - the browser will appear to be running on a standard-dpi display.

General Notes

  • Supported development host systems: Linux, MacOS, and Windows (MinGW)
  • Debugging: Qt debug and logging output is printed on the JavaScript console, which can be accessed via browser "Developer Tools" or similar.
  • Nested event loops are not supported. Applications should not call e.g. QDialog::exec() or create a new QEventLoop object.
  • Qt renders application content to a canvas element, and does not use (other) native DOM elements. This means accessibility (screen readers) are not supported and that text inputs won't trigger virtual keyboards.
  • WebGL is required, even for applications which do not use OpenGL themselves. 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.
  • Mixing OpenGL and raster content is not supported
  • To target WebAssembly version specifically in qmake, use emscripten as the platform name: emscripten { message("Building for WebAssembly") }
  • Qt will detect OpenGL support as OpenGL ES. In reality the browser will be providing WebGL. WebGL is based on ES and is very similar, but there are some incompatibilities. See WebGL and OpenGL Differences
  • Applications do not have access to system fonts. Font files must be distributed with the application, for example in Qt resources. Qt for WebAssembly itself embeds one such font.
  • High-DPI and scaling: High-DPI rendering is supported, and so is setting the overall UI visual size using the browser zoom feature. Browser font size (and type) settings have no effect on Qt applications.
  • There may be artifacts of uninitialized graphics memory on some Qt Quick Controls 2 components, such as checkboxes.
  • Network access: The web sandbox limits network access to a subset of what is available for native apps.
    • QNetworkAccessManager http requests to the web page origin server, or to a server which supports CORS.
    • QWebSocket connections to any host.
    • TCP and UDP socked tunneling using over WebSockets using a websockify server [3].
      • Websockify v0.8.0 can be used to tunnel TCP connections with QT5.12 but it is MANDATORY to specify the base64 or binary subprotocols before calling QWebSocket::open(). For example:

QWebSocket socket;

QUrl url{QString("ws://server:port")};

QNetworkRequest request{url};

request.setRawHeader("Sec-WebSocket-Protocol", "binary");

socket.open(request);

  • Link-time warnings of the form: "cannot represent a NaN literal '0x7fdae4bde910' with custom bit pattern", are expected.
  • Expected footprint (download size): Wasm modules as produced by the compiler can be large, but compress well.
Example 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
Qt Quick 3D HelloCube 6.2M 4.5M

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 Development

The main development tracking bug is https://bugreports.qt.io/browse/QTBUG-63917.