source: x/lib/qtwebengine.xml@ 685b8672

11.0 qt5new trunk
Last change on this file since 685b8672 was 685b8672, checked in by Ken Moffat <ken@…>, 5 months ago

Update qtwebengine to 2021-05-03.

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