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 5.15.0 or higher.
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.
libyaml 1.6 or higher.
libarchive 3.0 or higher - 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 or macOS) as well as on platforms that lack one of the dependencies, the bundled versions of these libraries from the 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.

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 dependencies are not available, such as:

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

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

Build

Note: If you want to build within QtCreator, you have to make sure that the qmake system() behavior when parsing: setting in Projects > Build Settings > General is set to Ignore.

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

qmake && make && make install

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

Option	Description
`-config force-libcrypto`	Force a build against OpenSSL, even on Windows and macOS.
`-config force-system-libarchive`	Force a build against the system libarchive.
`-config no-system-libarchive`	Do not build against the system libarchive, even if one was detected.
`-config force-system-libyaml`	Force a build against the system libyaml.
`-config no-system-libyaml`	Do not build against the system libyaml, even if one was detected.
`-config force-single-process`	Force a single-process build, even if Qt's Wayland `compositor` module is available.
`-config force-multi-process`	Force a multi-process build - this will break if Qt's Wayland `compositor` module is not available.
`-config enable-tests`	Include unit-tests in the build.
`-config enable-examples`	Include examples in the build.
`-config disable-installer`	Disable the installer part.
`-config disable-external-dbus-interfaces`	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.
`-config tools-only`	Build tools only: appman-controller and appman-packager.
`-config install-prefix=<path>`	Uses `path` as the base directory for `make install`. If you do not specify an `install-prefix` when you run 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 means: in developer builds, the binaries will be compiled directly to `${install-prefix}/bin` in prefix builds, the binaries will be compiled to `${builddir}/bin` Additionally, all binaries on Linux will get an absolute `RPATH` / `RUNPATH` when configured with an `install-prefix`. This allows you to run the binaries from the build directory directly without any weird side-effects. Linux pulls in the system-Qt, if it cannot find the necessary libs in `RUNPATH`. Ultimately, 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-workaround`	Paramount if you are running systemd and plan to support SD-Card installations. Works around systemd interfering with loopback mounts.
`-config enable-widgets`	Enables support for Qt widgets. 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 The Hardware ID for more information.
`-config hardware-id-from-file=<file>`	The hardware-id is read from the specified `file` at runtime; see The Hardware ID for more information.
`-config enable-libbacktrace`	Enables building and linking against `libbacktrace` in the 3rdparty folder. This gives you readable backtraces on Linux on crashes, but also increases the binary size slightly. For debug builds, this option is enabled by default.
`-config enable-stackwalker`	Enables building and linking against `stackwalker` in the 3rdparty folder. This gives you readable backtraces on Windows on crashes, but also increases the binary size slightly. For debug builds, this option is enabled by default.
`-config disable-libbacktrace`	Disables building and linking against `libbacktrace` in the 3rdparty folder.
`-config disable-stackwalker`	Disables building and linking against `stackwalker` in the 3rdparty folder.

The Hardware ID

The installer part of the application manager needs a unique device ID for two reasons:

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.
When you install 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 the same 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, 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:

No configure option: use the MAC address of the first ethernet device. Typically, this option works out of the box.
qmake --config 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.
qmake --config hardware-id-from-file=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.

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

Generate Code-Coverage Data

Instead of doing a normal build, you can also create a coverage build by running make coverage. Since every compile step needs to be instrumented with special compiler flags, make sure to run make clean before make coverage.

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

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

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 stick with the default, via the following command:

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

Alternatively, you can copy the contents of template-opt somewhere else; be sure to edit the 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, the QML import path, path to built-in apps, and so on.

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 --verbose main.qml

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

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