Qt WebEngine Platform Notes#
Contains information about issues that are specific to the Qt WebEngine module.
Building Qt WebEngine from Source#
Static builds are not supported.
The requirements for building Qt modules from source are listed separately for each supported platform:
Qt for Windows - Building from Source
Qt for X11 Requirements
Qt for macOS - Building from Source
In addition, the following tools are required for building the Qt WebEngine module:
All Platforms#
On all platforms, the following tools are required at build time:
CMake 3.19 or newer
Python 3 with html5lib library
Bison, Flex
GPerf
Node.js version 12 or later
Windows#
On Windows, the following additional tools are required:
Visual Studio 2019 or later, or clang-cl version 10 or later
Active Template Library (ATL), usually included in the Visual Studio installation
Windows 10 SDK version 10.0.20348.0 or later
Qt WebEngine can only be built on 64-bit Windows, with a x64-bit toolchain. For building Qt WebEngine for x86 applications, you need to configure and compile Qt with the Visual Studio x64 to x86 cross-compile toolchain. This toolchain can be set up on the command line by running vcvarsall.bat amd64_x86
.
Note
It is not recommended to use tools form msys2
or cygwin
to build Qt WebEngine as it may result in build errors.
Linux#
On Linux, Clang or GCC version 9 or later is required.
Qt WebEngine requires pkg-config
to detect most of its dependencies. The following pkg-config
files are required:
dbus-1
fontconfig
If Qt was configured for xcb
, the following pkg-config
files are also required:
libdrm
xcomposite
xcursor
xi
xrandr
xscrnsaver
xtst
macOS#
On macOS, the following are required:
macOS 10.14 or later
Xcode 12.0 or later
macOS 11 SDK or later
Note
Qt WebEngine cannot be built for the 32-bit mode of macOS (using the macx-clang-32
mkspec
).
Using Earlier Qt Versions to Build Qt WebEngine#
Building Qt WebEngine with earlier Qt versions (down to the last LTS version) is supported. It means that Qt WebEngine 6.4 can be built with Qt 6.2.x, Qt 6.3.x, and Qt 6.4.
To use an earlier Qt version to build Qt Webengine:
Download the qtwebengine sources.
From the earlier Qt version, run
qmake && make (&& make install)
.
Mac App Store Compatibility#
Applications using Qt WebEngine are not compatible with the Mac App Store, because:
The Chromium part of the code uses several private API methods, which are prohibited by the App Store.
Applications submitted to the App Store must be code-signed with the App Sandbox feature enabled. The App Sandbox feature interferes with Chromium’s own sandbox initialization, which results in Chromium not being properly initialized. This also ties in with the private API usage. Furthermore, standalone Chromium itself is not officially tested with the App Sandbox enabled, and even if work is done to bypass the App Store’s restrictions, that would not guarantee correct behavior of the library.
macOS Airplay Support on MacBooks with Dual GPUs#
To make Qt WebEngine work correctly when streaming to an AppleTV from a MacBook that supports GPU switching, it is important to add the NSSupportsAutomaticGraphicsSwitching
option to the application Info.plist file, with the value set to YES
. Otherwise rendering issues might occur when creating new web engine view instances after Airplay is switched on or off.
Default QSurfaceFormat OpenGL Profile Support#
If a new default QSurfaceFormat
with a modified OpenGL profile has to be set, it should be set before the application instance is declared, to make sure that all created OpenGL contexts use the same OpenGL profile.
On macOS, if the default QSurfaceFormat
is set after the application instance, the application will exit with qFatal()
, and print a message that the default QSurfaceFormat
should be set before the application instance.
Sandboxing Support#
Qt WebEngine provides out-of-the-box sandboxing support for Chromium render processes.
On Linux, note the following restrictions:
The kernel has to support the anonymous namespaces feature (kernel version 3.8 or later). However, on Debian, Ubuntu, and other Debian-derived distributions, this feature is off by default. It can be turned on by setting
/proc/sys/kernel/unprivileged_userns_clone
to 1.The kernel has to support the
seccomp-bpf
feature (kernel version 3.5 or later).Setuid sandboxes are not supported and are thus disabled.
To explicitly disable sandboxing, use one of the following options:
Set the
QTWEBENGINE_DISABLE_SANDBOX
environment variable to 1.Pass the
--no-sandbox
command line argument to the user application executable.Set
QTWEBENGINE_CHROMIUM_FLAGS
to--no-sandbox
.
For more information, see Using Command-Line Arguments .
Memory Requirements in Docker Environment#
When running Qt Web Engine examples in a Docker container and browsing content-heavy sites, BUS errors (SIGBUS) might be reported. Typically, this is caused by Docker running a container with a too small memory space (such as 64MB). To fix this problem, increase the memory space size.
Accessibility and Performance#
Qt WebEngine enables accessibility support for web pages when the following conditions are met:
Qt Core is configured and built with accessibility support enabled.
The QPA plugin is notified by the operating system that accessibility should be activated. This happens for example when using a screen reader application on Windows or VoiceOver on macOS.
Due to some limitations, the Linux QPA plugin almost always reports that accessibility should be activated. On big HTML pages, this can cause a significant slowdown in rendering speed.
Because of that, Qt WebEngine accessibility support is disabled by default on Linux. It can be re-enabled by setting the QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY
environment variable to a non-empty value.
Popups in Fullscreen Applications on Windows#
Because of a limitation in the Windows compositor, applications that show a fullscreen web engine view will not properly display popups or other top-level windows. The reason and workaround is described in Fullscreen OpenGL Based Windows .