Configuration

Introduction

You can configure the application manager through configuration (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.

Variable Substitution

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:

Type	Description
`${CONFIG_DIR}`	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 config files. This variable was named `${CONFIG_PWD}` in the past and that old name is of course still accepted as well.	`${EXECUTABLE_DIR}`	Is substituted with the absolute path to the current executable that runs this process. This can be the vanilla `appman` binary or a custom appman binary used in your specific project.
`${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.

Multiple Values

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.

Note: 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.

Time Duration Values

Starting with version 6.8, all time duration values should be specified with a unit suffix. The following units are supported: h, min, s, ms and us. Fields that have existed before 6.8 still accept values without a unit suffix, but it is recommended to upgrade all time durations to use the new syntax. In addition, a zero time duration can also be specified as off.

Example

A very minimalistic am-config.yaml example would be something like this, which defines the main qml entry point and two import paths:

Main Configuration

formatVersion: 1
formatType: am-configuration
---
ui:
  mainQml: "${CONFIG_DIR}/main.qml"
  importPaths: [ "${CONFIG_DIR}/imports/shared", "${CONFIG_DIR}/imports/sysui" ]

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	list<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 rules: Scalar values overwrite earlier config values. Lists are appended to the content from earlier lists. 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. In case the given argument is a directory, all files with a `.yaml` extension will be loaded from that directory in alphabetical order (ASCII sort order, non-recursive).
--no-cache	bool	Disables the caching functionality for the configuration files and the application database : the caches are neither read from or written to. (default: false)
--clear-cache	bool	Although the application manager should detect if the configuration file and application database caches are out of sync, you can force-clear the caches on startup with this option. The old options `--clear-config-cache`, `-r`, and `--recreate-database` are also still supported and do also - despite their names - clear both caches. (default: false)
--option or -o	YAML	Use 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 }'`).
--instance-id [`instanceId`]	string	Assign a name to this application manager instance. Only useful if you are running multiple instances at the same time and you need to address them via the appman-controller tool. A unique number is appended to this id to make it possible to disambiguate between instances with the same id. (default: appman)
--database [`applications/database`]	string	Deprecated and ignored. The application database will transparently be cached - see also the `--clear-cache` and `--no-cache` options.
--recreate-database or -r	bool	Deprecated. These options were necessary for the application manager to react on changes to the application manifest files, but this is not needed anymore. For backward compatibility these options do map to the `--clear-cache` option, which will clear both the configuration and application database cache. (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.
--installation-dir [`applications/installationDir`]	string	The base directory for package installations. This option must be specified if you want to install a new package; otherwise only the built-in ones are available. (default: empty/disabled)
--document-dir [`applications/documentDir`]	string	The base directory for per-package document storage directories. (default: empty/disabled) Please note, that if you do not set a `documentDir` here, no per-application document directories will be created when installing new packages.
[`applications/installationDirMountPoint`]	string	If set, package database loading will be delayed until the specified mount point has been mounted. (default: empty/disabled)
--dbus	string	Registers the ApplicationManager, PackageManager, NotificationManager, and WindowManager on the specified D-Bus. This 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 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.PackageManager`, `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`]	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 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`]	list<string>	Adds additional QML import paths to the System UI.
[`ui/pluginPaths`]	list<string>	Adds additional Qt plugin paths to the System UI.
[`ui/style`]	string	If set, the given style is used by QtQuickControls 2.
[`ui/resources`]	list<string>	Takes a list of Qt resource files (.rcc) or libraries that have resources compiled-in and registers them within the System UI process. Resources can be accessed with the ":" or "qrc://" file path prefix.
[`plugins`]	map<list<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`: `startup`: this plugin must implement the StartupInterface. The QML runtime calls the function hooks on application startup. `container`: this plugin must implement the ContainerInterface (see Containers).
[`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 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.
--verbose	bool	Enables 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-animations	bool	Runs all animations in slow motion. (default: false)
--load-dummydata [`ui/loadDummyData`]	bool	Deprecated. 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 option 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)
[`flags/allowUnsignedPackages`]	bool	Allows the installation of packages that have no signature at all. Only use this in production, if you are verifying packages by other means, while also limiting the access to the installer API. (default: false)
[`flags/allowUnknownUiClients`]	bool	If set, the Wayland compositor will accept surfaces from clients that have not been started by the application manager. (default: false)
--no-ui-watchdog [`flags/noUiWatchdog`]	bool	Deprecated and ignored (replaced by Watchdog functionality). Disables detecting UI applications that have hung (for example, via Wayland's ping/pong mechanism). (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; exits 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` or `qml` replacement. The argument is the path to `info.yaml`. Aliases (`info-*.yaml`) are also loaded from the given path.
--log-instant	bool	Causes all logging messages to be printed right away at start-up. Usually, the logging output is deferred until the logging configuration (e.g. logging rules) is known. Expect different output and format at start-up.
--logging-rule [`logging/rules`]	list<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`]	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 any non-boolean value is provided (preferably the string `auto`), the logging function is only used when `messagePattern` isn't set. (default: `auto`)
[`logging/dlt/id`]	string	If 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, "QTAM", is used until this configuration option has been applied.
[`logging/dlt/description`]	string	If 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.
[`logging/dlt/longMessageBehavior`]	string	Configures how very long messages (more than ~1000 characters) should be handled when using automotive DLT. The default behavior is to truncate the message to the maximum possible size. Other options are `split` to cut the message into several smaller messages, `pass` to forward it as-is to DLT or `truncate` to explicitly request the default behvior.
--no-dlt-logging	bool	Disables 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-debug	bool	Enables QML Debugging/Profiling. For more information, see Logging and Debugging.
[`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. There is one special key named `additionalLaunchers`: the value is an array of `id` strings, and all these ids are registered as custom runtimes. A corresponding `appman-launcher-<id>` executable is expected to be available when launching apps based on the respective runtime.
[`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`]	real	This 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`]	int	Specifies how many quick launchers should always be ready for any container/runtime combination. (default: 0) There are different ways to set this value: A single integer value, which will apply to all possible container/runtime combinations. A mapping from container IDs to an integer value, which will apply to all possible runtime IDs within the respective container. A mapping from container IDs to a mapping from runtime IDs to an integer value, which will apply only to the respective container/runtime combination. Approach 2 and 3 can be freely mixed, with the special wildcard ID `""` denoting "any container ID" or "any runtime ID". 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.
[`quicklaunch/failedStartLimit`]	int	Any quick launch container/runtime combination that fails to successfully start more often than `failedStartLimit` within `failedStartLimitIntervalSec`, will get disabled. (default: 5)
[`quicklaunch/failedStartLimitIntervalSec`]	duration	A time interval with seconds precision, see `failedStartLimit` above. (default: 10s)
--wayland-socket-name [`wayland/socketName`]	string	A filesystem name for the Wayland socket that should be used when creating the compositor component. (default: auto-detected by the application manager, most likely `qtam-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. See `wayland/extraSockets` below for a way to circumvent this limitation.
[`wayland/extraSockets`]	list<object>	A list of additional sockets that are added to the Wayland server. Each object in the list consists of the following fields `path`: the absolute path of the socket. `permissions`: the numeric permission of the socket - can be given in octal, e.g. `0640`. `userId`: the numeric uid of the socket. `groupId`: the numeric gid of the socket. Only `path` is required, while the other fields are optional and fall back to QLocalServer defaults. If the application manager is runing under `sudo` or with setuid-root, it will use its extended privileges to apply the optional `permissions`, `userId` and `groupId` settings.
--disable-installer [`installer/disable`]	bool	Deprecated and ignored. If you do not want to have any installer functionality then disable it at configure time.
[`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. For more details, see Crash Action Specification.
[`ui/opengl`]	object	Lets you specify the required OpenGL version and/or profile. For more details, see OpenGL Specification.
[`ui/iconThemeName`]	string	Specifies 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.
[`intents/disable`]	bool	Deprecated and ignored. As of version 6.8, the intent sub-system is always enabled.
[`intents/timeouts`]	object	Lets you specify the processing timeouts used in the intent sub-system. For more details, see Intent Timeout Specification.
[`watchdog`]	object	Configures the built-in watchdog. See Watchdog for more information.

D-Bus Specification

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

Config Key	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 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. Due to the way D-Bus properties are implemented, these policy only apply to methods, but not to property getters and setters.

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.PackageManager:
    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:

Interface	Corresponding QML class
`io.qt.ApplicationManager`	ApplicationManager
`io.qt.PackageManager`	PackageManager
`io.qt.WindowManager`	WindowManager
`org.freedesktop.Notifications`	Not application manager specific - this interface adheres to the freedesktop.org specification

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 Key	Runtimes	Type	Description
`environmentVariables`	native, qml	map<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.
`importPaths`	qml	list<string>	Adds additional QML import paths for apps started via this runtime.
`pluginPaths`	qml	list<string>	Adds additional Qt plugin paths for apps started via this runtime.
`plugins`	qml	map<list<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.
`resources`	qml	list<string>	Takes a list of Qt resource files (.rcc) or libraries that have resources compiled-in and registers them within each QML runtime. Consequently, all running QML applications will include these resources. The resources can be accessed with the ":" or "qrc://" file path prefix.
`quicklaunchQml`	qml	string	A 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.
`loadDummyData`	qml	bool	Deprecated. Loads QML dummy-data into the app, just like `qmlscene` and `qml` would. (default: false)
`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 details on what() occurred.
SIGSEGV
SIGABRT
SIGBUS
SIGILL
SIGFPE
SIGPIPE
SIGQUIT
SIGSYS

Config Key	Type	Description
`printBacktrace`	bool	Tries to print a readable backtrace. On Linux, it uses the primitive backtrace functionality from glibc, unless `libbacktrace` was enabled at configure time. On Windows, backtraces are only printed if `stackwalker` was enabled at configure time. (default: true).
`printQmlStack`	bool	Tries to print a readable QML stack trace. Similar to `printBacktrace` above, but prints the current QML function stack when the crash occurred. (default: true)
`dumpCore`	bool	Please note that the system's configuration determines if and where core dumps are saved: see `man 5 core`. If set to `false`, Unix core dumps are completely disabled. (default: true)
`waitForGdbAttach`	duration	Specifies a time duration with seconds precision: it is the time a crashed program is being held in the stopped state, waiting for a debugger to attach. Any value `<= 0` skips this step. (default: 0s)
`stackFramesToIgnore/onCrash`	int	The number of stack frames that should not be printed in a backtrace. This is to avoid having both the operating system's and the application manager's internal handling routines show up in the backtrace. (default: sensible values for the latest XCode and latest gcc versions)
`stackFramesToIgnore/onException`	int	The number of stack frames that should not be printed in a backtrace. This is to avoid having both the C++ library's and the application manager's internal handling routines show up in the backtrace. (default: sensible values for the latest XCode and latest gcc versions)

Intent Timeout Specification

The intents/timeouts sub-object lets you specify the exact timeouts with milli-seconds precision for the asynchronous IPC used to implement the intents mechanism. Any intent whose lifetime exceeds a timeout for the stages shown below is canceled by the system and an error reply is sent back to the original sender. Setting any of the timeout values to 0 or a negative number disables the timeout handling for that specific stage.

Config Key	Type	Description
`disambiguation`	duration	The time interval in which a disambiguation decision for an intent has to be made in the System UI. (default: 10s)
`startApplication`	duration	The time interval in which an application that should handle an intent request is supposed to be started - of course, only if it is not already running. (default: 3s)
`replyFromApplication`	duration	The time interval in which the handling application needs to acknowledge the receipt of an intent request. For QML applications, this is done in IntentHandler::requestReceived. (default: 5s)
`replyFromSystem`	duration	The time interval after which the complete handling of a single intent needs to be finished: this starts when actually creating the intent in the requesting application, going through the server to the handling application and then returning the (error) result back from the handling to the requesting application. Note: It makes sense that this timeout value is slightly bigger than the sum of the previous three timeout values described above: all the other timeouts are sub-steps towards the completion of an intent request, while this timeout represents the whole process. Making it slightly bigger than the sum accounts for processing and communication overhead that is not part of the individual sub timeouts. (default: 20s)

Please be aware that due to the asynchronous nature of the intent delivery, an intent might be canceled by the system because it ran into either a replyFromApplication or replyFromSystem timeout, although the receiver still received and processed it.

OpenGL Specification

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

Config Key Type Description

Config Key	Type	Description
`desktopProfile`	string	When 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.
`esMajorVersion`	int	When 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.
`esMinorVersion`	int	When set, the application manager requests the specified OpenGL ES minor version. For more information, see `esMajorVersion` above.

desktopProfile

string

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

esMajorVersion

int

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

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

© 2024 The Qt Company Ltd. 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.