source: x/lib/qtwebengine.xml@ 5efdd78

<?xml version="1.0" encoding="UTF-8"?>
<!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-download-http "https://download.qt.io/official_releases/qt/&qtwebengine-major;/&qtwebengine-version;/submodules/qtwebengine-everywhere-src-&qtwebengine-version;.tar.xz">
  <!ENTITY qtwebengine-download-ftp  " ">
  <!ENTITY qtwebengine-md5sum        "650bacb77f1fa3d4843e0667df07a1b8">
  <!ENTITY qtwebengine-size          "525 MB">
  <!ENTITY qtwebengine-buildsize     "8.7 GB (335 MB installed)">
  <!ENTITY qtwebengine-time          "40 SBU (Using parallelism=8)">
]>

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

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

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

    <warning>
      <para>
        QtWebEngine uses a forked copy of chromium, and is therefore vulnerable
        to many issues found there. The Qt developers seem to fork a newer
        version for minor Qt versions, but because chromium moves to newer
        versions very often, by the time the Qt developers get a forked version
        to pass their extended tests it is always an old version and security
        fixes from chromium (some of which have a CVE number) can take several
        months to appear in a QtWebengine release, even if the severity has been
        rated as Critical.
      </para>

      <para>
        Therefore, you should be wary of using QtWebEngine in a sensitive
        context and should always update to the next release as soon as it
        appears in this book, even if is not flagged as a Security Update.
        Identifying which vulnerabilities have been fixed in a particular
        release requires pulling the appropriate 'based-NNN' branch just before
        the previous and current releases and is often impractical. Reports of
        fixed QTBUG items do not seem to be available and there is not any
        documentation in the tarball for changes after the qt-5 versions.
      </para>
    </warning>

    &lfs121_checked;

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

      <para>
        To work around this, see the Command Explanations below.
      </para>
    </warning>

    <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">
          <!-- 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;-5.15.7-1.patch"/>-->
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/qtwebengine-&qtwebengine-version;-ffmpeg7_fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>


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

    <bridgehead renderas="sect4">Required</bridgehead>

    <para role="required">
      <xref linkend="cups"/>,
      <xref linkend="html5lib"/>,
      <xref linkend="nodejs"/>,
      <xref linkend="nss"/>,
      <xref linkend="pciutils"/>, and
      <xref linkend='qt6'/> 
    </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="mitkrb"/>,
      <xref linkend="pipewire"/>,
      <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="https://google.github.io/snappy/">snappy</ulink>
    </para>

  </sect2>

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

    <para>
     First, adapt the bundled copy of Chromium to the latest version of ffmpeg:
    </para>

<screen><userinput remap="pre">patch -Np1 -d src/3rdparty/chromium &lt; ../qtwebengine-&qtwebengine-version;-ffmpeg7_fixes-1.patch</userinput></screen>

    <para>
      Next, fix a build failure that occurs because the BLFS build of ffmpeg
      does not use OpenH264:
    </para>

<screen><userinput remap="pre">sed -e '189 s/=/&amp; false/' \
    -e '190 d'            \
    -i.orig src/3rdparty/chromium/third_party/webrtc/webrtc.gni</userinput></screen>

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

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

cmake -D CMAKE_MESSAGE_LOG_LEVEL=STATUS             \
      -D QT_FEATURE_webengine_system_ffmpeg=ON      \
      -D QT_FEATURE_webengine_system_icu=ON         \
      -D QT_FEATURE_webengine_system_libevent=ON    \
      -D QT_FEATURE_webengine_proprietary_codecs=ON \
      -D QT_FEATURE_webengine_webrtc_pipewire=ON    \
      -D QT_BUILD_EXAMPLES_BY_DEFAULT=OFF           \
      -G Ninja .. &amp;&amp;

ninja</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>ninja install</userinput></screen>

    <!-- EDITORS NOTE: If you are updating this package, use INSTALL_ROOT=
         instead of DESTDIR=    Not sure this is valid any more with version 6.6.2 -->
  </sect2>

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

    <para>
      <parameter>CMAKE_MESSAGE_LOG_LEVEL=STATUS</parameter>: Output
      interesting messages that project users might be interested in.
      Ideally these should be concise, no more than a single line, 
      but still informative.
    </para>

    <para>
      <parameter>QT_FEATURE_webengine_system_*</parameter>: Specify what
      external packages the system should use.
    </para>

    <para>
      <parameter>QT_BUILD_EXAMPLES_BY_DEFAULT=OFF</parameter>: Do not build
      examples by default.
    </para>

    <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 use options like this this:
    </para>

      <itemizedlist>
        <listitem>
          <para>
            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, <option>NINJAJOBS=4 make</option> will give a reasonable
            approximation (there is a short period where N+2 python and node
            jobs run).
          </para>
        </listitem>
        <listitem>
          <para>
            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.
          </para>
        </listitem>
        <listitem>
          <para>
            Reducing the number of cores being used on long running, CPU
            intensive packages may alleviate heat problems.
          </para>
        </listitem>
        <listitem>
          <para>
            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.
          </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>
      This package does not require any of the optional kernel namespace items,
      but if User namespace is enabled <phrase revision="systemd">(as happens
      in some unit files, for hardening)</phrase> PID namespace must also be
      enabled. In that case enable the following options in the kernel
      configuration and recompile the kernel if necessary:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="qtwebengine-kernel.xml"/>

    <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 (both in $QT6DIR/libexec)
        </seg>
        <seg>
          libQt6Pdf.so,
          libQt6PdfQuick.so,
          libQt6PdfWidgets.so,
          libQt6WebEngineCore.so,
          libQt6WebEngineiQuick.so,
          libQt6WebEngineQuickDelegatesQml.so, and
          libQt6WebEngineWidgets.so
        </seg>
        <seg>
          $QT6DIR/include/QtPdf,
          $QT6DIR/include/QtPdfQuick,
          $QT6DIR/include/QtPdfWidgets,
          $QT6DIR/include/QtWebEngineCore,
          $QT6DIR/include/QtWebEngineQuick,
          $QT6DIR/include/QtWebEngineWidgets,
          $QT6DIR/qml/QtWebEngine, and
          $QT6DIR/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>