source: x/lib/qtwebengine.xml@ 45ab6c7

11.0 qt5new trunk
Last change on this file since 45ab6c7 was 45ab6c7, checked in by Xi Ruoyao <xry111@…>, 5 months ago

more SVN prop clean up

Remove "$LastChanged$" everywhere, and also some unused $Date$

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