Writing an application that can be run as a client within the application-manager is not that much different from writing a stand-alone QML application. It basically boils down to three additional tasks:

1. If you write a QML application, make the root element of your QML scene an ApplicationManagerWindow (or derive your own custom root item from it).
2. Provide a valid info.yaml file.
3. Make the application-manager aware of your application by running appman --recreate-database.

The Root Element

It is recommended to use either an ApplicationManagerWindow or a QtObject as the root of your QML application. This is especially important, if you expect similar behavior in single- and multi-process mode. If a QtObject is used, visible base elements should still be ApplicationManagerWindows. Nevertheless other root elements are supported for convenience, as well. Here are a few things to consider:

• Only ApplicationManagerWindows support window properties that are shared between the System-UI and the client applications.
• In multi-porcess mode Window root elements will get a decoration (unless QT_WAYLAND_DISABLE_WINDOWDECORATION is set) and will be invisible by default. QQuick Items will be wrapped inside a Window representing a Wayland client window.
• In single-process mode Window root elements will appear parallel to instead of inside the System-UI.

The Manifest and Updating the Database

The Manifest Definition documentation has all the information to produce a minimal info.yaml file that should get you going.

Recursively finding and parsing info.yaml files for potentially hundreds of applications can be a very time consuming task and would severely slow down application-manager's startup. Therefore, all manifest files are cached in a binary database. In order to make changes to an info.yaml file known to the application-manager, you have to force a rebuild of this database by calling appman --recreate-database.

Note: Dynamically adding/updating/removing single applications is supported via the ApplicationInstaller interface.

Qmake Integration

To install applications into a system-ui using the Installer Sub-System, the application first needs to be packaged. This can be done using the Packager utility. To better integrate the packaging into your usual developer workflow you can also use the qmake integration provided by the application-manager.

The integration will add an additional package target to the Makefile. By calling make package on the command line or adding it as an additional build step in QtCreator a new application package gets created.

Simple QML Apps

For simple QML only apps, just create a qmake project file which defines an install step for all the needed files. The actual install location doesn't matter in this case, because it will just be used as a temporary path during package creation.

TEMPLATE = aux

FILES += info.yaml \
         icon.png \
         Main.qml

app.files = $$FILES
app.path = /apps/com.example.application
INSTALLS += app

In addition add the following two lines to provide the install location to the packaging step and to load the actual qmake integration.

AM_PACKAGE_DIR = $$app.path

load(am-app)

Complex Apps

For more complex apps, where you need to deploy a C++ based QML plugin in addition to your QML content, you need to split your app into multiple folders and project files. One folder for the QML part, another one for the C++ plugin and a SUBDIRS project to glue them together.

The packaging integration will be done in the SUBDIRS project and expects that the other project files provide install targets to a shared install location. E.g the QML part installs it's files to '/apps/com.example.application', while the C++ plugin will install to '/apps/com.example.application/imports/com/example/application'.

In the SUBDIRS project you need to define the AM_MANIFEST variable and set it to the location of your info.yaml file as well as define the shared install location as AM_PACKAGE_DIR:

AM_MANIFEST = $$PWD/app/info.yaml
AM_PACKAGE_DIR = /apps/com.example.application

load(am-app)

Packaging multiple apps

If your repository provides multiple apps, like the Qt Auto Extra Apps Repository, you can use the am-package qmake feature to provide a repository wide package step.

Just add a ".qmake.conf" file with the following content to your repository, which gets automatically loaded by qmake:

CONFIG += am-package