1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtwebengine-deploying.html
\title Deploying Qt WebEngine Applications
\ingroup explanations-webtechnologies
The way to package and deploy applications varies between operating systems.
For Windows and \macos, \l{The Windows Deployment Tool}{windeployqt} and
\l{Deploying Applications on macOS}{macdeployqt} automate the steps to
generate a stand-alone application package.
When manually deploying applications that depend on \QWE, all the
files that are required to run the application have to be included:
libraries, QML imports, plugins, and translations.
For more information, see \l {Deploying Qt Applications}.
\section1 Target Platforms
\QWE does try to support all \l{Supported Platforms} of Qt. However,
due to different requirements of Chromium this is not always possible. Known
limitations are:
\list
\li \QWE currently supports only Windows, Linux, and \macos.
\li On Windows, \QWE only supports Windows Vista or newer as
target platform. Due to use of newer API in Chromium, Windows XP is
not supported. WinRT is not supported, either.
\endlist
\section1 Deploying Applications Manually
When manually deploying applications that depend on \QWE, the
following files might have to be deployed:
\list
\li Libraries
\li QML imports
\li \QWE process
\li Resources
\li Translations
\li Audio and video codecs
\endlist
\section2 Deploying Libraries
The following libraries must be deployed with applications that depend on
\QWE:
\list
\li QtWebEngineCore library
\li QtWebEngineWidgets or QtWebEngine libraries, depending on
application type
\endlist
\section2 Deploying QML Imports
If Qt Quick integration is used in the application, the QtWebEngine import
directory needs to be deployed.
\section2 Deploying \QWE Processes
\QWE takes advantage of the multi-process model that the Chromium
project offers. The multi-process model requires that the \QWE
Process executable be deployed alongside your application.
The WebEngine process is executed for each QWebEngineView or WebEngineView
instance. For example, a browser application
with two tabs open should have two separate instances of the process
running. This is a common approach used by most modern web engines to
provide a stable browsing experience.
At runtime, \QWE looks for the \c QtWebEngineProcess executable in
the directory that
QLibraryInfo::location(QLibraryInfo::LibraryExecutablesPath) returns.
For Qt installations, this is \c QTDIR/libexec (Linux) or \c QTDIR\bin
(Windows). The path can be changed by defining a \c qt.conf file, for
example. Alternatively, an executable path can be set as a value of the
\c QTWEBENGINEPROCESS_PATH environment variable. On \macos, \QWE
looks for the executable in \c .app/Helpers/QtWebEngineProcess.
\section2 Deploying Resources
\QWE requires the following resource files:
\list
\li \c qtwebengine_resources.pak contains the resources needed by
Chromium.
\li \c qtwebengine_devtools_resources.pak contains tools for remote
debugging.
\li \c qtwebengine_resources_100p.pak contains images suitable for low
resolution displays.
\li \c qtwebengine_resources_200p.pak contains images suitable for high
DPI displays.
\li \c icudtl.dat provides support for International Components for
Unicode (ICU). It is the Chromium version of ICU, which is not
needed if \QWE was configured to use the system ICU.
\li \c v8_context_snapshot.bin contains a previously prepared snapshot
of a v8 context used to speed up initialization. Debug builds use
separate snapshots with the file name extension \c .debug.bin instead
of \c .bin. On \macos, there is a snapshot for each architecture named
accordingly, for example \c v8_context_snapshot.arm64.bin or
\c v8_context_snapshot.arm64.debug.bin.
\endlist
Resources are searched from the following locations:
\list
\li On Linux and Windows: the \c resources directory in the directory
specified by QLibraryInfo::location(QLibraryInfo::DataPath)
\li On \macos: \c .app/Content/Resources
\li The application directory specified by QCoreApplication::applicationDirPath()
\endlist
Alternatively, a resources directory path can be set as a value of the
\c QTWEBENGINE_RESOURCES_PATH environment variable.
\section2 Translations
Locale data (such as \c en-US.pak) is searched form the following locations:
\list
\li On \macos: \c .app/Content/Resources
\li On Linux and Windows: \c qtwebengine_locales directory in the
directory specified by
QLibraryInfo::location(QLibraryInfo::TranslationsPath)
\endlist
Alternatively, a locales directory path can be set as a value of the
\c QTWEBENGINE_LOCALES_PATH environment variable.
\section2 JavaScript Files in Qt Resource Files
If your WebEngine application is built using the Qt Quick Compiler, and the application ships
JavaScript files inside .qrc resources, and these files are supposed to be loaded from inside
HTML pages, make sure to specify the resource files in a \c QTQUICK_COMPILER_SKIPPED_RESOURCES
qmake variable inside your project. This prevents the Qt Quick Compiler from trying to generate
C++ code for the corresponding JavaScript code, as well as removing the original JavaScript code
from the Qt resources file, which would lead to broken HTML pages. For example:
\code
QTQUICK_COMPILER_SKIPPED_RESOURCES += resources/my_resource.qrc
\endcode
\section2 \macos Specific Deployment Steps
To deploy a \QWE application on \macos, you will need to ensure that the \QWE process is signed
with an entitlements file that at least contains the entitlements listed in
QtWebEngineCore.framework/Helpers/QtWebEngineProcess.app/Contents/Resources/QtWebEngineProcess.entitlements.
To deploy a \QWE application that accesses the microphone or camera
on \macos, you will need to provide texts for the messages that will be shown to the user to
explain why the application asks for permission to access to the camera or microphone.
To do this, add the texts to the application's \c Info.plist file using the keys
described below.
For the camera usage message, provide a text using the following key:
\code
<key>NSCameraUsageDescription</key>
<string>Your message text for camera usage.</string>
\endcode
See also \l{https://developer.apple.com/documentation/bundleresources/information_property_list/nscamerausagedescription}
{Apple's property list file documentation}.
For the microphone usage message, provide a text using the following key:
\code
<key>NSMicrophoneUsageDescription</key>
<string>Your message text for microphone usage.</string>
\endcode
See also \l{https://developer.apple.com/documentation/bundleresources/information_property_list/nsmicrophoneusagedescription}
{Apple's property list file documentation}.
To notarize an application that accesses the camera or the microphone,
you will need to add the corresponding keys to your application's entitlements file used for
deployment and notarization.
To enable access to the camera, add:
\code
<key>com.apple.security.device.camera</key>
<true/>
\endcode
See also \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_device_camera}
{Apple's camera entitlement documentation}.
To enable access to the microphone, add:
\code
<key>com.apple.security.device.microphone</key>
<true/>
\endcode
See also \l{https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_device_microphone}
{Apple's microphone entitlement documentation}.
*/
|
