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:
- If you write a QML application, make your QML scene's root element an ApplicationManagerWindow; or derive your own custom root item from it.
- Provide a valid info.yaml file.
- Restart the application manager to make it aware of your application.
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 Definition has all the information you need to produce a minimal
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
Note: Dynamically adding, updating, or removing individual applications is supported via the ApplicationInstaller interface.
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:
make packageon the command line.
make packageas an additional build step in QtCreator.
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)
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
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_MANIFEST = $$PWD/app/info.yaml AM_PACKAGE_DIR = /apps/com.example.application load(am-app)
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
.qmake.conf file with the following content to your repository, which is loaded automatically by qmake:
CONFIG += am-package
© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.