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
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:
|Force building against OpenSSL, even on Windows and Mac OS X.|
|Force building against the system libarchive.|
|Do not build against the system libarchive, even if one was detected.|
|Force building 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 |
|Enable building of all unit-tests.|
|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 though.|
If you specify an
In addition, all binaries on Linux will get an absolute
In any case, 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 on supporting SD-Card installations. Works around systemd interfering with loopback mounts.|
|Enables support for Qt widgets. Enabling this option can be useful to enable the use of some development graphical tools using Qt widgets.|
|Compiles in |
|The hardware-id will be read from the specified |
|Enables building and linking against |
|Disables building and linking against |
The Hardware ID
The installer part of the application-manager needs an unique device id for two purposes:
- 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.
- 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:
- No configure option: use the MAC of the first ethernet device. Works in 90% of all cases out of the box.
qmake --config hardware-id=foohardcodes 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.
qmake --config hardware-id-from-file=barmakes the application-manager read the contents of the file
barat startup and use its content as the id instead of the ethernet MAC. Useful if your device has a unique device id available via
/sysand 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:
in the build directory. The command-line output will tell 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
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.