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
|
/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt 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 ApplicationManager::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 contained 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 command line 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.
*/
|
