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.8.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

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.

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>

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.