source: x/lib/qtwebengine.xml@ 4eb513e

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY qtwebengine-major "5.15">
<!-- URL if there is a public release
  <!ENTITY qtwebengine-download-http "https://download.qt.io/archive/qt/&qtwebengine-major;/&qtwebengine-version;/submodules/qtwebengine-everywhere-src-&qtwebengine-version;.tar.xz">
     URL for a prepared git version -->
  <!ENTITY qtwebengine-download-http "&sources-anduin-http;/qtwebengine/qtwebengine-&qtwebengine-version;.tar.xz">
  <!ENTITY qtwebengine-download-ftp  " ">
  <!ENTITY qtwebengine-md5sum        "838d5d4ef9d1e5b82a41bff6f830e4a4">
  <!ENTITY qtwebengine-size          "306 MB">
  <!ENTITY qtwebengine-buildsize     "4.4 GB (154 MB installed)">               
  <!ENTITY qtwebengine-time          "64 SBU (Using parallelism=4)">            
]>

<sect1 id="qtwebengine" xreflabel="qtwebengine-&qtwebengine-version;">
  <?dbhtml filename="qtwebengine.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>QtWebEngine-&qtwebengine-version;</title>

  <indexterm zone="qtwebengine">
    <primary sortas="a-qtwebengine">qtwebengine</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to QtWebEngine</title>

    <para>
      <application>QtWebEngine</application> integrates
      <application>chromium</application>'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
      <application>chromium</application> developers.
    </para>

    <!-- Note for editors re switching between git versions and releases:
      If a public release of Qt 5.15.3 (or later) appears in a meaningful
      time frame, please keep the notes re the git build, as comments, so
      that updating for later fixes will be easier: in the past, updates
      of 'stable' versions (i.e. 5.12 when 5.14, 5.15 were the newest)
      happened much later than updates to the newest version (now Qt6)
      and it seems likely we might again need to use a git version to fix
      future chromium vulnerabilities. -->

    <warning>
      <para>
        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.
      </para>

      <para>
        It seems likely that future 5.15-series versions will also be released
        long after the chromium vulnerabilities are known.
      </para>

      <para> <!-- for git versions -->
        The tarball linked to above was created from the 5.15 git branch
        at https://code.qt.io/cgit/qt/qtwebengine.git commit 029771bcd254
        just before the version there was rolled on for 5.15.4,
        <!-- the DTS doesn't let me put a url in a para -->
        <!--ulink url="https://code.qt.io/cgit/qt/qtwebengine.git/commit/?h=5.15&amp;id=029771bcd254"/>code.qt.io/cgit/qt/qtwebengine.git</ulink>-->
        with the chromium submodule using the 87-branch at revision 7c8217b36a95.
      </para>
    </warning>

    <!-- note for editors on obtaining webengine from git.
      First (if you do not already have a past version)
      git clone git://code.qt.io/qt/qtwebengine.git
      git submodule init -
       that will report qtwebengine-chromium.git registered for src/3rdparty
       now find the main branch names:
      git fetch origin
      git branch -r
       after a release is prepared (even if the rest is not public), the 5.15
       branch is probably what you want
      git checkout origin/5.15
       Confirm that HEAD is where you expected.
       Now go to src/3rdparty
      git fetch origin
      git branch -r
       The required branch is likely to be 87-branch unless there is a newer one
      git checkout origin/87-branch (or whatever)
       Use git log or git tk to look at its HEAD and check it seems appropriate.

      Now create tarballs - 'git archive' does not work across submodule boundaries,
      so you need to create one archive from the top of qtwebengine/ and another
      from the top of src/3rdparty (chromium, gn, ninja are apparently all part of
      the qtwebengine-chromium module).  Then in a work area untar the qtwebengine
      tarball, go down to src/3rdparty and untar the submodule tarball.
      Decide on what to call the result and create a full xz tarball using tar -cJf.
     -->

    &lfs101_checked;

    <note>
      <para>
        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'.  To work around this, see
        the Command Explanations below.
      </para>

      <para>
        Unusually, the shipped GN build system (used to create the Ninja files)
        requires a static <filename class="libraryfile">libstdc++.a</filename>
        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
        <application>Qt</application> and the static library is not available,
        that build will either complete without installing webengine, or else
        fail during the install (both variants have been observed in 5.12.0).
      </para>
    </note>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&qtwebengine-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&qtwebengine-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &qtwebengine-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &qtwebengine-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &qtwebengine-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &qtwebengine-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <!-- keep links for releases and git versions as a reminder
               that the tarball names names differ -->
          <ulink url="&patch-root;/qtwebengine-everywhere-src-&qtwebengine-version;-ICU68-2.patch"/>
          <ulink url="&patch-root;/qtwebengine-&qtwebengine-version;-build_fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">qtwebengine Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
      <!-- the qmake output tends to be misleading. 'khr' is from Mesa -->
    <para role="required">
      <xref linkend="node"/>,
      <xref linkend="nss"/>,
      <xref linkend="python2"/>, and
      <xref linkend='qt5'/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <note>
      <para>
        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.
      </para>
    </note>

    <para role="recommended">
      either <xref linkend="alsa-lib"/> or
      <xref linkend="pulseaudio"/> (or both),
      <xref linkend="ffmpeg"/>,
      <xref linkend="icu"/>,
      <xref linkend="libwebp"/>,
      <xref linkend="libxslt"/>, and
      <xref linkend="opus"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="libevent"/>,
      <xref linkend="poppler"/>,
      <ulink url="https://github.com/open-source-parsers/jsoncpp/releases">jsoncpp</ulink>,
      <ulink url="https://github.com/cisco/libsrtp/releases">libsrtp</ulink>,
      <ulink url="http://google.github.io/snappy/">snappy</ulink>
    </para>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/qtwebengine"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of qtwebengine</title>

    <note>
      <para>
        Unlike version 5.15.2, the chromium-derived build system now needs
        <command>python</command> to be available and to be python2. In
        BLFS-10.1 the creation of the python symlink was removed as a step
        towards eventually getting rid of python2 (other old packages which
        need python2 usually work by invoking python2). If you are still
        using an earlier version of BLFS where
        <filename>/usr/bin/python</filename> exists, you can skip the
        commands to create the symlink, and to later remove it.
      </para>
    </note>

    <para>
      First, as the <systemitem class="username">root</systemitem>
      user, create the python symlink:
    </para>

<screen role="root"><userinput>ln -svf /usr/bin/python{2,}</userinput></screen>

    <para>
      Now apply a patch to fix several issues that can prevent the build working:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../qtwebengine-&qtwebengine-version;-build_fixes-1.patch</userinput></screen>

<!-- start of commands for git versions only -->
    <para>
      Although the 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 <filename>.git</filename> 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:
    </para>

<screen><userinput>mkdir -pv .git src/3rdparty/chromium/.git</userinput></screen>

    <para>
      Because this version of qtwebengine is aimed at a later release than the
      current public releases, change it to build for qt-&qt5-version; using a
      sed:
    </para>

<screen><userinput>sed -e '/^MODULE_VERSION/s/5.*/&qt5-version;/' -i .qmake.conf</userinput></screen>
<!-- end of commands for git versions only -->

    <para>
      Now, ensure that the local headers are available when not building as
      part of the complete <xref linkend="qt5"/>:
    </para>

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

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

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

    <para>
      Finally, fix a change in the build system which allows its developers to
      pass e.g. -j20 to make (for quick tests of some areas) but breaks the
      build with LFS's use of the NINJAJOBS environment variable:
    </para>

<!-- editors: See thread at
http://lists.linuxfromscratch.org/pipermail/blfs-dev/2019-December/036996.html
et.seq, particularly 037002.html which shows the commit near the end. -->

<screen><userinput>sed -i 's/NINJAJOBS/NINJA_JOBS/' src/core/gn_run.pro</userinput></screen>

    <para>
      If an older version of the package's main library has been installed,
      when the package is built separately it will link to that in preference
      to its own not-yet-installed version, and fail because of missing symbols.
      Prevent that by, as the <systemitem class="username">root</systemitem>
      user, moving the symlink out of the way:
    </para>

<screen role="root"><userinput>if [ -e ${QT5DIR}/lib/libQt5WebEngineCore.so ]; then
  mv -v ${QT5DIR}/lib/libQt5WebEngineCore.so{,.old}
fi</userinput></screen>

    <para>
      Install <application>qtwebengine</application> by running the following
      commands:
    </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

qmake .. -- -system-ffmpeg -webengine-icu &amp;&amp;
make</userinput></screen>

<!--
    <para>
      if you wish to build the HTML documentation, issue:
    </para>

<screen><userinput>make docs</userinput></screen>
-->
    <para>
      This package does not come with a test suite.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

    <!-- EDITORS NOTE: If you are updating this package, use INSTALL_ROOT=
         instead of DESTDIR= -->
<!--
    <para>
      If you built the HTML documentation, install it with:
    </para>

<screen role="root"><userinput>make install_docs</userinput></screen>
-->
    <para>
      Remove references to the build directory from installed library
      dependency (prl) files by running the following
      commands as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>find $QT5DIR/ -name \*.prl \
   -exec sed -i -e '/^QMAKE_PRL_BUILD_DIR/d' {} \;</userinput></screen>

    <para>
      Finally, as the <systemitem class="username">root</systemitem>
      user, remove the python symlink:
    </para>

<screen role="root"><userinput>rm -v /usr/bin/python</userinput></screen>
  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>qmake</command>: This will build the included copy of
      <application>ninja</application> if it is not already installed
      and use it to configure the build.
    </para>

    <para>
      <command>-- -system-ffmpeg -webengine-icu</command>: 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.  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.
    </para>

    <!--
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
       href="../../xincludes/SIOCGSTAMP.xml"/>
    -->

    <para>
      <option>NINJAJOBS=4 make</option>: 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 do this:
    </para>
      
      <itemizedlist>
        <listitem>
          <para>
            Building on a subset of CPUs allows measuring the build time
            for that number of processors or to run other CPU-intensive tasks on
            other cores.
          </para>
        </listitem>
        <listitem>
          <para>
            Improving the build speed on a less-well endowed 4-core machine.
            On a machine with a powerful CPU and plenty of RAM, running N+2
            jobs (the ninja default for 4+ cores) for the large working sets
            of the C++ compiles in this package is typically only marginally
            faster than running N jobs at a time.  But for a machine with less
            memory it can be much slower.
          </para>
        </listitem>
        <listitem>
          <para>
            Reducing the number of cores being used on long running, CPU
            intensive packages may alleviate heat problems.
          </para>
        </listitem>
      </itemizedlist>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring QtWebEngine</title>

    <sect3 id="qtwebengine-config">
      <title>Configuration Information</title>

      <para>
        If you are upgrading from an older minor version of this
        application, for some webpages to load you may need to
        clear the <emphasis>browser</emphasis> caches, e.g. for
        <application>falkon</application> they will be found in
        <filename class="directory">~/.cache/falkon/</filename>.
        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.
      </para>

      <para>
        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.
      </para>

    </sect3>

  </sect2>

  <sect2 role="kernel" id="qtwebengine-kernel">
    <title>Kernel Configuration</title>

    <para>
      Enable the following options in the kernel configuration and recompile the
      kernel if necessary:
    </para>

<!-- Spaces are significant in <screen> sections -->
<screen><literal>General setup ---&gt;
  -*- Namespaces support ---&gt;
    [*]     UTS namespace                     [CONFIG_UTS_NS]
    [*]     TIME namespace                    [CONFIG_TIME_NS]
    [*]     IPC namespace                     [CONFIG_IPC_NS]
    [ ]     User namespace                    #CONFIG_USER_NS is not set
    [*]     PID namespace                     [CONFIG_PID_NS]
    [*]     Network namespace                 [CONFIG_NET_NS]</literal></screen>

    <para>
      These are now the default options. Do <emphasis>NOT</emphasis> enable
      User namespace (CONFIG_USER_NS), it <emphasis>will</emphasis> cause
      libQtWebengineCore to crash.
    </para>

    <indexterm zone="qtwebengine qtwebengine-kernel">
      <primary sortas="d-qtwebengine">qtwebengine</primary>
    </indexterm>
  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          qtwebengine_convert_dict and 
          QtWebEngineProcess (in $QT5DIR/libexec)
        </seg>
        <seg>
          libQt5Pdf.so,
          libQt5PdfWidgets.so,
          libQt5WebEngineCore.so, 
          libQt5WebEngine.so, and 
          libQt5WebEngineWidgets.so
        </seg>
        <seg>
          $QT5DIR/include/QtPdf,
          $QT5DIR/include/QtPdfWidgets,
          $QT5DIR/include/QtWebEngine,
          $QT5DIR/include/QtWebEngineCore,
          $QT5DIR/include/QtWebEngineWidgets,
          $QT5DIR/qml/QtWebEngine, and
          $QT5DIR/translations/qtwebengine_locales
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="qtwebengine_convert_dict">
        <term><command>qtwebengine_convert_dict</command></term>
        <listitem>
          <para>
            converts hunspell dictionaries (<literal>.dic</literal>) to chromium
            format (<literal>.bdic</literal>)
          </para>
          <indexterm zone="qtwebengine qtwebengine_convert_dict">
            <primary sortas="b-qtwebengine_convert_dict">qtwebengine_convert_dict</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="QtWebEngineProcess">
        <term><command>QtWebEngineProcess</command></term>
        <listitem>
          <para>
            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)
          </para>
          <indexterm zone="qtwebengine QtWebEngineProcess">
            <primary sortas="b-QtWebEngineProcess">QtWebEngineProcess</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libQtWebEngine-lib">
        <term><filename class="libraryfile">libQtWebEngine.so</filename></term>
        <listitem>
          <para>
            provides QML types for rendering web content within a QML application
          </para>
          <indexterm zone="qtwebengine libQtWebEngine-lib">
            <primary sortas="c-libQtWebEngine">libQtWebEngine.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libQtWebEngineCore">
        <term><filename class="libraryfile">libQtWebEngineCore.so</filename></term>
        <listitem>
          <para>
            provides public API shared by both QtWebEngine and QtWebEngineWidgets
          </para>
          <indexterm zone="qtwebengine libQtWebEngineCore">
            <primary sortas="c-libQtWebEngineCore">libQtWebEngineCore.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libQtWebEngineWidgets">
        <term><filename class="libraryfile">libQtWebEngineWidgets.so</filename></term>
        <listitem>
          <para>
            provides a web browser engine as well as C++ classes to render and
            interact with web content
          </para>
          <indexterm zone="qtwebengine libQtWebEngineWidgets">
            <primary sortas="c-libQtWebEngineWidgets">libQtWebEngineWidgets.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>
  </sect2>

</sect1>