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:
- 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).
- Provide a valid info.yaml file.
- Make the application-manager aware of your application by running
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
Note: Dynamically adding/updating/removing single applications is supported via the ApplicationInstaller interface.
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)
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
Just add a ".qmake.conf" file with the following content to your repository, which gets automatically loaded by qmake:
CONFIG += am-package
© 2019 Luxoft Sweden AB. 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.