Doc: Describe deployment of Qt WebEngine applications

Task-number: QTBUG-55142
Change-Id: I1255269730bb3b5ae13e2128743da421589c26c8
Reviewed-by: Kai Koehne <kai.koehne@qt.io>

1 files changed, 97 insertions, 26 deletions

diff --git a/src/webengine/doc/src/qtwebengine-deploying.qdoc b/src/webengine/doc/src/qtwebengine-deploying.qdoc
index 1336cdbfd..b6b91f2e9 100644
--- a/src/webengine/doc/src/qtwebengine-deploying.qdoc
+++ b/src/webengine/doc/src/qtwebengine-deploying.qdoc
@@ -29,18 +29,16 @@
     \page qtwebengine-deploying.html
     \title Deploying Qt WebEngine Applications
 
-    Qt WebEngine takes advantage of the multi process model that the Chromium
-    project offers. The multi process model requires the QtWebEngineProcess
-    executable to be deployed alongside your application. To do this, we
-    recommend the use of Qt's cross-platform deployment tools.
+    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 OS X}{macdeployqt} automate the steps to
+    generate a stand-alone application package.
 
-    Alternatively, if you are carrying out manual deployment, you will find the
-    QtWebEngineProcess executable in the libexec directory of your Qt
-    installation. On Windows, QtWebEngineProcess.exe is located in the bin
-    directory of your Qt application.
+    When manually deploying applications that depend on Qt WebEngine, all the
+    files that are required to run the application have to be included:
+    libraries, QML imports, plugins, and translations.
 
-    For more information on deploying Qt applications, please see
-    \l {Deploying Qt Applications}.
+    For more information, see \l {Deploying Qt Applications}.
 
     \section1 Target Platforms
 
@@ -49,32 +47,105 @@
     limitations are:
 
     \list
-        \li Qt WebEngine currently supports only Windows, Linux, and OS X.
+        \li Qt WebEngine currently supports only Windows, Linux, and macOS.
 
         \li On Windows, Qt WebEngine 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 Qt WebEngine Applications on Windows
+    \section1 Deploying Applications Manually
 
-    If your application depends on Qt WebEngine, you must deploy
-    \c{<Qt install path>/bin/QtWebEngineProcess.exe} to the application install
-    path. If you chose to deploy the binary to a different path, set the
-    \c QTWEBENGINEPROCESS_PATH environment variable to the binary's absolute
-    path (including its file name). This enables the application to find the
-    binary and execute it for every instance of QWebEngineView or
-    WebEngineView created. For example, a browser application with two tabs
-    open should have two separate processes of \c QtWebEngineProcess.exe
+    When  manually deploying applications that depend on Qt WebEngine, the
+    following files might have to be deployed:
+
+    \list
+        \li Libraries
+        \li QML imports
+        \li Qt WebEngine 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
+    Qt WebEngine:
+
+    \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 Qt WebEngine Processes
+
+    Qt WebEngine takes advantage of the multi-process model that the Chromium
+    project offers. The multi-process model requires that the Qt WebEngine
+    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.
 
-    \note To support HTML5 videos, you must additionally deploy
+    At runtime, Qt WebEngine 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, Qt WebEngine
+    looks for the executable in \c .app/Helpers/QtWebEngineProcess.
+
+    \section2 Deploying Resources
+
+    Qt WebEngine 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 Qt WebEngine was configured to use the system ICU.
+    \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
+    \endlist
+
+    \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
+
+    \section2 Deploying Audio and Video Codecs
+
+    To support HTML5 video, you must additionally deploy
     \c ffmpegsumo.dll (WebM codec plugin) into the \c qtwebengine directory
     under the application install path or under the path that the
-    \c PluginsPath variable was set to in
-    \c{<Qt install path>/<Qt version>/msvc2013/qt.conf}.
-
-    For more information about deploying applications on Windows, see
-    \l{Qt for Windows - Deployment}.
+    \c PluginsPath variable was set to in \c qt.conf.
 */