Qt Documentation

Configuration

Main Configuration

The application manager can be configured through config files and the command line. The currently supported command-line options can always be displayed by running appman --help. Some of these options can also be set via config files, which in itself are referenced on the command-line with the --config-file <filename> option.

The config file is a YAML file, consisting of exactly one object and it supports a subset of the command-line options.

Any value that starts with the magic string ${CONFIG_PWD} will have this magic string replaced with the absolute path to the config file where it appears in - this makes it very easy to have all your imports paths and file references relative to your main config file.

Command Line Config key	Type	Description
(first non-option) ui/mainQml	string	The main QML file.
--help -	bool	Prints the supported options and exits.
--version -	bool	Prints the current version of the application manager and exits.
--build-config -	bool	Prints the build configuration of the application manager in YAML format and exits.
--config-file or `-c` -	array<string>	Loads configuration settings from a set of files. Using more than one config file could be used to cleanly split the configuration into a device specific and a UI specific part. All the config files' content will be merged in the order they appear on the command line: keys that did not appear in an earlier config value are taken as is; duplicate keys are merged according to the following algorithm: scalar values simply overwrite earlier config values. lists get appended to earlier lists' content. maps will be merged with earlier maps recursively on a key-by-key basis, according to rules 1 and 2. The application manager will save the result of parsing and evaluating all the configuration files into a cache. This cache is loaded on subsequent starts if the exact same set of config files is used unchanged. (default: `/opt/am/config.yaml`)
--no-config-cache -	bool	Disables the caching functionality for the configuration files: the cache is neither read from or written to.
--clear-config-cache -	bool	Although 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 `-o` -	YAML	Use this option to set or override parts of your config files from the command-line. This option can be given multiple times and its values are evaluated the same way as the content of configuration files specified via `-c`. The evaluation order is after the configuration files, but before more specific, direct options like e.g. `--fullscreen` (which could be rewritten as `-o 'ui: { fullscreen: no }'`).
--database applications/database	string	To decrease the start up time of the System UI, its application database can be cached in a file so that in subsequent start ups it doesn't have to scan and parse the `info.yaml` files of installed applications all over again. This option specifies the filepath of such cache file. (default: empty/disabled)
--recreate-database or `-r` -	bool	Ignores any preexisting 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	string	The base directory for built-in application manifests. You can also specify multiple directories as a list.
--installed-apps-manifest-dir applications/installedAppsManifestDir	string	The base directory for installed application manifests. This must be specified if you want to install new applications, otherwise only the built-in ones will be available. (default: empty/disabled)
--app-image-mount-dir applications/appImageMountDir	string	The base directory where application images are mounted to. (defaults: `/opt/am/image-mounts`)
--dbus -	string	Register the ApplicationManager, ApplicationInstaller, NotificationManager and WindowManager on the specified D-Bus: can be either `session`, `system`, `none` (for no registration at all) or a full D-Bus bus specification string. (default: `session` on Linux, `none` on all other platforms) Note: On production systems, you most likely 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 option `dbus` below.
- 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` or `org.freedesktop.Notifications`). If such a key is present, it will take precedence over the command-line option `dbus`. Each key's value is a D-Bus specification object.
--start-session-dbus -	bool	Start a private session bus instead of using an existing one.
--fullscreen ui/fullscreen	bool	Display in full-screen. (default: false)
--no-fullscreen -	bool	Override full-screen setting in the System UI's config file. Useful for development on the desktop. (default: false)
- ui/windowIcon	string	If set, the given image file will be used as a window icon for all application manager windows. This setting is only useful for development and will only take effect on Windows, macOS and Linux/X11.
-I ui/importPaths	array<string>	Adds additional QML import paths to the System UI.
- ui/style	string	If set, the given style will be 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 list of plugin library file path names. A single plugin will also be accepted. Currently the only valid key is `startup`. The plugin itself must implement the StartupInterface. The application manager will call the function hooks during startup of the System UI.
- systemProperties	object	Exports 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 will be ignored). Properties under one of the access tags can be freely chosen and can also be nested. The 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 will overwrite identical protected and public ones and protected keys will overwrite identical public ones. The properties will just be converted to QVariantMaps, but the application manager will not interpret them in any way. Non-QML applications can access this data via the environment variable `$AM_RUNTIME_SYSTEM_PROPERTIES` as a YAML snippet.
--verbose -	bool	Enable verbose output. All logging categories and message types will be enabled with the exception of some Qt internal debug messages; `logging-rules` will be ignored. Note that logging rules provided via the QT_LOGGING_RULES environment variable will still prevail. For more control over the logging output, see `logging-rules` below.
--slow-animations -	bool	Run all animations in slow motion. (default: false)
--load-dummydata ui/loadDummyData	bool	Loads QML dummy data into the System UI, similar to `qmlscene` and `qml`.
--no-security flags/noSecurity	bool	Disables all security related checks. Use this in a development setup only; never in production. (default: false)
--development-mode flags/developmentMode	bool	Allows the installation of packages that only come with a valid developer signature. (default: false)
--no-ui-watchdog flags/noUiWatchdog	bool	Disables detecting hung UI applications (e.g. via Wayland's ping/pong). (default: false)
--force-single-process flags/forceSingleProcess	bool	Forces single-process mode even on a Wayland enabled build. (default: false)
--force-multi-process flags/forceMultiProcess	bool	Forces multi-process mode. Will exit immediately if this is not possible. (default: false)
--single-app -	string	Runs the application manager with a single application only (ignoring the database). In this mode, the application manager can act as a `qmlscene` / `qml` replacement. The argument is the path to `info.yaml`. Aliases (`info-*.yaml`) will also be 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 listed in Logging and Debugging.
- logging/messagePattern	string	If provided, used as the Qt message pattern. For more information about the format see qSetMessagePattern().
- logging/useAMConsoleLogger	bool	Always 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	string	If provided, it will be used as the automotive DLT application id. The size is limited to four characters, additional characters will be discarded. Note that the default id "PCAM" is used until this configuration option has been applied.
- logging/dlt/description	string	If provided, it will be used as the automotive DLT application description. This allows to augment the short DLT application id with a more verbose definition. Note that a default description is used until this configuration option has been applied.
--no-dlt-logging -	bool	Disables logging using automotive DLT. This is especially useful when currently no dlt-daemon is running as otherwise the processes will hang at exit for some time to send the logs.
--qml-debug -	bool	Enables QML Debugging/Profiling. See Logging and Debugging for more information.
- installationLocations	array<object>	Definition of available installation locations on the system. This is an array of Installation Locations objects.
- runtimes	map<object>	This can be used to specify options for runtimes - the key in this map is the runtime's name and the value is interpreted by the respective runtime implementation. See below for specific information.
- containers	map<object>	This can be used to specify options for containers - the key in this map is the container's name and the value is interpreted by the respective container implementation. Containers for specific information.
- quicklaunch/idleLoad	real	This is a system-load value between `0` and `1`. The application manager will not start a new quick-launcher, as long as the idle-load of the system is higher than this value. (default: 0)
- quicklaunch/runtimesPerContainer	int	Specifies how many quick-launchers should always be ready for all active container/runtime combinations. (default: 0) Note: Values bigger than 10 will be ignored, since this does not make sense and could also potentially freeze your device if you have a container plugin were instantiation is expensive resource-wise.
--wayland-socket-name -	string	A 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` and will fail to start the compositor, if this directory is not writable or if the environment variable is not even set in the first place.
--disable-installer installer/disable	bool	Completely disables the installer sub-system at runtime. 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	object	Specifies which actions to take, if the application manager is crashing. See below for more information.
- ui/opengl	object	Gives you the possibility to specify the required OpenGL version and/or profile. See below for more information.
- ui/iconThemeName	string	Specifies which icon theme is used. See ui/iconThemeSearchPaths for 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 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.

Name	Type	Description
`register`	string	Registers 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.
`policy`	map<object>	These optional access policies can be used either 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.

A simple example, that only allows applications with the capability appstore, 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: ~
...

Installation Locations

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

Name	Type	Description
`id`	string	The installation location id that is used as the handle for all other ApplicationInstaller function calls. The `id` consists of the `type` and `index` field, concatenated by 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`.
`isDefault`	bool	Only 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().
`installationPath`	string	The absolute file system path to the base directory under which applications are installed.
`documentPath`	string	The absolute file-system path to the base directory under which 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.
`mountPoint`	string	Only 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:

Name	Runtimes	Type	Description
`environmentVariables`	native, qml	map<string>	A simple string-to-string map, describing the environment variables that should be set when spawning the runtime process. You can remove a variable from the default environment by giving it a null value.
`importPaths`	qml	array<string>	Add an additional QML import path for apps started via this runtime.
`plugins`	qml	map<array<string>>	A string-to-string-list map that defines plugins that the QML runtime should load. The value must be a list of plugin library file path names. A single plugin will also be accepted. Currently the only valid keys are `startup` and `container`: `startup`: this plugin must implement the StartupInterface. The QML runtime will call the function hooks during startup of an application. `container`: this plugin must implement the ContainerInterface (see Containers).
`quicklaunchQml`	qml	string	A QML source file that is loaded when a quick-launcher is started. It will not be loaded when an application is started directly. Providing this file is only useful, if quicklaunch/runtimesPerContainer > 0. It can be used to improve subsequent start-up performance of the actual application, e.g. by importing and hence preloading common application plugins and instantiating costly singletons. Creating other objects is generally useless as the created component will immediately be deleted again. For the same reason visual items should not be created. Always keep in mind that everything included in this file will be loaded into all applications that use the QML runtime.
`loadDummyData`	qml	bool	Loads QML dummy-data into the app (just like `qmlscene` and `qml` would). Defaults to `false`.
`backgroundColor`	qml	string	If 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.
`quitTime`	qml	int	Defines 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).
`crashAction`	qml	object	Specifies 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 the what() information.
SIGSEGV
SIGABRT
SIGBUS
SIGILL
SIGFPE
SIGPIPE

Name	Type	Description
`printBacktrace`	bool	Tries to print a readable backtrace. This type uses the primitive backtrace functionality from glibc, unless `libbacktrace` was enabled at configure time (default: true).
`printQmlStack`	bool	Tries to print a readable QML stack trace. This is similar to `printBacktrace` above, but prints the current QML function stack when the crash occurred (default: true).
`dumpCore`	bool	Ends the process via `abort` instead of `_exit`. This will dump a `core` file, depending on your kernel configuration (default: true).
`waitForGdbAttach`	int	Specifies a timeout in seconds while the crashed program is being held in the stopped state, waiting for a debugger to attach. Any value `<= 0` will skip this step (default: 0).

OpenGL Specification

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

Name Type Description

Name	Type	Description
`desktopProfile`	string	When running on a desktop, you can request a non-default OpenGL profile by setting this value to either `core` or `compatibility`. 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 will output a warning, if the requested profile does not match the actual profile.
`esMajorVersion`	int	When set, the application manager will request 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 either specify both `esMajorVersion` and `esMinorVersion` options; or none at all. Note: Be aware that this is just a request. The application manager will output a warning, if the requested version does not match the actual version.
`esMinorVersion`	int	When set, the application manager will request the specified OpenGL ES minor version. See `esMajorVersion` above for more information.

desktopProfile

string

When running on a desktop, you can request a non-default OpenGL profile by setting this value to either core or compatibility. 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 will output a warning, if the requested profile does not match the actual profile.

esMajorVersion

int

When set, the application manager will request 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 either specify both esMajorVersion and esMinorVersion options; or none at all.

Note: Be aware that this is just a request. The application manager will output a warning, if the requested version does not match the actual version.

esMinorVersion int When set, the application manager will request the specified OpenGL ES minor version. See esMajorVersion above for more information.

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