Qt WebEngine Platform Notes | Qt WebEngine | Qt 6.10.2
Description: Contains information about issues that are specific to the Qt WebEngine module.

- Qt 6.10
- Qt WebEngine
- Qt WebEngine Platform Notes
- Qt 6.10.2 Reference Documentation

Features ◦ Qt WebEngine Core

# Qt WebEngine Platform Notes

## 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
- Windows
- Linux
- macOS

### All Platforms

Note: Qt WebEngine requires a C++20-compatible compiler on all platforms, due to its dependency on the Chromium project. While Qt as a whole only requires C++17, Qt WebEngine is an exception.

On all platforms, the following tools are required at build time:

- C++20 compiler support
- CMake version at least 3.19 or higher.
- 64-bit Nodejs 14.9 version or later.
- Python 3.8 version or later.
- Ninja version 3.8 or later.
- Python3 html5lib module.
- GNU gperf binary.
- GNU bison binary.
- GNU flex binary.

### Windows

On Windows, the following additional tools are required:

- Visual Studio 2019 or higher.
- Visual Studio compiler version at least 14.29 if compiled with Visual Studio 2019
- Visual Studio compiler version at least 14.36 if compiled with Visual Studio 2022
- Windows 11 SDK at least version 10.0.26100.0

Note: It is not recommended to use tools from `msys2` or `cygwin` to build Qt WebEngine as it may result in build errors.

Note: Currently, Qt WebEngine does not compile with MinGW.

### Linux

On Linux, the following additional tools are required:

- A pkg-config binary.
- Glibc library at least 2.16 version or later.
- Mesa development headers.
- Nss library is at least 3.26 version.
- Gcc version must be at least 10.0 to compile QtWebEngine.
- Clang version must be at least 17.0 to compile QtWebEngine.
- Glib library version 2.32.0 or later. (optional, built-in used otherwise)
- Harfbuzz library version 4.3.0 or later. (optional, built-in used otherwise)
- Libudev library version or later. (optional, built-in used otherwise)
- Libpng library version 1.6.0 or later. (optional, built-in used otherwise)
- Libtiff library version 4.5.0 or later. (optional, built-in used otherwise)
- Re2 library version 11.0.0 or later. (optional, built-in used otherwise)
- Icu library version 70 or later. (optional, built-in used otherwise)
- Opus library version 1.3.1 or later. (optional, built-in used otherwise)
- Vpx library version 1.10.0 or later. (optional, built-in used otherwise)
- Libavutil library version 58.29.100 or later. (optional, built-in used otherwise)
- Libavcodec library version 60.31.102 or later. (optional, built-in used otherwise)
- Libavformat library version 60.16.100 or later. (optional, built-in used otherwise)
- Openh264 library version 2.4.1 or later. (optional, built-in used otherwise)

Qt WebEngine requires `pkg-config` to detect most of its dependencies. The following `pkg-config` files are required:

- Fontconfig
- Dbus

If Qt was configured for `xcb`, the following `pkg-config` files are also required:

- x11
- libdrm
- xcomposite
- xcursor
- xrandr
- xi
- xproto
- xshmfence
- xtst
- xkbcommon
- xkbfile
- xcbdri3

### 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:

1. Download the qtwebengine sources.
2. From the earlier Qt version, run

        ../qtbase/bin/qt-configure-module .
        cmake --build . --parallel
        cmake --install .

Note: You may also use `qmake` with `make` and `make` install, but this method is considered legacy and not recommended for Qt 6 and later.

## 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.

On some old Linux configurations, accessibility can cause a significant slowdown on large HTML pages.

Because of that, Qt WebEngine accessibility support can be disabled on Linux, by setting the `QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY` environment variable to 0.

## 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.

## Windows Application Manifest

A manifest is an XML file that is read when the program starts and informs Windows how to run the program. Some Qt WebEngine features may require adding a manifest file for the user application to work correctly on Windows.

The following snippets show the manifest file's structure and how to embed it into the program.

Note: These code snippets are taken from the WebEngine Quick Nano Browser example.

The manifest file defines which Windows versions the application supports. httpUserAgent needs this information to report the correct Windows version.

     <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
     <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
         <application>
         <!--The ID below indicates application support for Windows Vista -->
         <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>
         <!--The ID below indicates application support for Windows 7 -->
         <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
         <!--The ID below indicates application support for Windows 8 -->
         <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
         <!--The ID below indicates application support for Windows 8.1 -->
         <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
         <!--The ID below indicates application support for Windows 10/11 -->
         <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
         </application>
     </compatibility>
     </assembly>

To embed the file into the executable, add it to the sources:

         ...
     qt_add_executable(quicknanobrowser
         main.cpp
     )

     if(WIN32)
         set_property(
             TARGET quicknanobrowser
             APPEND PROPERTY
                 SOURCES quicknanobrowser.exe.manifest)
     endif()
         ...

For more information, see the Application manifest documentation page.

Features ◦ Qt WebEngine Core