From 8a08dcc18ab8cbc3ef40989bd6500c413821dbf4 Mon Sep 17 00:00:00 2001 From: Robert Griebl Date: Tue, 14 Jul 2020 12:02:51 +0200 Subject: 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 --- doc/applicationmanager.qdocconf | 2 +- doc/index.qdoc | 1 + doc/manifest.qdoc | 8 ++- doc/migration-guide-5.14.qdoc | 111 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 119 insertions(+), 3 deletions(-) create mode 100644 doc/migration-guide-5.14.qdoc (limited to 'doc') 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 = \ "\n" \ "
\n" \ "

\n" \ - " © 2019 Luxoft Sweden AB.\n" \ + " © 2020 The Qt Company Ltd.\n" \ " Documentation contributions included herein are the copyrights of\n" \ " their respective owners.
" \ " 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. + +*/ -- cgit v1.2.1