Configuration

Main Configuration

You can configure the application manager through config files and the command line. To display the currently supported command line options, run appman --help. Some of these options can also be set via config files that are referenced on the command line with the --config-file <filename> option.

The config file is a YAML file that follows the same rules as all the other YAML files used in the application manager.

Before parsing the YAML document, the application manager substitutes variables denoted by a syntax similar to bash: ${VariableName}. There are different types of variables that can be substituted this way:

TypeDescription
${CONFIG_PWD}Is substituted with the absolute path to the config file being parsed. This feature makes it possible to have all your import paths and file references relative to your main config file.
${env:ENV_VAR_NAME}Is substituted with the value of the $ENV_VAR_NAME environment variable. For example ${env:USER} is replaced by your Unix user name.
${stdpath:Location}Is substituted with the platform's value of the corresponding standard location for Location. For example, ${stdpath:TempLocation} is replaced by /tmp on Unix; unless configured otherwise by your system administrator.

If an option is specified in more than one place: either on the command line and the config files, or across multiple config files, the final value is resolved based on these rules:

  • Options are parsed from all the config files available, in the order in which they appear on the command line. Values are overridden by config files, as they are loaded.
  • Options that are specified directly via the command line always override values in any config file.
  • There is one exception: options that expect a list of values, such as -I or ui/importPaths. In this case, all values, regardless of where they are specified, are merged into one single, final list.
Command Line
[Config Key]
TypeDescription
(first non-option)
[ui/mainQml]
stringThe main QML file.
--helpboolPrints the supported options and exits.
--versionboolPrints the current version of the application manager and exits.
--build-configboolPrints the build configuration of the application manager in YAML format and exits.
--config-file or -carray<string>Loads configuration settings from a set of files. You can use more than one config file, for example, to split the configuration cleanly, into a device specific and a UI specific part. All the config files' content are merged in the order in which they appear on the command line: keys that didn't appear in an earlier config value are taken as is; duplicate keys are merged according to the following algorithm:
  1. Scalar values overwrite earlier config values.
  2. Lists are appended to the content from earlier lists.
  3. Maps are merged with earlier maps, recursively on a key-by-key basis, according to rules 1 and 2.

The application manager saves the result of parsing and evaluating all the configuration files into a cache. This cache is loaded on subsequent starts, if the exact set of config files is used, unchanged.

(default: /opt/am/config.yaml)

--no-config-cacheboolDisables the caching functionality for the configuration files: the cache is neither read from or written to.
--clear-config-cacheboolAlthough the application manager should detect if the configuration file cache is out of sync, you can force-clear the cache on startup with this option.
--option or -oYAMLUse this option to set or overwrite parts of your config files from the command line. This option can be specified multiple times and its values are evaluated the same way as the content of config files specified via -c. The evaluation order is after the configuration files, but before more specific, direct options such as --fullscreen (which can be rewritten as -o 'ui: { fullscreen: no }').
--database
[applications/database]
stringTo decrease the startup time of the System UI, its application database can be cached in a file. This way, in subsequent startups, the System UI doesn't have to scan and parse the info.yaml files for the applications installed, all over again. This option specifies the path for this cache file. (default: empty/disabled)
--recreate-database or -rboolIgnores any pre-existing database cache and creates a new one by (re)scanning all info.yaml files in builtin-apps-manifest-dir and installed-apps-manifest-dir. (default: false)
--builtin-apps-manifest-dir
[applications/builtinAppsManifestDir]
stringThe base directory for built-in application manifests; you can also specify multiple directories as a list.
--installed-apps-manifest-dir
[applications/installedAppsManifestDir]
stringThe base directory for installed application manifests. This option must be specified if you want to install new applications; otherwise only the built-in ones are available. (default: empty/disabled)
--app-image-mount-dir
[applications/appImageMountDir]
stringThe base directory where application images are mounted to. (defaults: /opt/am/image-mounts)
--dbusstringRegisters the ApplicationManager, ApplicationInstaller, NotificationManager, and WindowManager on the specified D-Bus: can be a full D-Bus bus specification string, session, system, auto (default), or none (for no registration at all).

Use the auto keyword on the desktop or during development only. This keyword implies that the application manager tries to start a private session bus and uses that bus if successful. Otherwise, it results in no registration at all, which is equivalent to none.

On production systems, you may want to put the application manager on the system bus, where you can set detailed security policies using standard D-Bus mechanisms, while keeping the NotificationManager on the session bus. See the more advanced config-file optiondbus below.

Note: As of Qt 5.13, the new auto keyword replaces the old --start-session-dbus flag.

[dbus]map<object>Allows for more fine-grained control over D-Bus registrations and function call policies. Every key (with one exception - see next) in this map corresponds to the D-Bus interface name you want to configure (io.qt.ApplicationManager, io.qt.ApplicationInstaller, io.qt.WindowManager, and org.freedesktop.Notifications). If such a key is present, it takes precedence over the dbus command line option. Each key's value is a D-Bus specification object.
--fullscreen
[ui/fullscreen]
boolDisplay in full-screen. (default: false)
--no-fullscreenboolOverride full-screen setting in the System UI's config file. Useful for development on the desktop. (default: false)
[ui/windowIcon]stringIf set, the given image file is used as a window icon for all application manager windows. This option is only useful for development and takes effect on Windows, macOS, and Linux/X11.
-I
[ui/importPaths]
array<string>Adds additional QML import paths to the System UI.
[ui/pluginPaths]array<string>Adds additional Qt plugin paths to the System UI.
[ui/style]stringIf set, the given style is used by QtQuickControls 2.
[plugins]map<array<string>>A string-to-string-list map that defines plugins that the application manager should load. The value must be a single plugin or a list of plugin library file path names. Currently the only valid keys are startup and container:
[systemProperties]objectExports user-defined properties (key/value pairs) to the System UI and applications. This field can only have the following children, that control access to the actual properties: private, protected, and public; other children are ignored. Properties under one of these access tags can be freely chosen and can also be nested. These properties are exposed as ApplicationManager::systemProperties to the System UI and as ApplicationInterface::systemProperties to all QML applications:
  • The System UI has access to public, protected, and private properties.
  • Built-in applilcations have access to public and protected properties.
  • Installed (third party) applications have access to public properties only.

Private keys overwrite identical protected and public keys; protected keys overwrite identical public keys. The properties are converted to QVariantMaps, but the application manager won't interpret them in any way. Non-QML applications can access this data via the $AM_RUNTIME_SYSTEM_PROPERTIES environment variable, as a YAML snippet.

--verboseboolEnables verbose output. All logging categories and message types are enabled with the exception of some Qt internal debug messages; logging-rules is ignored.

Note: Logging rules provided via the QT_LOGGING_RULES environment variable still prevails. For more control over the logging output, see logging-rules below.

--slow-animationsboolRuns all animations in slow motion. (default: false)
--load-dummydata
[ui/loadDummyData]
boolLoads QML dummy data into the System UI, similar to qmlscene and qml.
--no-security
[flags/noSecurity]
boolDisables all security related checks. Use this option in a development setup only; never in production. (default: false)
--development-mode
[flags/developmentMode]
boolAllows the installation of packages that only come with a valid developer signature. (default: false)
--no-ui-watchdog
[flags/noUiWatchdog]
boolDisables detecting UI applications that have hung (for example, via Wayland's ping/pong mechanism). (default: false)
--force-single-process
[flags/forceSingleProcess]
boolForces single-process mode even on a Wayland-enabled build. (default: false)
--force-multi-process
[flags/forceMultiProcess]
boolForces multi-process mode; exits immediately if this is not possible. (default: false)
--single-appstringRuns the application manager with a single application only (ignoring the database). In this mode, the application manager can act as a qmlscene or qml replacement. The argument is the path to info.yaml. Aliases (info-*.yaml) are also loaded from the given path.
--logging-rule
[logging/rules]
array<string>Adds standard Qt logging rules - see the QLoggingCategory documentation for the required format. Application manager specific logging categories are described in Logging and Debugging.
[logging/messagePattern]stringIf provided, used as the Qt message pattern. For more information about the format, see qSetMessagePattern().
[logging/useAMConsoleLogger]boolAlways use the application manager specific logging function, which enables colored console output. If no value or an invalid value is provided, the logging function is only used when messagePattern isn't set.
[logging/dlt/id]stringIf provided, it is used as the automotive DLT application ID. The size is limited to four characters, additional characters are discarded.

Note: The default ID, "PCAM", is used until this configuration option has been applied.

[logging/dlt/description]stringIf provided, it is used as the automotive DLT application description. This allows to augment the short DLT application ID with a more verbose definition.

Note: A default description is used until this configuration option has been applied.

--no-dlt-loggingboolDisables logging using automotive DLT. This option is especially useful when no dlt-daemon is running currently; otherwise the processes hang on exit for a while to send the logs.
--qml-debugboolEnables QML Debugging/Profiling. For more information, see Logging and Debugging.
[installationLocations]array<object>The definition of installation locations available on the system; an array of Installation Locations objects.
[runtimes]map<object>This option can be used to specify options for runtimes, as a map of key-value pairs. The key is the runtime's name; the value is interpreted by the respective runtime implementation. For more information, see Runtime Configuration.
[containers]map<object>This option can be used to specify options for containers, as a map of key-value pairs. The key is the container's name; the value is interpreted by the respective container implementation. For more information, see Containers.
[quicklaunch/idleLoad]realThis is a system load value between 0 and 1. The application manager does not start a new quick launcher, as long as the system's idle load is higher than this value. (default: 0)
[quicklaunch/runtimesPerContainer]intSpecifies how many quick launchers should always be ready for all active container/ runtime combinations. (default: 0)

Note: Values bigger than 10 are ignored, since this does not make sense and could also potentially freeze your device if you have a container plugin where instantiation is expensive, resource-wise.

--wayland-socket-namestringA filesystem name for the Wayland socket that should be used when creating the compositor component. (default: auto-detected by libwayland-server, most likely wayland-0)

Note: You can only specify the name here, but not a path: Wayland will always create this socket in $XDG_RUNTIME_DIR. The compositor will fail to start if this directory is not writable or if the environment variable is not even set in the first place.

--disable-installer
[installer/disable]
boolDisables the installer sub-system at runtime completely. Another option would be to not even compile it in the first place, in the qmake step.
[installer/caCertificates] list<string>A list of file paths to CA-certifcates that are used to verify packages. For more details, see the Installer documentation.
[crashAction]objectSpecifies which actions to take, if the application manager is crashing. For more details, see Crash Action Specification.
[ui/opengl]objectLets you specify the required OpenGL version and/or profile. For more details, see OpenGL Specification.
[ui/iconThemeName] stringSpecifies which icon theme to use. See ui/iconThemeSearchPaths for details on how to add a path to a custom theme.
[ui/iconThemeSearchPaths] list<string>Adds additional icon theme search paths to the System UI and all apps. This option can be used to add a custom icon theme to the search path and load it by specifying ui/iconThemeName.

D-Bus Specification

These YAML objects describe both, which D-Bus interfaces are registered on, as well as access policies.

Config KeyTypeDescription
registerstringRegisters the interface on the specified D-Bus: can be either session, system, none, ~ (for no registration at all), or a full D-Bus bus specification string.
policymap<object>These optional access policies can be used instead of or in addition to the standard D-Bus policy configuration. The keys into this map are the undecorated D-Bus function names, such as startApplication. When a key is specified, the corresponding function's access policy is deny, until you add allow criterias -- all of which are AND-ed together.

The code snippet below shows a simple example, that only allows applications with the appstore capability, running with user ID 1000 to call the installer's startPackageInstallation function, while preventing anyone to remotely call acknowledgePackageInstallation:

...
dbus:
  io.qt.ApplicationInstaller:
    register: 'session'
    policy:
      startPackageInstallation:
        uids: [ 1000 ]
        capabilities: [ 'appstore' ]
      acknowledgePackageInstallation: null
...

Only the public D-Bus interfaces of the application manager can be configured this way. The names of these available interfaces are as follows:

InterfaceCorresponding QML class
io.qt.ApplicationManagerApplicationManager
io.qt.ApplicationInstallerApplicationInstaller
io.qt.WindowManagerWindowManager
org.freedesktop.NotificationsNot application manager specific - this interface adheres to the freedesktop.org specification

Installation Locations

The installationLocations YAML field is a list of YAML objects, very similar to ApplicationInstaller::getInstallationLocation.

Config KeyTypeDescription
idstringThe installation location ID that is used as the handle for all other ApplicationInstaller function calls. The id consists of a type and index field, concatenated with a single dash. For example, removable-0.

Valid values for type are internal and removable.

In case there is more than one installation location for the same type of device, this zero-based index is used for disambiguation. For example, two SD card slots will result in the IDs removable-0 and removable-1. Otherwise, the index is always 0.

isDefaultboolOnly one installation location can be the default location, which must be mounted and accessible at all times. This location can be used by a UI application to get a sensible default for the installation location that it needs to pass to startPackageInstallation().
installationPathstringThe absolute file system path to the base directory where applications are installed.
documentPathstringThe absolute file system path to the base directory where per-user document directories are created. This entry can either be located on this device, or it can be the same as the documentPath of the master installation location.
mountPointstringOnly required for removable installation location: The absolute file system path to the mount-point of the device, where installationPath is located.

Runtime Configuration

The runtime configuration sub-objects are specific to the actual runtimes, so the table below has an additional column specifying which runtime a configuration option applies to:

Config KeyRuntimesTypeDescription
environmentVariablesnative, qmlmap<string>A simple string-to-string map that describes the environment variables that should be set when spawning the runtime process. To remove a variable from the default environment, give it a null value.
importPathsqmlarray<string>Adds additional QML import paths for apps started via this runtime.
pluginPathsqmlarray<string>Adds additional Qt plugin paths for apps started via this runtime.
pluginsqmlmap<array<string>>A string-to-string-list map that defines plugins that the QML runtime should load. The value must be a single plugin or a list of plugin library file path names. Currently the only valid key is startup:
  • startup: this plugin must implement the StartupInterface. The QML runtime calls the function hooks on application startup.
quicklaunchQmlqmlstringA QML source file that is loaded when a quick launcher is started; but not when an application is started directly. Providing this file is only useful, if quicklaunch/runtimesPerContainer > 0. This option can be used to improve subsequent startup performance of the actual application, such as by importing and hence preloading common application plugins and instantiating costly singletons. Generally, creating other objects is not useful as the created component is immediately deleted again. For the same reason, visual items should not be created. Always keep in mind that everything included in this file is loaded into all applications that use the QML runtime.
loadDummyDataqmlboolLoads QML dummy-data into the app, just like qmlscene and qml would. (default: false)
backgroundColorqmlstringIf set, the main window of the app gets this color set as the default clear color. This option also gives the surface an 8-bit alpha buffer.
quitTimeqmlintDefines the grace period in milliseconds, that an application is given for shutting down. This is the time limit between receiving the quit() signal and responding with acknowledgeQuit(). (default: 250)
crashActionqmlobjectSpecifies which actions to take, if a QML client application is crashing. See Crash Action Specification for more information.

Crash Action Specification

These sub-objects specify which actions to take, if the application manager or QML runtimes are crashing.

Note: All of these actions only work on Linux.

The following conditions are handled:

  • Uncaught exceptions. Exceptions derived from std::exception also show details on what() occurred.
  • SIGSEGV
  • SIGABRT
  • SIGBUS
  • SIGILL
  • SIGFPE
  • SIGPIPE
Config KeyTypeDescription
printBacktraceboolTries to print a readable backtrace, using the primitive backtrace functionality from glibc, unless libbacktrace was enabled at configure time (default: true).
printQmlStackboolTries to print a readable QML stack trace. Similar to printBacktrace above, but prints the current QML function stack when the crash occurred. (default: true)
dumpCoreboolEnds the process via abort instead of _exit. Dumps a core file, depending on your kernel configuration. (default: true)
waitForGdbAttachintSpecifies a timeout in seconds while the crashed program is being held in the stopped state, waiting for a debugger to attach. Any value <= 0 skips this step. (default: 0)

OpenGL Specification

The opengl sub-object lets you specify the required OpenGL version and/or profile.

Config KeyTypeDescription
desktopProfilestringWhen running on a desktop, set this value to either core or compatibility to request a non-default OpenGL profile. If you do not specify anything here, Qt uses the default settings for this platform. OpenGL ES has no support for profiles, so this setting is ignored on platforms using OpenGL ES.

Note: Be aware that this is just a request. The application manager outputs a warning, if the requested profile doesn't match the actual profile.

esMajorVersionintWhen set, the application manager requests the specified OpenGL ES major version. On the desktop, the given GLES version is transparently mapped to the corresponding desktop GL version. The current mapping table is as follows:
  • 2.0 → 2.1
  • 3.0 → 4.3
  • 3.1 → 4.5
  • 3.2 → 4.6

Make sure to specify either both options: esMajorVersion and esMinorVersion; or none at all.

Note: Be aware that this is just a request. The application manager outputs a warning, if the requested version doesn't match the actual version.

esMinorVersionintWhen set, the application manager requests the specified OpenGL ES minor version. For more information, see esMajorVersion above.

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