source: x/lib/qtwebengine.xml@ 1d23596

<?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.13">
  <!ENTITY qtwebengine-download-http "https://download.qt.io/archive/qt/&qtwebengine-major;/&qtwebengine-version;/submodules/qtwebengine-everywhere-src-&qtwebengine-version;.tar.xz">
  <!ENTITY qtwebengine-download-ftp  " ">
  <!ENTITY qtwebengine-md5sum        "235ecc14211ba03ae7331c175c1b7c78">
  <!ENTITY qtwebengine-size          "245 MB">
  <!ENTITY qtwebengine-buildsize     "3.5 GB (135 MB installed)">
  <!ENTITY qtwebengine-time          "62 SBU (using 4 cores)">
]>

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

    &lfs84_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:
          <ulink url="&patch-root;/qtwebengine-&qtwebengine-version;-background_rendering_fix-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="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>

    <para>
      First, 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, apply a patch that fixes background rendering issues in Falkon,
      and crashes on multimedia-heavy sites.
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../qtwebengine-&qtwebengine-version;-background_rendering_fix-1.patch</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/libQtWebEngineCore.so ]; then
  mv -v ${QT5DIR}/lib/libQtWebEngineCore.so{,.old}
fi</userinput></screen>

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

<screen><userinput>sed -i 's/SIOCGSTAMP/0x8906/' \
src/3rdparty/chromium/third_party/webrtc/rtc_base/physical_socket_server.cc &amp;&amp;
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>
  </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>

    </sect3>

  </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
        </seg>
        <seg>
          libQt5WebEngineCore.so, 
          libQt5WebEngine.so, and 
          libQt5WebEngineWidgets.so
        </seg>
        <seg>
          $QT5PREFIX/includeQtWebEngine,
          $QT5PREFIX/include/QtWebEngineCore, and
          $QT5PREFIX/include/QtWebEngineWidgets
        </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>