path: root/doc/configuration.qdoc

// Copyright (C) 2021 The Qt Company Ltd.
// Copyright (C) 2019 Luxoft Sweden AB
// Copyright (C) 2018 Pelagicore AG
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!

\page configuration.html
\ingroup qtappman
\ingroup qtappman-highlights
\title Configuration
\brief Configure the application manager through configuration (config) files and the command line.
\section1 Main Configuration

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

The config file is a \l{YAML syntax}{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 \c bash: \c ${VariableName}. There are different types of variables that can be
substituted this way:

\table
    \header
        \li Type
        \li Description
    \row
        \li \c ${CONFIG_PWD}
        \li 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.
    \row
        \li \c ${env:ENV_VAR_NAME}
        \li Is substituted with the value of the \c $ENV_VAR_NAME environment variable. For
            example \c ${env:USER} is replaced by your Unix user name.
    \row
        \li \c ${stdpath:Location}
        \li Is substituted with the platform's value of the corresponding \l
            {QStandardPaths::StandardLocation}{standard location} for \c Location. For example,
            \c ${stdpath:TempLocation} is replaced by \c /tmp on Unix; unless configured
            otherwise by your system administrator.
\endtable

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:

\list
    \li 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.
    \li Options that are specified directly via the command line always override values in any
        config file.
\endlist
\note There is one exception: options that expect a list of values, such as \c -I or
\c ui/importPaths. In this case, all values, regardless of where they are specified, are
merged into one single, final list.

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

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

\table 100%
    \header
        \li Command Line \br [\c {Config Key}]
        \li Type
        \li Description
    \row
        \li \b {(first non-option)}
            \br [\c ui/mainQml]
        \li string
        \li The main QML file.
    \row
        \li \b --help
        \li bool
        \li Prints the supported options and exits.
    \row
        \li \b --version
        \li bool
        \li Prints the current version of the application manager and exits.
    \row
        \li \b --build-config
        \li bool
        \li Prints the build configuration of the application manager in YAML format and exits.
    \row
        \li \b --config-file or \b -c
        \li array<string>
        \li 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:
            \list 1
                \li Scalar values overwrite earlier config values.
                \li Lists are appended to the content from earlier lists.
                \li Maps are merged with earlier maps, recursively on a key-by-key basis, according
                    to rules 1 and 2.
            \endlist

            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.
    \row
        \li \b --no-cache
        \li bool
        \li Disables the caching functionality for the configuration files and the application
            database : the caches are neither read from or written to.
            (default: false)
    \row
        \li \b --clear-cache
        \li bool
        \li 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 \c --clear-config-cache, \c -r, and \c --recreate-database are also still
            supported and do also - despite their names - clear both caches.

            (default: false)
    \row
        \li \b --option or \b -o
        \li YAML
        \li 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 -c. The evaluation order is after the
            configuration files, but before more specific, direct options such as \c --fullscreen
            (which can be rewritten as \c{ -o 'ui: { fullscreen: no }'}).
    \row
        \target instance-id
        \li \b --instance-id
            \br [\c instanceId]
        \li string
        \li Assign an unique 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
            \l{Controller}{appman-controller tool}.
    \row
        \li \b --database
            \br [\c applications/database]
        \li string
        \li Deprecated and ignored. The application database will transparently be cached - see also
            the \c --clear-cache and \c --no-cache options.
    \row
        \li \b --recreate-database or \b -r
        \li bool
        \li 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 \c --clear-cache option, which will clear both
            the configuration and application database cache.
            (default: false)
    \row
        \li \b --builtin-apps-manifest-dir
            \br [\c applications/builtinAppsManifestDir]
        \li string
        \li The base directory for built-in application manifests; you can also specify multiple
            directories as a list.
    \row
        \li \b --installation-dir
            \br [\c applications/installationDir]
        \li string
        \li The base directory for package installations. This option must be specified
            if you want to install new package; otherwise only the built-in ones are
            available. (default: empty/disabled)
    \row
        \li \b --document-dir
            \br [\c applications/documentDir]
        \li string
        \li The base directory for per-package document storage directories.
            (default: empty/disabled)

            Please note, that if you do not set a \c documentDir here, no per-application
            document directories will be created when installing new packages.
    \row
        \li [\c applications/installationDirMountPoint]
        \li string
        \li If set, package database loading will be delayed until the specified mount point has been mounted.
            (default: empty/disabled)
    \row
        \li \b --dbus
        \li string
        \li Registers the ApplicationManager, ApplicationInstaller, NotificationManager, and
            WindowManager on the specified D-Bus. This can be a full D-Bus bus specification string,
            \c session, \c system, \c auto (default), or \c none (for no registration at all).

            Use the \c 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
            \c none.

            On production systems, you may want to put the application manager on the \c 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\c dbus below.

    \row
        \li [\c dbus]
        \li map<object>
        \li 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 (\c io.qt.ApplicationManager,
            \c io.qt.ApplicationInstaller, \c io.qt.WindowManager, and \c org.freedesktop.Notifications).
            If such a key is present, it takes precedence over the \c dbus command line option.
            Each key's value is a \l{D-Bus specification} object.
    \row
        \li \b --fullscreen
            \br [\c ui/fullscreen]
        \li bool
        \li Display in full-screen. (default: false)
    \row
        \li \b --no-fullscreen
        \li bool
        \li Override full-screen setting in the System UI's config file. Useful for development on
            the desktop. (default: false)
    \row
        \li [\c ui/windowIcon]
        \li string
        \li 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.
    \row
        \li \b -I
            \br [\c ui/importPaths]
        \li array<string>
        \li Adds additional QML import paths to the System UI.
    \row
        \li [\c ui/pluginPaths]
        \li array<string>
        \li Adds additional Qt plugin paths to the System UI.
    \row
        \li [\c ui/style]
        \li string
        \li If set, the given style is used by QtQuickControls 2.
    \row
        \li [\c ui/resources]
        \li array<string>
        \li Takes a list of \l{The Qt Resource System}{Qt resource} files (.rcc) or libraries that
            have resources \l{Resource Collection Files}{compiled-in} and registers them within the
            System UI process. Resources can be accessed with the ":" or "qrc://" file path prefix.
    \row
        \li [\c plugins]
        \li map<array<string>>
        \li 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 \c startup and \c container:
            \list
                \li \c startup: this plugin must implement the StartupInterface. The QML runtime
                calls the function hooks on application startup.
                \li \c container: this plugin must implement the ContainerInterface
                (see \l Containers).
            \endlist
    \row
        \target system properties
        \li [\c systemProperties]
        \li object
        \li 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: \c private, \c protected, and \c 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:
            \list
                \li The System UI has access to public, protected, and private properties.
                \li Built-in applilcations have access to public and protected properties.
                \li Installed (third party) applications have access to public properties only.
            \endlist
            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 \c $AM_RUNTIME_SYSTEM_PROPERTIES environment variable, as a YAML
            snippet.
    \row
        \li \b --verbose
        \li bool
        \li Enables verbose output. All logging categories and message types are enabled with the
            exception of some Qt internal debug messages; \c 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 \c logging-rules below.
    \row
        \li \b --slow-animations
        \li bool
        \li Runs all animations in slow motion. (default: false)
    \row
        \li \b --load-dummydata
            \br [\c ui/loadDummyData]
        \li bool
        \li Loads QML dummy data into the System UI, similar to \c qmlscene and \c qml.
    \row
        \target no-security
        \li \b --no-security
            \br [\c flags/noSecurity]
        \li bool
        \li Disables all security related checks. Use this option in a development setup only;
            never in production. (default: false)
    \row
        \target development-mode
        \li \b --development-mode
            \br [\c flags/developmentMode]
        \li bool
        \li Allows the installation of packages that only come with a valid developer signature.
            (default: false)
    \row
        \li [\c flags/allowUnsignedPackages]
        \li bool
        \li 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)
    \row
        \li [\c flags/allowUnknownUiClients]
        \li bool
        \li If set, the Wayland compositor will accept surfaces from clients that have not been
            started by the application manager. (default: false)
    \row
        \li \b --no-ui-watchdog
            \br [\c flags/noUiWatchdog]
        \li bool
        \li Disables detecting UI applications that have hung (for example, via Wayland's ping/pong
            mechanism). (default: false)
    \row
        \li \b --force-single-process
            \br [\c flags/forceSingleProcess]
        \li bool
        \li Forces single-process mode even on a Wayland-enabled build. (default: false)
    \row
        \li \b --force-multi-process
            \br [\c flags/forceMultiProcess]
        \li bool
        \li Forces multi-process mode; exits immediately if this is not possible. (default: false)
    \row
        \li \b --single-app
        \li string
        \li Runs the application manager with a single application only (ignoring the database).
            In this mode, the application manager can act as a \c qmlscene or \c qml replacement.
            The argument is the path to \c info.yaml. Aliases (\c{info-*.yaml}) are also loaded
            from the given path.
    \row
        \li \b --log-instant
        \li bool
        \li 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.
    \row
        \li \b --logging-rule
            \br [\c logging/rules]
        \li array<string>
        \li Adds standard Qt logging rules - see the QLoggingCategory documentation for the
            required format. Application manager specific logging categories are described in
            \l {Logging and Debugging}.
    \row
        \li [\c logging/messagePattern]
        \li string
        \li If provided, used as the Qt message pattern. For more information about the format, see
            qSetMessagePattern().
    \row
        \li [\c logging/useAMConsoleLogger]
        \li bool
        \li 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.
    \row
        \li [\c logging/dlt/id]
        \li string
        \li 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, "PCAM", is used until this configuration option has been applied.
    \row
        \li [\c logging/dlt/description]
        \li string
        \li 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.
    \row
        \li [\c logging/dlt/longMessageBehavior]
        \li string
        \li 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 \c split to cut the message into several smaller
            messages, \c pass to forward it as-is to DLT or \c truncate to explicitly request the
            default behvior.
    \row
        \li \b --no-dlt-logging
        \li bool
        \li 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.
    \row
        \li \b --qml-debug
        \li bool
        \li Enables QML Debugging/Profiling. For more information, see \l {Logging and Debugging}.
    \row
        \li [\c installationLocations]
        \li array<object>
        \li The definition of installation locations available on the system. This is deprecated,
            since only a single installation location is supported now, defined by \c
            --installationDir or \c{applications/installationDir}.
    \row
        \li [\c runtimes]
        \li map<object>
        \li 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 \l {Runtime Configuration}.
            There is one special key named \c{additionalLaunchers}: the value is an array of \c id
            strings, and all these ids are registered as custom runtimes. A corresponding
            \c{appman-launcher-<id>} executable is expected to be available when launching apps
            based on the respective runtime.
    \row
        \li [\c containers]
        \li map<object>
        \li 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 \l {Containers}.
    \row
        \li [\c quicklaunch/idleLoad]
        \li real
        \li This is a system load value between \c 0 and \c 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)
    \row
        \li [\c quicklaunch/runtimesPerContainer]
        \li int
        \li Specifies 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.
    \row
        \li \b --wayland-socket-name
            \br [\c wayland/socketName]
        \li string
        \li 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
            \c qtam-wayland-0)
            \note You can only specify the name here, but not a path: Wayland will always create
                  this socket in \c{$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 \c wayland/extraSockets below for a way to circumvent this
                  limitation.
    \row
        \li [\c wayland/extraSockets]
        \li list<object>
        \li A list of additional sockets that are added to the Wayland server. Each object in the
            list consists of the following fields
            \list
                \li \c path: the absolute path of the socket.
                \li \c permissions: the numeric permission of the socket - can be given in octal, e.g. \c 0640.
                \li \c userId: the numeric uid of the socket.
                \li \c groupId: the numeric gid of the socket.
            \endlist
            Only \c path is required, while the other fields are optional and fall back to
            QLocalServer defaults.

            If the application manager is runing under \c sudo or with setuid-root, it will use
            its extended privileges to apply the optional \c permissions, \c userId and \c groupId
            settings.
    \row
        \li \b --disable-installer
            \br [\c installer/disable]
        \li bool
        \li Disables the installer sub-system at runtime completely. Another option would be to
            not even compile it in the first place, in the \l{config disable installer}{qmake step}.
    \row
        \li [\c installer/caCertificates]
            \target ca certificates
        \li list<string>
        \li A list of file paths to CA-certifcates that are used to verify packages. For more
            details, see the \l {Public Key Infrastructure} {Installer documentation}.
    \row
        \li [\c crashAction]
        \li object
        \li Specifies which actions to take, if the application manager is crashing. For more
            details, see \l{Crash Action Specification}.
    \row
        \li [\c ui/opengl]
        \li object
        \li Lets you specify the required OpenGL version and/or profile. For more details, see
            \l{OpenGL Specification}.
    \row
        \li [\c ui/iconThemeName]
            \target iconThemeName
        \li string
        \li Specifies which icon theme to use. See \l{iconThemeSearchPaths}{ui/iconThemeSearchPaths}
            for details on how to add a path to a custom theme.
    \row
        \li [\c ui/iconThemeSearchPaths]
            \target iconThemeSearchPaths
        \li list<string>
        \li 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
            \l{iconThemeName} {ui/iconThemeName}.
    \row
        \li [\c intents/disable]
        \li bool
        \li Disables the intent sub-system at runtime completely.
    \row
        \li [\c intents/timeouts]
            \target intentConfiguration
        \li object
        \li Lets you specify the processing timeouts used in the intent
            sub-system. For more details, see \l{Intent Timeout Specification}.

    \omit
    telnetPort and telnetAddress: these are configuring the Pelagicore proprietary telnet component
    applicationUserIdSeparation: this should be factored out into a container plugin
    \endomit
\endtable

\section1 D-Bus Specification

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

\table
\header
    \li Config Key
    \li Type
    \li Description
\row
    \li \c register
    \li string
    \li Registers the interface on the specified D-Bus: can be either \c session, \c system,
        \c none, \c ~ (for no registration at all), or a full D-Bus bus specification string.
\row
    \li \c policy
    \li map<object>
    \li 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 \c startApplication. When a key is specified, the corresponding function's access policy
        is \c deny, until you add \c 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.
\endtable

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

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

Only the public D-Bus interfaces of the application manager can be configured this way. The names
of these available interfaces are as follows:
\table
    \header
        \li Interface
        \li Corresponding QML class
    \row
        \li \c io.qt.ApplicationManager
        \li ApplicationManager
    \row
        \li \c io.qt.ApplicationInstaller
        \li ApplicationInstaller
    \row
        \li \c io.qt.WindowManager
        \li WindowManager
    \row
        \li \c org.freedesktop.Notifications
        \li Not application manager specific - this interface adheres to the
            \l {freedesktop.org specification}
\endtable

\section1 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:

\table
    \header
        \li Config Key
        \li Runtimes
        \li Type
        \li Description
    \row
        \li \c environmentVariables
        \li native, qml
        \li map<string>
        \li 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.
    \row
        \li \c importPaths
        \li qml
        \li array<string>
        \li Adds additional QML import paths for apps started via this runtime.
    \row
        \li \c pluginPaths
        \li qml
        \li array<string>
        \li Adds additional Qt plugin paths for apps started via this runtime.
    \row
        \li \c plugins
        \li qml
        \li map<array<string>>
        \li 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 \c startup:
            \list
                \li \c startup: this plugin must implement the StartupInterface. The QML runtime
                    calls the function hooks on application startup.
            \endlist
    \row
        \li \c resources
        \li qml
        \li array<string>
        \li Takes a list of \l{The Qt Resource System}{Qt resource} files (.rcc) or libraries that
            have resources \l{Resource Collection Files}{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.
    \row
        \li \c quicklaunchQml
        \li qml
        \li string
        \li 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
            \c 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 \b all applications that use the
            QML runtime.
    \row
        \li \c loadDummyData
        \li qml
        \li bool
        \li Loads QML dummy-data into the app, just like \c qmlscene and \c qml would.
            (default: false)
    \row
        \li \c backgroundColor
        \li qml
        \li string
        \li This option is deprecated and will be removed in the next release. Please use the
            ApplicationManagerWindow's \c color property instead.

    \row
        \li \c quitTime
        \li qml
        \li int
        \li Defines the grace period in milliseconds, that an application is given for shutting
            down. This is the time limit between receiving the
            \l{ApplicationInterface::quit()}{quit()} signal and responding with
            \l{ApplicationInterface::acknowledgeQuit()}{acknowledgeQuit()}. (default: 250)
    \row
        \li \c crashAction
        \li qml
        \li object
        \li Specifies which actions to take, if a QML client application is crashing. See
            \l{Crash Action Specification} for more information.
\endtable

\section1 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:

    \list
        \li Uncaught exceptions. Exceptions derived from \c std::exception also show details on
            \c {what()} occurred.
        \li \c SIGSEGV
        \li \c SIGABRT
        \li \c SIGBUS
        \li \c SIGILL
        \li \c SIGFPE
        \li \c SIGPIPE
        \li \c SIGQUIT
        \li \c SIGSYS
    \endlist

\table
    \header
        \li Config Key
        \li Type
        \li Description
    \row
        \li \c printBacktrace
        \li bool
        \li Tries to print a readable backtrace. On Linux, it uses the primitive backtrace
            functionality from glibc, unless \c libbacktrace was enabled at configure time.
            On Windows, backtraces are only printed if \c stackwalker was enabled at
            configure time. (default: true).
    \row
        \li \c printQmlStack
        \li bool
        \li Tries to print a readable QML stack trace. Similar to \c printBacktrace above, but
            prints the current QML function stack when the crash occurred. (default: true)
    \row
        \li \c dumpCore
        \li bool
        \li Ends the process via \c abort instead of \c _exit. Dumps a \c core file, depending on
            your kernel configuration. (default: true)
    \row
        \li \c waitForGdbAttach
        \li int
        \li Specifies a timeout in seconds while the crashed program is being held in the stopped
            state, waiting for a debugger to attach. Any value \c{<= 0} skips this step.
            (default: 0)
\endtable


\section1 Intent Timeout Specification

The \c intents/timeouts sub-object lets you specify the exact timeouts in milli-seconds 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 \c 0 or a negative number disables the timeout handling for
that specific stage.

\table
    \header
        \li Config Key
        \li Type
        \li Description
    \row
        \li \c disambiguation
        \li int
        \li The time interval in milli-seconds, in which a disambiguation decision for an intent
            has to be made in the System UI. (default: 10000)
    \row
        \li \c startApplication
        \li int
        \li The time interval in milli-seconds, 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: 3000)
    \row
        \li \c replyFromApplication
        \li int
        \li The time interval in milli-seconds, in which the handling application needs to
            acknowledge the receipt of an intent request. For QML applications, this is done in
            IntentHandler::requestReceived. (default: 5000)
    \row
        \li \c replyFromSystem
        \li int
        \li The time interval in milli-seconds, 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: 20000)
\endtable

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 \c replyFromApplication or \c replyFromSystem
timeout, although the receiver still received and processed it.

\section1 OpenGL Specification

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

\table
    \header
        \li Config Key
        \li Type
        \li Description
    \row
        \li \c desktopProfile
        \li string
        \li When running on a desktop, set this value to either \c core or \c 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.
    \row
        \li \c esMajorVersion
        \li int
        \li 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:
            \list
                \li 2.0 \unicode{0x2192} 2.1
                \li 3.0 \unicode{0x2192} 4.3
                \li 3.1 \unicode{0x2192} 4.5
                \li 3.2 \unicode{0x2192} 4.6
            \endlist

            Make sure to specify either \b both options: \c esMajorVersion and \c esMinorVersion;
            or \b 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.
    \row
        \li \c esMinorVersion
        \li int
        \li When set, the application manager requests the specified OpenGL ES minor version.
            For more information, see \c esMajorVersion above.
\endtable

*/