Writing Applications

Writing an application to run as a client within the application manager is similar to writing a stand-alone QML application, except for these three additional tasks or limitations:

1. If you write a QML application, make your QML scene's root element an ApplicationManagerWindow; or derive your own custom root item from it.
2. Provide a valid info.yaml file.
3. Restart the application manager to make it aware of your application.

The Root Element

It's recommended to use either an ApplicationManagerWindow or a QtObject as the root of your QML application. This is especially important if you require similar behavior in single-process and multi-process mode. If you use a QtObject, any 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-process mode, Window root elements always get a decoration (unless you set QT_WAYLAND_DISABLE_WINDOWDECORATION) and are invisible by default. QQuick Items are wrapped inside a Window representing a Wayland client window.
• In single-process mode Window root elements appear parallel to instead of inside the System UI.

The Manifest and Updating the Database

The Manifest Definition has all the information you need to produce a minimal info.yaml file.

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

qmake Integration

To install applications into a System UI using the Installer Sub-System, the application needs to be packaged first. 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.

The integration adds an additional package target to the Makefile. You can create a new application in one of two ways:

• Call make package on the command line.
• Add make package as an additional build step in QtCreator.

Simple QML Applications

For simple QML-only applications, 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 is used as a temporary path when the package is being created.

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 qmake integration.

AM_PACKAGE_DIR = $$app.path

load(am-app)

Complex Applications

For complex applications, where you need to deploy a C++ based QML plugin in addition to your QML content, you must 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 is done in the SUBDIRS project and this process expects that the other project files provide install targets to a shared install location. In this case, the QML part installs its files in /apps/com.example.application, while the C++ plugin installs in /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. Then, 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)

Package Multiple Applications

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

Add a .qmake.conf file with the following content to your repository, which is loaded automatically by qmake:

CONFIG += am-package