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 varying stability levels in Wayland drivers, only the Intel and VMWare drivers are supported. While other drivers may work, they require either special QtWayland versions or specific firmware blobs for the GPU driver.
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 necessary libraries are dynamically loaded at runtime.
- 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.
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.
QtWaylandmodule is available.
QtDBusmodule is available.
You can force the build mode via the respective
force-single-process, as described below.
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:
|Force a build against OpenSSL, even on Windows and macOS.|
|Force a build against the system libarchive.|
|Do not build against the system libarchive, even if one was detected.|
|Force a build against the system libyaml.|
|Do not build against the system libyaml, even if one was detected.|
|Force a single-process build, even if Qt's Wayland |
|Force a multi-process build - this will break if Qt's Wayland |
|Include unit-tests in the build.|
|Include examples in the build.|
|Disable the installer part.|
|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.|
|Build tools only: appman-controller and appman-packager.|
If you specify an
Additionally, all binaries on Linux will get an absolute
Ultimately, the application manager is a Qt module. This means that all libraries and headers are always installed into
|Paramount if you are running systemd and plan to support SD-Card installations. Works around systemd interfering with loopback mounts.|
|Enables support for Qt widgets. This option can be useful to enable the use of some development graphical tools using Qt widgets.|
|Compiles in |
|The hardware-id is read from the specified |
|Enables building and linking against |
|Disables building and linking against |
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=yourIDhardcodes 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=yourFilemakes the application manager read the contents of
yourFileat 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
/sysand 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.
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
Using a build like this enables you to generate HTML coverage reports with the following command in the build directory:
The command line output provides you the URL to the generated report.
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
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 -r --verbose main.qml
-r makes sure to recreate the apps database and
--verbose gives you verbose output, which is quite helpful when first setting up the environment.
© 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.