1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
|
/****************************************************************************
**
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Luxoft Application Manager.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite licenses may use
** this file in accordance with the commercial license agreement provided
** with the Software or, alternatively, in accordance with the terms
** contained in a written agreement between you and The Qt Company. For
** licensing terms and conditions see https://www.qt.io/terms-conditions.
** For further information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page configuration.html
\title Configuration
\section1 Main Configuration
You can configure the application manager through 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.
\li 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.
\endlist
\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 -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 algorithm:
\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.
(default: \c /opt/am/config.yaml)
\row
\li \b --no-config-cache
\li bool
\li Disables the caching functionality for the configuration files: the cache is neither
read from or written to.
\row
\li \b --clear-config-cache
\li bool
\li 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.
\row
\li \b --option or \b{\c -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
\li \b --database
\br [\c applications/database]
\li string
\li To 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 \c info.yaml files for the applications installed, all over again. This
option specifies the path for this cache file. (default: empty/disabled)
\row
\li \b --recreate-database or \b{\c -r}
\li bool
\li Ignores any pre-existing database cache and creates a new one by (re)scanning all
\c info.yaml files in \c builtin-apps-manifest-dir and \c installed-apps-manifest-dir.
(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)
\row
\li \b --dbus
\li string
\li Registers the ApplicationManager, ApplicationInstaller, NotificationManager, and
WindowManager on the specified D-Bus: 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.
\note As of Qt 5.13, the new \c auto keyword replaces the old \c --start-session-dbus
flag.
\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/style]
\li string
\li If set, the given style is used by QtQuickControls 2.
\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
\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 \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 --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 \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}.
\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
\li string
\li A filesystem name for the Wayland socket that should be used when creating the
compositor component. (default: auto-detected by \c libwayland-server, most likely
\c 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.
\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}.
\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.
\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 an additional QML import path 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 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 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.
\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
\endlist
\table
\header
\li Config Key
\li Type
\li Description
\row
\li \c printBacktrace
\li bool
\li Tries to print a readable backtrace, using the primitive backtrace functionality from
glibc, unless \c libbacktrace 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 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
*/
|