source: x/lib/qtwebengine.xml@ 639a5b9

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 639a5b9 was 639a5b9, checked in by Douglas R. Reno <renodr@…>, 7 months ago

qtwebengine: Minor typo fixes

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

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