Installation

Supported Platforms

The application manager is tested regularly on multiple platforms.

The following platforms are only supported for development and testing purposes. In addition these platforms only allow the application manager to work in single-process mode:

  • Windows
  • macOS
  • Android (the application manager cannot be deployed directly, but only as part of an Android APK package containing the System UI)

These platforms can be used for development and production and will allow you to use the full feature set of the application manager:

  • Linux desktop and embedded in single-process and multi-process mode

    Note: In multi-process mode, only the Intel, AMD (open source), and VMWare graphics drivers are supported due to the varying stability levels in Wayland drivers. While other drivers may work, they require either special QtWayland versions or specific firmware blobs for the GPU driver.

Prerequisites

To build the application manager with all its features, the following components are required:

  • Qt 6.5.0 or higher.
  • libyaml 2.2 or higher.
  • libarchive 3.5 or higher - if you need the installer functionality.
  • libsystemd 183 or higher - if you need systemd watchdog support.

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

apt-get install libyaml-dev libarchive-dev libsystemd-dev

Note: On platforms without pkg-config (for example, Windows or macOS) as well as on platforms that lack one of the prerequisites, the bundled versions of libyaml and libarchive from the src/3rdparty folder are automatically 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.

Runtime Requirements

Some libraries used by the application manager are not directly linked in, but instead loaded dynamically at runtime:

  • openssl - Linux only and only if you need the installer functionality. Qt needs to be built with openssl support. The required minimum version is defined by Qt.
  • libdbus 1.12 or higher - if you need multi-process mode or appman-controller support. As libdbus is not readily available for Windows and macOS, the application manager provides its own copy to support the appman-controller tool (which is also used by the Qt-Creator integration).

Multi-process vs. Single-process

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

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

You can force the build mode via the respective --force-multi-process and --force-single-process command line options, as described below.

Note: The Qt Installer cannot install the necessary Wayland development packages from your Linux distro when installing the QtWaylandCompositor module. This will result in hard to read cmake errors when trying to build the application manager examples.
sudo apt install libwayland-dev zlib1g-dev (or the equivalent installation on a non Debian-based distro) will fix this.

Build

The application manager uses CMake for its build system. The basic installation steps are:

mkdir <builddir>
  && cd <builddir>
  && cmake <srcdir> <options>
  && cmake --build .
  && cmake --install .

or

mkdir <builddir>
  && cd <builddir>
  && <qtbase>/bin/qt-configure-module <srcdir> <options>
  && cmake --build .
  && cmake --install .

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

There are various options that can be given to CMake to tailor the build to suit your needs.

With Qt's new CMake based build system, there are three ways to set configure options for Qt modules:

  1. You can call cmake from a shell and specify the options as -DINPUT_<option>=<value> directly on the CMake command line
  2. You can also use the cmake-gui or Qt Creator's built-in configuration UI to change options after the first CMake run
  3. Again on the command line, there is Qt's convenience CMake wrapper qt-configure-module, which lets you specify the options as normal command line options: --<option>=<value>
OptionDescription
libarchiveSet to system to force a build against the system libarchive, or qt to not build against the system libarchive, even if one was detected.
libyamlSet to system to force a build against the system libyaml, or qt to not build against the system libyaml, even if one was detected.
force-single-processForce a single-process build, even if Qt's Wayland compositor module is available.
The corresponding cmake input is -DINPUT_force_mode=single.
force-multi-processForce a multi-process build - this will break if Qt's Wayland compositor module is not available.
The corresponding cmake input is -DINPUT_force_mode=multi.
installer Set to no to disable the installer part.
external-dbus-interfacesSet to no to completely 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.
tools-onlySet to yes to create a build that only compiles the tools (as in Qt build tools, that are only built for the host Qt when cross compiling): appman-packager.
package-serverSet to no to disable building the appman-package-server tool, and yes to force building it. The default depends on the availability of the QtHttpServer module.
widgets-supportSet to yes to enable support for Qt widgets. This option can be useful to enable the use of some development tools using Qt widgets.
hardware-id=<id>If set, compiles in id as a hard-coded hardware-id; see The Hardware ID for more information.
libbacktraceIf set to yes, enables building and linking against libbacktrace in the 3rdparty folder. This gives you readable backtraces for crashes on Linux, but also increases the binary size slightly. For debug builds, this option is enabled by default. Setting this to no disables building and linking against libbacktrace.
stackwalkerIf set to yes, enables building and linking against stackwalker in the 3rdparty folder. This gives you readable backtraces for crashes on Windows, but also increases the binary size slightly. For debug builds, this option is enabled by default. Settings this to no disables building and linking against stackwalker.
libdbusWindows and macOS only: If set to yes, enables building libdbus-1 from the 3rdparty folder. This will allow you to use the appman-controller tool (which is also used by the Qt-Creator integration) on Windows and macOS. This option is enabled by default. Settings this to no disables building libdbus-1.
systemd-watchdogSet to no to disable building against libsystemd for Watchdog support and yes to force building with it. The default depends on the availability of libsystemd-dev.

The Hardware ID

The installer part of the application manager needs a unique device ID, if you want to deliver application packages that are bound to a specific device unit from your app-store. The use case here is to prevent customers from buying apps once and then sharing them with others for free.

Since the application manager doesn't know, at build time, how a potential app-store will be configured, the application manager tries to create a 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 application manager starts, this scenario will not work.

There are three different ways to specify a hardware ID:

  1. No configure option: use the MAC address of the first ethernet device. Typically, this option works out of the box.
  2. hardware-id=yourID hardcodes the ID to yourID. This option 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 the application manager starts.
  3. hardware-id=@yourFile makes the application manager read the contents of yourFile at startup and uses its content as the ID; instead of the ethernet MAC address. This option is useful if your device has a unique device ID available via /proc or /sys and you want to use features that require such an ID.

Generate Code-Coverage Data

Instead of doing a normal build, you can also create a coverage build by running cmake -DAM_COVERAGE=ON. Since every compile step needs to be instrumented with special compiler flags, make sure to create a new build directory, or at least clean an existing one.

Using a build like this enables you to generate HTML coverage reports with the following command in the build directory:

cmake --build . --target check_coverage

The command line output provides 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.

Ideally, in a production setup, the basic configuration is done via two separate config files: one for target system specific setup and one for System UI specific settings. The target system specific one would for example have the path to installation directories and the required logging settings; the System UI specific one would for example have the QML import path and the paths to built-in apps.

If you have the target settings in /etc/target-am-config.yaml and the System UI with its am-config.yaml and main.qml files at /path/to/system-ui, you can then the application manager like so:

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

--verbose gives you verbose output, which is quite helpful when first setting up the environment and also for debugging purposes.

© 2024 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.