Migrating code from 5.13 to 5.14

Qt Application Manager 5.14 added a new 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.

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 Alias Manifests. To disambiguate which application was actually activated, you would supply different 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 documentUrl field is not supported in the newer manifest versions anymore, but continues to work as expected when specified in a legacy manifest.

The 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 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: Launch Applications Using Intents System UI Example

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.

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. overlayfs, lvm2, or btrfs

Although you should use the new --installation-dir option or the applications/installationDir key in the configuration file to set the installation directory in 5.14, the old syntax using a list of installationLocations in the configuration file is still supported - as long as there is exactly one location defined in this list.

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 -r / --recreate-database command line option is not needed anymore. Along the same lines the --database option and the 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 --clear-cache option or not use caches at all via the --no-cache option.