source: x/lib/qtwebengine.xml@ 455eec0

11.0 ken/refactor-virt lazarus qt5new trunk xry111/git-date xry111/git-date-for-trunk xry111/git-date-test
Last change on this file since 455eec0 was 455eec0, checked in by Ken Moffat <ken@…>, 6 months ago

qtwebengine:

Note that the SBU time appears to be severely adrift - see #14863 -
and explain why this and browsers using it might be useful.

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@24435 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 22.1 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY qtwebengine-major "5.15">
8<!-- URL if there is a public release
9 <!ENTITY qtwebengine-download-http "https://download.qt.io/archive/qt/&qtwebengine-major;/&qtwebengine-version;/submodules/qtwebengine-everywhere-src-&qtwebengine-version;.tar.xz">
10 URL for a prepared git version -->
11 <!ENTITY qtwebengine-download-http "&sources-anduin-http;/qtwebengine/qtwebengine-&qtwebengine-version;.tar.xz">
12 <!ENTITY qtwebengine-download-ftp " ">
13 <!ENTITY qtwebengine-md5sum "838d5d4ef9d1e5b82a41bff6f830e4a4">
14 <!ENTITY qtwebengine-size "306 MB">
15 <!ENTITY qtwebengine-buildsize "4.4 GB (154 MB installed)">
16 <!ENTITY qtwebengine-time "64 SBU (Using parallelism=4) Issue: this appears to be around half the correct value">
17]>
18
19<sect1 id="qtwebengine" xreflabel="qtwebengine-&qtwebengine-version;">
20 <?dbhtml filename="qtwebengine.html"?>
21
22 <sect1info>
23 <othername>$LastChangedBy$</othername>
24 <date>$Date$</date>
25 </sect1info>
26
27 <title>QtWebEngine-&qtwebengine-version;</title>
28
29 <indexterm zone="qtwebengine">
30 <primary sortas="a-qtwebengine">qtwebengine</primary>
31 </indexterm>
32
33 <sect2 role="package">
34 <title>Introduction to QtWebEngine</title>
35
36 <para>
37 <application>QtWebEngine</application> integrates
38 <application>chromium</application>'s web capabilities into Qt. It
39 ships with its own copy of ninja which it uses for the build if it cannot
40 find a system copy, and various copies of libraries from ffmpeg, icu,
41 libvpx, and zlib (including libminizip) which have been forked by the
42 <application>chromium</application> developers.
43 </para>
44
45 <para>
46 This package and browsers using it may be useful if you need to use a
47 website designed for google chrome, or chromium, browsers.
48 </para>
49
50 <!-- Note for editors re switching between git versions and releases:
51 If a public release of Qt 5.15.3 (or later) appears in a meaningful
52 time frame, please keep the notes re the git build, as comments, so
53 that updating for later fixes will be easier: in the past, updates
54 of 'stable' versions (i.e. 5.12 when 5.14, 5.15 were the newest)
55 happened much later than updates to the newest version (now Qt6)
56 and it seems likely we might again need to use a git version to fix
57 future chromium vulnerabilities. -->
58
59 <warning>
60 <para>
61 QtWebEngine uses a forked copy of chromium, and is therefore vulnerable
62 to many issues found there. The Qt developers have always preferred to
63 make releases at the same time as the rest of Qt (rather than adding
64 emergency fixes), but with stable versions getting released after the
65 current development version. Now that they are keen to move to Qt6, the
66 5.15.3 and later Qt-5.15 releases are initially only available to paying
67 customers. QtWebEngine is something of an exception because of its LGPL
68 licence, but getting the git sources (with the forked chromium submodule)
69 to a position where they will successfully build on a current BLFS system
70 can take a lot of effort and therefore updates to the book may be delayed.
71 </para>
72
73 <para>
74 It seems likely that future 5.15-series versions will also be released
75 long after the chromium vulnerabilities are known.
76 </para>
77
78 <para> <!-- for git versions -->
79 The tarball linked to below was created from the 5.15 git branch
80 at https://code.qt.io/cgit/qt/qtwebengine.git commit 029771bcd254
81 just before the version there was rolled on for 5.15.4,
82 <!-- the DTS doesn't let me put a url in a para -->
83 <!--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>-->
84 with the chromium submodule using the 87-branch at revision 7c8217b36a95.
85 </para>
86 </warning>
87
88 <!-- note for editors on obtaining webengine from git.
89 First (if you do not already have a past version)
90 git clone git://code.qt.io/qt/qtwebengine.git
91 git submodule init -
92 that will report qtwebengine-chromium.git registered for src/3rdparty
93 now find the main branch names:
94 git fetch origin
95 git branch -r
96 after a release is prepared (even if the rest is not public), the 5.15
97 branch is probably what you want
98 git checkout origin/5.15
99 Confirm that HEAD is where you expected.
100 Now go to src/3rdparty
101 git fetch origin
102 git branch -r
103 The required branch is likely to be 87-branch unless there is a newer one
104 git checkout origin/87-branch (or whatever)
105 Use git log or git tk to look at its HEAD and check it seems appropriate.
106
107 Now create tarballs - 'git archive' does not work across submodule boundaries,
108 so you need to create one archive from the top of qtwebengine/ and another
109 from the top of src/3rdparty (chromium, gn, ninja are apparently all part of
110 the qtwebengine-chromium module). Then in a work area untar the qtwebengine
111 tarball, go down to src/3rdparty and untar the submodule tarball.
112 Decide on what to call the result and create a full xz tarball using tar -cJf.
113 -->
114
115 &lfs101_checked;
116
117 <note>
118 <para>
119 By default, ninja will use all online CPUs +2 (if at least 4 exist),
120 even if they are not available to the current task because the build
121 terminal has been restricted with 'taskset'. To work around this, see
122 the Command Explanations below.
123 </para>
124
125 <para>
126 Unusually, the shipped GN build system (used to create the Ninja files)
127 requires a static <filename class="libraryfile">libstdc++.a</filename>
128 although the installed libraries correctly use the shared version. If
129 that static library is not present, the build will fail quite quickly.
130 Please note that if you try to build webengine as part of
131 <application>Qt</application> and the static library is not available,
132 that build will either complete without installing webengine, or else
133 fail during the install (both variants have been observed in 5.12.0).
134 </para>
135 </note>
136
137 <bridgehead renderas="sect3">Package Information</bridgehead>
138 <itemizedlist spacing="compact">
139 <listitem>
140 <para>
141 Download (HTTP): <ulink url="&qtwebengine-download-http;"/>
142 </para>
143 </listitem>
144 <listitem>
145 <para>
146 Download (FTP): <ulink url="&qtwebengine-download-ftp;"/>
147 </para>
148 </listitem>
149 <listitem>
150 <para>
151 Download MD5 sum: &qtwebengine-md5sum;
152 </para>
153 </listitem>
154 <listitem>
155 <para>
156 Download size: &qtwebengine-size;
157 </para>
158 </listitem>
159 <listitem>
160 <para>
161 Estimated disk space required: &qtwebengine-buildsize;
162 </para>
163 </listitem>
164 <listitem>
165 <para>
166 Estimated build time: &qtwebengine-time;
167 </para>
168 </listitem>
169 </itemizedlist>
170
171 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
172 <itemizedlist spacing="compact">
173 <listitem>
174 <para>
175 Required patch:
176 <!-- keep links for releases and git versions as a reminder
177 that the tarball names names differ
178 <ulink url="&patch-root;/qtwebengine-everywhere-src-&qtwebengine-version;-ICU68-2.patch"/> -->
179 <ulink url="&patch-root;/qtwebengine-&qtwebengine-version;-build_fixes-2.patch"/>
180 </para>
181 </listitem>
182 </itemizedlist>
183
184 <bridgehead renderas="sect3">qtwebengine Dependencies</bridgehead>
185
186 <bridgehead renderas="sect4">Required</bridgehead>
187 <!-- the qmake output tends to be misleading. 'khr' is from Mesa -->
188 <para role="required">
189 <xref linkend="nodejs"/>,
190 <xref linkend="nss"/>,
191 <xref linkend="python2"/>, and
192 <xref linkend='qt5'/>
193 </para>
194
195 <bridgehead renderas="sect4">Recommended</bridgehead>
196 <note>
197 <para>
198 If these packages are not installed, the build process will compile and
199 install its own (perhaps older) version, with the side effect of
200 increasing build and installed disk space and build time.
201 </para>
202 </note>
203
204 <para role="recommended">
205 either <xref linkend="alsa-lib"/> or
206 <xref linkend="pulseaudio"/> (or both),
207 <xref linkend="ffmpeg"/>,
208 <xref linkend="icu"/>,
209 <xref linkend="libwebp"/>,
210 <xref linkend="libxslt"/>, and
211 <xref linkend="opus"/>
212 </para>
213
214 <bridgehead renderas="sect4">Optional</bridgehead>
215 <para role="optional">
216 <xref linkend="libevent"/>,
217 <xref linkend="poppler"/>,
218 <ulink url="https://github.com/open-source-parsers/jsoncpp/releases">jsoncpp</ulink>,
219 <ulink url="https://github.com/cisco/libsrtp/releases">libsrtp</ulink>,
220 <ulink url="http://google.github.io/snappy/">snappy</ulink>
221 </para>
222
223 <para condition="html" role="usernotes">
224 User Notes: <ulink url="&blfs-wiki;/qtwebengine"/>
225 </para>
226 </sect2>
227
228 <sect2 role="installation">
229 <title>Installation of qtwebengine</title>
230
231 <note>
232 <para>
233 Unlike version 5.15.2, the chromium-derived build system now needs
234 <command>python</command> to be available and to be python2. In
235 BLFS-10.1 the creation of the python symlink was removed as a step
236 towards eventually getting rid of python2 (other old packages which
237 need python2 usually work by invoking python2). If you are still
238 using an earlier version of BLFS where
239 <filename>/usr/bin/python</filename> exists, you can skip the
240 commands to create the symlink, and to later remove it.
241 </para>
242 </note>
243
244 <para>
245 First, as the <systemitem class="username">root</systemitem>
246 user, create the python symlink:
247 </para>
248
249<screen role="root"><userinput>ln -svf /usr/bin/python{2,}</userinput></screen>
250
251 <para>
252 Now apply a patch to fix several issues that can prevent the build working:
253 </para>
254
255<screen><userinput remap="pre">patch -Np1 -i ../qtwebengine-&qtwebengine-version;-build_fixes-2.patch</userinput></screen>
256
257<!-- start of commands for git versions only -->
258 <para>
259 Although the patch has ensured that git is not invoked during the build,
260 the build system has labyrinthine rules of byzantine complexity, and in
261 particular trying to build without two <filename>.git</filename> directories
262 will lead to it eventually falling into unexpected and unbuildable code
263 which references a private header that has not been created. Avoid this
264 by creating the required directories:
265 </para>
266
267<screen><userinput>mkdir -pv .git src/3rdparty/chromium/.git</userinput></screen>
268
269 <para>
270 Because this version of qtwebengine is aimed at a later release than the
271 current public releases, change it to build for qt-&qt5-version; using a
272 sed:
273 </para>
274
275<screen><userinput>sed -e '/^MODULE_VERSION/s/5.*/&qt5-version;/' -i .qmake.conf</userinput></screen>
276<!-- end of commands for git versions only -->
277
278 <para>
279 Now, ensure that the local headers are available when not building as
280 part of the complete <xref linkend="qt5"/>:
281 </para>
282
283<screen><userinput>find -type f -name "*.pr[io]" |
284 xargs sed -i -e 's|INCLUDEPATH += |&amp;$$QTWEBENGINE_ROOT/include |'</userinput></screen>
285
286 <para>
287 Next, allow the pulseaudio library to be linked at build time, instead
288 of run time. This also prevents an issue with newer pulseaudio:
289 </para>
290
291<screen><userinput>sed -e '/link_pulseaudio/s/false/true/' \
292 -i src/3rdparty/chromium/media/media_options.gni</userinput></screen>
293
294 <para>
295 Finally, fix a change in the build system which allows its developers to
296 pass e.g. -j20 to make (for quick tests of some areas) but breaks the
297 build with LFS's use of the NINJAJOBS environment variable:
298 </para>
299
300<!-- editors: See thread at
301http://lists.linuxfromscratch.org/pipermail/blfs-dev/2019-December/036996.html
302et.seq, particularly 037002.html which shows the commit near the end. -->
303
304<screen><userinput>sed -i 's/NINJAJOBS/NINJA_JOBS/' src/core/gn_run.pro</userinput></screen>
305
306 <para>
307 If an older version of the package's main library has been installed,
308 when the package is built separately it will link to that in preference
309 to its own not-yet-installed version, and fail because of missing symbols.
310 Prevent that by, as the <systemitem class="username">root</systemitem>
311 user, moving the symlink out of the way:
312 </para>
313
314<screen role="root"><userinput>if [ -e ${QT5DIR}/lib/libQt5WebEngineCore.so ]; then
315 mv -v ${QT5DIR}/lib/libQt5WebEngineCore.so{,.old}
316fi</userinput></screen>
317
318 <para>
319 Install <application>qtwebengine</application> by running the following
320 commands:
321 </para>
322
323<screen><userinput>mkdir build &amp;&amp;
324cd build &amp;&amp;
325
326qmake .. -- -system-ffmpeg -webengine-icu &amp;&amp;
327make</userinput></screen>
328
329<!--
330 <para>
331 if you wish to build the HTML documentation, issue:
332 </para>
333
334<screen><userinput>make docs</userinput></screen>
335-->
336 <para>
337 This package does not come with a test suite.
338 </para>
339
340 <para>
341 Now, as the <systemitem class="username">root</systemitem> user:
342 </para>
343
344<screen role="root"><userinput>make install</userinput></screen>
345
346 <!-- EDITORS NOTE: If you are updating this package, use INSTALL_ROOT=
347 instead of DESTDIR= -->
348<!--
349 <para>
350 If you built the HTML documentation, install it with:
351 </para>
352
353<screen role="root"><userinput>make install_docs</userinput></screen>
354-->
355 <para>
356 Remove references to the build directory from installed library
357 dependency (prl) files by running the following
358 commands as the <systemitem class="username">root</systemitem> user:
359 </para>
360
361<screen role="root"><userinput>find $QT5DIR/ -name \*.prl \
362 -exec sed -i -e '/^QMAKE_PRL_BUILD_DIR/d' {} \;</userinput></screen>
363
364 <para>
365 Finally, as the <systemitem class="username">root</systemitem>
366 user, remove the python symlink:
367 </para>
368
369<screen role="root"><userinput>rm -v /usr/bin/python</userinput></screen>
370 </sect2>
371
372 <sect2 role="commands">
373 <title>Command Explanations</title>
374
375 <para>
376 <command>qmake</command>: This will build the included copy of
377 <application>ninja</application> if it is not already installed
378 and use it to configure the build.
379 </para>
380
381 <para>
382 <command>-- -system-ffmpeg -webengine-icu</command>: If any options are
383 passed to qmake they must come after '--' which must follow '..' that points
384 to the main directory. The options here cause it to use system ffmpeg and
385 system icu. If built as part of full Qt5, the system icu is automatically
386 used (only) by Qt5Core if it is available, but unless this option is used
387 webengine will always use its shipped copy of icu, adding time and space
388 to the build.
389 </para>
390
391 <!--
392 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
393 href="../../xincludes/SIOCGSTAMP.xml"/>
394 -->
395
396 <para>
397 <option>NINJAJOBS=4 make</option>: If you patched system ninja in LFS to
398 recognize the NINJAJOBS environment variable, this command will run system
399 ninja with the specified number of jobs (i.e. 4).
400 There are several reasons why you might want to do this:
401 </para>
402
403 <itemizedlist>
404 <listitem>
405 <para>
406 Building on a subset of CPUs allows measuring the build time
407 for that number of processors or to run other CPU-intensive tasks on
408 other cores.
409 </para>
410 </listitem>
411 <listitem>
412 <para>
413 Improving the build speed on a less-well endowed 4-core machine.
414 On a machine with a powerful CPU and plenty of RAM, running N+2
415 jobs (the ninja default for 4+ cores) for the large working sets
416 of the C++ compiles in this package is typically only marginally
417 faster than running N jobs at a time. But for a machine with less
418 memory it can be much slower.
419 </para>
420 </listitem>
421 <listitem>
422 <para>
423 Reducing the number of cores being used on long running, CPU
424 intensive packages may alleviate heat problems.
425 </para>
426 </listitem>
427 </itemizedlist>
428
429 </sect2>
430
431 <sect2 role="configuration">
432 <title>Configuring QtWebEngine</title>
433
434 <sect3 id="qtwebengine-config">
435 <title>Configuration Information</title>
436
437 <para>
438 If you are upgrading from an older minor version of this
439 application, for some webpages to load you may need to
440 clear the <emphasis>browser</emphasis> caches, e.g. for
441 <application>falkon</application> they will be found in
442 <filename class="directory">~/.cache/falkon/</filename>.
443 You will need to do this if the browser starts to render
444 the page and then changes to a blank tab with a message
445 that something went wrong, and a button to Retry. Even
446 after removing the old caches, you may need to retry a
447 few times for each affected tab.
448 </para>
449
450 <para>
451 If a browser using this package fails to run and when run
452 from a term it reports 'Trace/breakpoint trap' that is
453 probably a kernel configuration issue - there is no need
454 to rebuild QtWebEngine, see the next section, recompile
455 the kernel and reboot to the new kernel.
456 </para>
457
458 </sect3>
459
460 </sect2>
461
462 <sect2 role="kernel" id="qtwebengine-kernel">
463 <title>Kernel Configuration</title>
464
465 <para>
466 This package does not require any of the optional kernel namespace items,
467 but if User namespace is enabled <phrase revision="systemd">(as happens
468 in some unit files, for hardening)</phrase> PID namespace must also be
469 enabled. In that case enable the following options in the kernel
470 configuration and recompile the kernel if necessary:
471 </para>
472
473<!-- Spaces are significant in <screen> sections -->
474<screen><literal>General setup ---&gt;
475 -*- Namespaces support ---&gt;
476 [ ] User namespace [CONFIG_USER_NS]
477 [*] PID namespace [CONFIG_PID_NS]</literal></screen>
478
479 <indexterm zone="qtwebengine qtwebengine-kernel">
480 <primary sortas="d-qtwebengine">qtwebengine</primary>
481 </indexterm>
482 </sect2>
483
484 <sect2 role="content">
485 <title>Contents</title>
486
487 <segmentedlist>
488 <segtitle>Installed Programs</segtitle>
489 <segtitle>Installed Libraries</segtitle>
490 <segtitle>Installed Directories</segtitle>
491
492 <seglistitem>
493 <seg>
494 qtwebengine_convert_dict and
495 QtWebEngineProcess (in $QT5DIR/libexec)
496 </seg>
497 <seg>
498 libQt5Pdf.so,
499 libQt5PdfWidgets.so,
500 libQt5WebEngineCore.so,
501 libQt5WebEngine.so, and
502 libQt5WebEngineWidgets.so
503 </seg>
504 <seg>
505 $QT5DIR/include/QtPdf,
506 $QT5DIR/include/QtPdfWidgets,
507 $QT5DIR/include/QtWebEngine,
508 $QT5DIR/include/QtWebEngineCore,
509 $QT5DIR/include/QtWebEngineWidgets,
510 $QT5DIR/qml/QtWebEngine, and
511 $QT5DIR/translations/qtwebengine_locales
512 </seg>
513 </seglistitem>
514 </segmentedlist>
515
516 <variablelist>
517 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
518 <?dbfo list-presentation="list"?>
519 <?dbhtml list-presentation="table"?>
520
521 <varlistentry id="qtwebengine_convert_dict">
522 <term><command>qtwebengine_convert_dict</command></term>
523 <listitem>
524 <para>
525 converts hunspell dictionaries (<literal>.dic</literal>) to chromium
526 format (<literal>.bdic</literal>)
527 </para>
528 <indexterm zone="qtwebengine qtwebengine_convert_dict">
529 <primary sortas="b-qtwebengine_convert_dict">qtwebengine_convert_dict</primary>
530 </indexterm>
531 </listitem>
532 </varlistentry>
533
534 <varlistentry id="QtWebEngineProcess">
535 <term><command>QtWebEngineProcess</command></term>
536 <listitem>
537 <para>
538 is a libexec program which runs a zygote process (one that listens
539 for spawn requests from a master process and will fork itself in
540 response)
541 </para>
542 <indexterm zone="qtwebengine QtWebEngineProcess">
543 <primary sortas="b-QtWebEngineProcess">QtWebEngineProcess</primary>
544 </indexterm>
545 </listitem>
546 </varlistentry>
547
548 <varlistentry id="libQtWebEngine-lib">
549 <term><filename class="libraryfile">libQtWebEngine.so</filename></term>
550 <listitem>
551 <para>
552 provides QML types for rendering web content within a QML application
553 </para>
554 <indexterm zone="qtwebengine libQtWebEngine-lib">
555 <primary sortas="c-libQtWebEngine">libQtWebEngine.so</primary>
556 </indexterm>
557 </listitem>
558 </varlistentry>
559
560 <varlistentry id="libQtWebEngineCore">
561 <term><filename class="libraryfile">libQtWebEngineCore.so</filename></term>
562 <listitem>
563 <para>
564 provides public API shared by both QtWebEngine and QtWebEngineWidgets
565 </para>
566 <indexterm zone="qtwebengine libQtWebEngineCore">
567 <primary sortas="c-libQtWebEngineCore">libQtWebEngineCore.so</primary>
568 </indexterm>
569 </listitem>
570 </varlistentry>
571
572 <varlistentry id="libQtWebEngineWidgets">
573 <term><filename class="libraryfile">libQtWebEngineWidgets.so</filename></term>
574 <listitem>
575 <para>
576 provides a web browser engine as well as C++ classes to render and
577 interact with web content
578 </para>
579 <indexterm zone="qtwebengine libQtWebEngineWidgets">
580 <primary sortas="c-libQtWebEngineWidgets">libQtWebEngineWidgets.so</primary>
581 </indexterm>
582 </listitem>
583 </varlistentry>
584
585 </variablelist>
586 </sect2>
587
588</sect1>
Note: See TracBrowser for help on using the repository browser.