The application-manager is tested regularly on these platforms:

  • Windows (single-process)
  • macOS (single-process)
  • Linux desktop (single-process)
  • Linux desktop (multi-process)

    Note: Due to the wildly varying stability of Wayland drivers, only the Intel and VMWare drivers are supported. Other drivers may work, but may also need either special QtWayland versions or specific firmware blobs for the GPU driver.


In order to build the application-manager with all its features, the following components are required:

  • Qt 5.9.0 or higher.
  • libyaml 1.6 or higher.
  • openssl 1.0.1 or higher - Linux only. At compile time, only the headers need to be available. The needed libraries will be dynamically loaded at runtime.
  • libarchive 3.0 or higher - only if you need the installer functionality.

On Debian-based systems, this command installs the three required packages:

apt-get install libyaml-dev libarchive-dev libssl-dev

Note: On platforms without pkg-config (for example, Windows and macOS) as well as on platforms lacking one of the dependencies, the bundled versions of these libraries from the 3rdparty folder will automatically be used instead. Make sure you are aware of the licensing implications, since these bundled 3rdparty libs will be linked in as static libraries. This option is not meant for production, but for development and testing environments only.

Multi- vs. Single-process

By default, the application-manager always tries to build in multi-process mode, but will fallback to single-process mode, if certain dependencies are not available:

  • You are building for Linux.
  • The QtWayland module is available.
  • The QtDBus module is available.

You can force the build mode though via the respective -config options force-multi-process and force-single-process (see below).


The application-manager is using qmake for its build-system. This means that the basic installation steps are:

qmake && make && make install

There are various options that can be given to qmake to tailor the build to your needs:

-config force-libcryptoForce building against OpenSSL, even on Windows and Mac OS X.
-config force-system-libarchiveForce building against the system libarchive.
-config no-system-libarchiveDo not build against the system libarchive, even if one was detected.
-config force-system-libyamlForce building against the system libyaml.
-config no-system-libyamlDo not build against the system libyaml, even if one was detected.
-config force-single-processForce a single-process build, even if Qt's Wayland compositor module is available.
-config force-multi-processForce a multi-process build - this will break if Qt's Wayland compositor module is not available.
-config enable-testsEnable building of all unit-tests.
-config disable-installerDisable the installer part.
-config disable-external-dbus-interfacesCompletely disable the external D-Bus interfaces. The internal communication channel between the applications and the application-manager will still be based on a peer-to-peer D-Bus though.
-config install-prefix=<path>Uses path as the base directory for make install. If you are not specifying an install-prefix when running qmake, then the application-manager will behave like a standard Qt module:
  • in developer builds, the binaries will be compiled directly to ${qtbase}/bin
  • in prefix builds, the binaries will be compiled to ${builddir}/bin

If you specify an install-prefix, this will change:

  • in developer builds, the binaries will be compiled directly to ${install-prefix}/bin
  • in prefix builds, the binaries will be compiled to ${builddir}/bin

In addition, all binaries on Linux will get an absolute RPATH / RUNPATH when configured with an install-prefix. This will allow you to run the binaries from the build directory directly without weird side-effects (Linux will just pull in the system-Qt, if it cannot find the necessary libs in RUNPATH.

In any case, the application-manager is a Qt module. This means that all libraries and headers are always installed into ${qtbase} to make them accessible via standard Qt mechanisms.

-config systemd-workaroundParamount if you are running systemd and plan on supporting SD-Card installations. Works around systemd interfering with loopback mounts.
-config enable-widgetsEnables support for Qt widgets. Enabling this option can be useful to enable the use of some development graphical tools using Qt widgets.
-config hardware-id=<id>Compiles in id as a hard-coded hardware-id (see below for more information)
-config hardware-id-from-file=<file>The hardware-id will be read from the specified file at runtime (see below for more information)
-config enable-libbacktraceEnables building and linking against libbacktrace in the 3rdparty folder. This will give you readable backtraces on crash, but will also increase the binary size slightly. This is enabled by default for debug builds.
-config disable-libbacktraceDisables building and linking against libbacktrace in the 3rdparty folder.

The Hardware ID

The installer part of the application-manager needs an unique device id for two purposes:

  1. If you want to deliver application packages that are bound to a specific device unit from your app-store. The use case is that you don't want customers buying apps and then sharing them with others for free.
  2. When installing application packages onto an SD card that can be removed by the user. The use case here is that we need to be able to detect which SD card "belongs" to which device, in case the user is swapping a card between devices.

Since the application-manager doesn't know at build time how a potential app-store will be configured, and if installations on removable SD-cards are enabled, it tries to create an unique id based on the MAC address of the first configured ethernet device. If the ethernet device is not configured at all (or configured after the start of the application-manager), this will obviously not work.

All in all, there are 3 different methods to specify an id:

  1. No configure option: use the MAC of the first ethernet device. Works in 90% of all cases out of the box.
  2. qmake --config hardware-id=foo hardcodes the id to foo. This is ideal, if you do not use any application-manager features that require this id to be unique and if you cannot (or do not want to) guarantee that an ethernet device is up when starting the application-manager.
  3. qmake --config hardware-id-from-file=bar makes the application-manager read the contents of the file bar at startup and use its content as the id instead of the ethernet MAC. Useful if your device has a unique device id available via /proc or /sys and you want to use features requiring such an id.

All executables (including the unit-tests) can be found in the build folder's bin directory after compiling.

Generating Code-Coverage Data

Instead of doing a normal build, you can also create a coverage build by running make coverage. As every compile step needs to be instrumented with special compiler flags, you need to make sure to run make clean before. Using a build like this enables you to generate HTML coverage reports simply by executing:

make check-coverage

in the build directory. The command-line output will tell you the url to the generated report.

System Setup

The runtime configuration of the application-manager is done through command-line switches and one or more configuration files.

Normally, the basic configuration is done via two separate config files: one for target system specific setup and one for System-UI specific settings. The default location for the system specific part is /opt/am. A standard setup is shipped with the application-manager in the template-opt directory. You can either stick with the default:

sudo cp -r template-opt/am /opt
sudo chown $(whoami) /opt/am -R

or you could copy the contents of template-opt somewhere else; be sure to edit the contained config.yaml file to reflect the changed paths.

Once this is done, add a file called am-config.yaml to your System-UI with UI specific settings (for example, QML import path, path to built-in apps).

With everything in place, you can start the application-manager:

cd /path/to/system-ui
appman -c /opt/am/config.yaml -c am-config.yaml -r --verbose main.qml

-r makes sure to recreate the apps database and --verbose will give you verbose output, which is quite helpful when first setting up the environment.

© 2018 Pelagicore AG. 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.