Added a migration document for 5.13 -> 5.14

Also fixed the handling of the legacy documentUrl field in application
manifests to conform to the documentation.

Change-Id: I35d179058afa939a67471829c03b69954ec188d7
Reviewed-by: Bernd Weimer <bernd.weimer@pelagicore.com>

4 files changed, 119 insertions, 3 deletions

diff --git a/doc/applicationmanager.qdocconf b/doc/applicationmanager.qdocconf
index f347eb2d..59ec4937 100644
--- a/doc/applicationmanager.qdocconf
+++ b/doc/applicationmanager.qdocconf
@@ -9,7 +9,7 @@ HTML.footer = \
     "</div>\n" \
     "<div class=\"footer\">\n" \
     "   <p>\n" \
-    "   <acronym title=\"Copyright\">&copy;</acronym> 2019 Luxoft Sweden AB.\n" \
+    "   <acronym title=\"Copyright\">&copy;</acronym> 2020 The Qt Company Ltd.\n" \
     "   Documentation contributions included herein are the copyrights of\n" \
     "   their respective owners.<br>" \
     "   The documentation provided herein is licensed under the terms of the" \
diff --git a/doc/index.qdoc b/doc/index.qdoc
index 4f920f9f..9a0d66fc 100644
--- a/doc/index.qdoc
+++ b/doc/index.qdoc
@@ -55,6 +55,7 @@ For a high-level overview, see \l{The Qt Application Manager}{Introduction to th
     \li \l{Use Qt Resources}
     \li \l{Single-Process vs. Multi-Process Mode}
     \li \l{Migrating code from 5.11 to 5.12}
+    \li \l{Migrating code from 5.13 to 5.14}
 \endlist
 
 \section1 Tools
diff --git a/doc/manifest.qdoc b/doc/manifest.qdoc
index a9091963..28382755 100644
--- a/doc/manifest.qdoc
+++ b/doc/manifest.qdoc
@@ -1,7 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 Luxoft Sweden AB
-** Copyright (C) 2018 Pelagicore AG
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Application Manager.
@@ -376,6 +375,11 @@ that specifies which runtime a configuration option applies to:
         \li Setting these variables disables the use of the quick launch mechanism for this
             application.
         \endlist
+\row
+    \li \c documentUrl
+    \li string
+    \li An optional default document URL to use if the application is started without
+        specifying a document URL (see \l{ApplicationManager::startApplication}).
 \endtable
 
 */
diff --git a/doc/migration-guide-5.14.qdoc b/doc/migration-guide-5.14.qdoc
new file mode 100644
index 00000000..1555e79e
--- /dev/null
+++ b/doc/migration-guide-5.14.qdoc
@@ -0,0 +1,111 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Application Manager.
+**
+** $QT_BEGIN_LICENSE:FDL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+
+\page migration-guide-5.14.html
+\title Migrating code from 5.13 to 5.14
+
+Qt Application Manager 5.14 added a new \l{Intents} IPC mechanism and added support for application
+packages shipping multiple executables. In this document we go through the main API breaks and how
+to port affected code and meta-data from the 5.13 to the new 5.14 API.
+
+\section1 Application Aliases and the documentUrl
+
+If you wanted to have a single application, but have it show up with multiple different entries in
+the launcher, you would use \l{Alias Manifests}. To disambiguate which application was actually
+activated, you would supply different \c documentUrl parameters in each of the alias manifests and
+watch for these in a signal handler for ApplicationInterface::openDocument.
+This mechanism only worked for built-in applications though and it was not possible to extend it in
+a clean way to support the new multiple executables alternative that is possible with 5.14.
+
+Because of this, support for alias manifests is completely removed in 5.14.
+
+The \c documentUrl field is not supported in the newer manifest versions anymore, but continues to
+work as expected when specified in a legacy manifest.
+
+The \c documentUrl parameter in the ApplicationObject::start() and
+ApplicationManager::startApplication() calls is still fully supported. This also ties into the
+open-URL handling via ApplicationMananger::openUrl() and Qt::openUrlExternally(), which use the \c
+documentUrl parameter to communicate the URL to open towards the application. Although there are no
+plans to retire this API, you still might want to switch over to the more versatile intent
+framework, depending on your use-case.
+
+There is an example explaining how to use this new mechanism as a direct replacement for the old
+alias manifests: \l{Launch Applications Using Intents System UI Example}
+
+
+\section1 The PackageManager and the PackageObject
+
+Installable applications were already referred to as "packages", but were just represented by an
+ApplicationObject handle within the the application manager. Now that 5.14 added support for
+multiple applications within a single package, all packages - even built-in ones - are represented
+by a PackageObject handle, which in turn holds references to all the contianed applications. For
+legacy applications, this results in the PackageObject referring to just a single application.
+
+A new PackageManager singleton was added, which acts as an item model for all PackageObjects in the
+same way the ApplicationManager does for ApplicationObjects. Since everything is a package now, the
+ApplicationInstaller singleton functionality was moved to the PackageManager singleton and the API
+was adapted slightly to reflect the distinction between packages and applications.
+The old ApplicationInstaller singleton is deprecated, but still available as a light-weight wrapper
+around the new PackageManager.
+In the same vein, using the PackageManager singleton is completely optional, if the information you
+are getting from the ApplicationManager singleton is sufficient for your use-case.
+
+
+\section1 Multiple Installation Locations
+
+The possibility to specify multiple installation locations for installing third-party applications
+has been removed in 5.14. This feature complicated the ApplicationInstaller API use, added a lot of
+hard to test complexity to the installer code base and the originally intended use-case (removable
+SD-Cards) was not fully implemented at all.
+
+A replacement for this functionality should be implemented on a system level and depend on the
+intended use-case: candidates would be e.g.
+\l{https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html}{\c overlayfs},
+\l{https://www.tldp.org/HOWTO/LVM-HOWTO/index.html}{\c lvm2}, or
+\l {https://www.kernel.org/doc/html/latest/filesystems/btrfs.html}{\c btrfs}
+
+Although you should use the new \c --installation-dir option or the \c applications/installationDir
+key in the configuration file to set the installation directory in 5.14, the old syntax using a
+list of \c installationLocations in the configuration file is still supported - as long as there is
+exactly one location defined in this list.
+
+\section1 Application Database Internals
+
+The internal application database - a cache of the known application manifest files - was
+completely re-done in 5.14. All manifest files are now scanned on startup, so the \c -r / \c
+--recreate-database commandline option is not needed anymore. Along the same lines the \c --database
+option and the \c applications/database configuration key are not needed anymore, because the new
+application database is just treated as a standard cache file and is stored in the appropriate
+system directories (see also QStandardPaths::CacheLocation).
+
+Although both the configuration and application caches are versioned and keyed to the checksum
+of the respective source files, you can still force the application manager to either clear them via
+the \c --clear-cache option or not use caches at all via the \c --no-cache option.
+
+*/