Beyond Linux® From Scratch (System V Edition) - Version 12.1

Chapter 25. Graphical Environment Libraries

QtWebEngine-5.15.17

Introduction to QtWebEngine

QtWebEngine integrates chromium's web capabilities into Qt. It ships with its own copy of ninja which it uses for the build if it cannot find a system copy, and various copies of libraries from ffmpeg, icu, libvpx, and zlib (including libminizip) which have been forked by the chromium developers.

This package and browsers using it may be useful if you need to use a website designed for google chrome, or chromium, browsers.

[Important]

Important

Qt-5.15 reached End Of Life on 26 May 2023. Extended lifetime Qt5.15 LTS has been extended until 26th May 2025 for those with subscription licenses. Because qtwebengine uses chromium code under the LGPL, it appears that any new backported CVE fixes for QtWebEngine will be available after Qt makes public releases of its current versions.

[Warning]

Warning

QtWebEngine uses a forked copy of chromium, and is therefore vulnerable to many issues found there. The Qt developers have always preferred to make releases at the same time as the rest of Qt (rather than adding emergency fixes), but with stable versions getting released after the current development version. Now that they are keen to move to Qt6, the 5.15.3 and later Qt-5.15 releases are initially only available to paying customers. QtWebEngine is something of an exception because of its LGPL licence, but getting the git sources (with the forked chromium submodule) to a position where they will successfully build on a current BLFS system can take a lot of effort and therefore updates to the book may be delayed.

It seems likely that future 5.15-series versions will also be released long after the chromium vulnerabilities are known, but fixes for QtWebEngine can be found in git and the editors take the view that known vulnerabilities in browsers should be fixed.

The tarball linked to below was created from the 5.15 git branch and the 87-branch of the chromium submodule (which is forked from chromium). See the GIT-VERSIONS file in the tarball for details of the latest commits.

This package is known to build and work properly using an LFS 12.1 platform.

[Warning]

Warning

By default, ninja will use all online CPUs +2 (if at least 4 exist), even if they are not available to the current task because the build terminal has been restricted with 'taskset'. In BLFS, this package takes more time to build than any other. In one example, the build of this package crashed at about the 90 percent point due to an out of memory problem on a system with 24 cores and 32 GB of memory.

To work around this, see the Command Explanations below.

[Note]

Note

If you are upgrading and have installed a newer version of ICU-74.2 since you last installed Qt-5.15.12, you will need to reinstall Qt5 before upgrading, otherwise the final link of this package will fail with a warning that the version of icu libraries needed by libQt5Core.so may conflict with the version used for this package.

Unusually, the shipped GN build system (used to create the Ninja files) requires a static libstdc++.a although the installed libraries correctly use the shared version. If that static library is not present, the build will fail quite quickly. Please note that if you try to build webengine as part of Qt and the static library is not available, that build will either complete without installing webengine, or else fail during the install (both variants were observed in 5.12.0).

Package Information

Additional Downloads

qtwebengine Dependencies

Required

nodejs-20.11.1, nss-3.98, pciutils-3.10.0, Python-3.11.1, and (Qt-5.15.12 or qt-components-5.15.12 with qtlocation and qtwebchannel)

Recommended

[Note]

Note

If these packages are not installed, the build process will compile and install its own (perhaps older) version, with the side effect of increasing build and installed disk space and build time.

either alsa-lib-1.2.11 or PulseAudio-17.0 (or both), FFmpeg-6.1.1, ICU-74.2, libwebp-1.3.2, libxslt-1.1.39, and Opus-1.4

Optional

libevent-2.1.12, MIT Kerberos V5-1.21.2, pipewire-1.0.3, Poppler-24.02.0, jsoncpp, libsrtp, snappy

Installation of qtwebengine

Apply a patch to fix several issues that can prevent the build from completing, and to force it to use python3: 

patch -Np1 -i ../qtwebengine-5.15.17-build_fixes-2.patch

If building with system FFmpeg-6.1.1 as the editors recommend, apply a patch that resolves problems when building with ffmpeg-5 and later: 

patch -Np1 -i ../qtwebengine-5.15.17-ffmpeg5_fixes-1.patch

Although the build_fixes patch has ensured that git is not invoked during the build, the build system has labyrinthine rules of byzantine complexity, and in particular trying to build without two .git directories will lead to it eventually falling into unexpected and unbuildable code which references a private header that has not been created. Avoid this by creating the required directories: 

mkdir -pv .git src/3rdparty/chromium/.git

Because this version of qtwebengine is aimed at a later release than the current public releases, change it to build for qt-5.15.12 using a sed: 

sed -e '/^MODULE_VERSION/s/5.*/5.15.12/' -i .qmake.conf

Now, ensure that the local headers are available when not building as part of the complete Qt-5.15.12: 

find -type f -name "*.pr[io]" |
  xargs sed -i -e 's|INCLUDEPATH += |&$$QTWEBENGINE_ROOT/include |'

Next, allow the pulseaudio library to be linked at build time, instead of run time. This also prevents an issue with newer pulseaudio: 

sed -e '/link_pulseaudio/s/false/true/' \
    -i src/3rdparty/chromium/media/media_options.gni

Next, fix a build failure that occurs when libxml2-2.12.0 or later is installed: 

sed -e 's/xmlError/const xmlError/' \
-i src/3rdparty/chromium/third_party/blink/renderer/core/xml/xslt_processor.h \
-i src/3rdparty/chromium/third_party/blink/renderer/core/xml/xslt_processor_libxslt.cc

Install qtwebengine by running the following commands: 

mkdir build &&
cd    build &&
PATH=/opt/python3.11/bin:$PATH qmake .. --                  \
                                        -system-ffmpeg      \
                                        -proprietary-codecs \
                                        -webengine-icu      &&
make

This package does not come with a test suite.

Now, as the root user: 

make install

Remove references to the build directory from installed library dependency (prl) files by running the following commands as the root user: 

find $QT5DIR/ -name \*.prl \
   -exec sed -i -e '/^QMAKE_PRL_BUILD_DIR/d' {} \;

Command Explanations

PATH=/opt/python3.11/bin:$PATH: This switch forces this package to use the version of Python 3.11 that is installed in /opt. This is done to reduce the chances for problems that may occur during the build, and to simplify the instructions since this package is incompatible with Python 3.12 without additional modifications.

qmake: This will build the included copy of ninja if it is not already installed and use it to configure the build.

-- -system-ffmpeg -proprietary-codecs -webengine-icu: If any options are passed to qmake they must come after '--' which must follow '..' that points to the main directory. The options here cause it to use system ffmpeg and system icu. The '-proprietary-codecs' option allows ffmpeg to decode H264 and H265 codecs. If built as part of full Qt5, the system icu is automatically used (only) by Qt5Core if it is available, but unless this option is used webengine will always use its shipped copy of icu, adding time and space to the build. Remove the -system-ffmpeg switch if you don't have FFmpeg-6.1.1 installed and want to build this package with an internal copy of ffmpeg.

-webengine-jumbo-build 0: If this is added to the qmake command it will cause the 'Jumbo Build Merge Limit' to be reported as 'no' instead of 8. That turns off the jumbo build. Some distros do that to get a smaller build on some architectures such as MIPS. On x86_64 it might save a little space in the build, but the build time will increase by a very large amount.

-webengine-kerberos: Add this if you have installed MIT Kerberos V5-1.21.2 and wish to connect from a browser using QtWebEngine to a webserver which requires you to connect via kerberos.

NINJAJOBS=4 make: If you patched system ninja in LFS to recognize the NINJAJOBS environment variable, this command will run system ninja with the specified number of jobs (i.e. 4). There are several reasons why you might want to use options like this this:

  • Building on a subset of CPUs allows measuring the build time for a smaller number of processors, and/or running other CPU-intensive tasks at the same time. For an editor on a machine with a lot of CPUs, trying to measure the build time for a 4-CPU machine, NINJAJOBS=4 make will give a reasonable approximation (there is a short period where N+2 python and node jobs run).

  • On a machine with only 4 CPUs online, the default of scheduling N+2 jobs for qtwebengine is slower by between 3% and 7%, probably because of the size of the C++ files and their many includes and templates. Therefore, if in doubt set NINJAJOBS to the number of CPUs.

  • Reducing the number of cores being used on long running, CPU intensive packages may alleviate heat problems.

  • Reducing the number of cores will prevent potential out-of-memory problems on systems that do not have enough memory (or swap) when all cores are active. A suggested approach is to limit the number of cores to about one core for each 1.5 GB of combined RAM and swap space.

Configuring QtWebEngine

Configuration Information

If you are upgrading from an older minor version of this application, for some webpages to load you may need to clear the browser caches, e.g. for falkon they will be found in ~/.cache/falkon/. You will need to do this if the browser starts to render the page and then changes to a blank tab with a message that something went wrong, and a button to Retry. Even after removing the old caches, you may need to retry a few times for each affected tab.

If a browser using this package fails to run and when run from a term it reports 'Trace/breakpoint trap' that is probably a kernel configuration issue - there is no need to rebuild QtWebEngine, see the next section, recompile the kernel and reboot to the new kernel.

Kernel Configuration

This package does not require any of the optional kernel namespace items, but if User namespace is enabled PID namespace must also be enabled. In that case enable the following options in the kernel configuration and recompile the kernel if necessary: 

General setup --->
  -*- Namespaces support --->                                       [NAMESPACES]
    # Enable or disable *both* of them:
    [ /*] User namespace                                               [USER_NS]
    [ /*] PID Namespaces                                                [PID_NS]

Contents

Installed Programs: qtwebengine_convert_dict and QtWebEngineProcess (in $QT5DIR/libexec)
Installed Libraries: libQt5Pdf.so, libQt5PdfWidgets.so, libQt5WebEngineCore.so, libQt5WebEngine.so, and libQt5WebEngineWidgets.so
Installed Directories: $QT5DIR/include/QtPdf, $QT5DIR/include/QtPdfWidgets, $QT5DIR/include/QtWebEngine, $QT5DIR/include/QtWebEngineCore, $QT5DIR/include/QtWebEngineWidgets, $QT5DIR/qml/QtWebEngine, and $QT5DIR/translations/qtwebengine_locales

Short Descriptions

qtwebengine_convert_dict

converts hunspell dictionaries (.dic) to chromium format (.bdic)

QtWebEngineProcess

is a libexec program which runs a zygote process (one that listens for spawn requests from a master process and will fork itself in response)

libQtWebEngine.so

provides QML types for rendering web content within a QML application

libQtWebEngineCore.so

provides public API shared by both QtWebEngine and QtWebEngineWidgets

libQtWebEngineWidgets.so

provides a web browser engine as well as C++ classes to render and interact with web content