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
|
// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page manifest.html
\ingroup qtappman
\keyword info.yaml metadata manifest format
\title Manifest Definition
\brief Describes the current metadata format for packages.
\note This page describes the current metadata format (\c am-package, version \c 1) that was
introduced with the 5.14 release. For the old format - that is still supported - please see
\l{Manifest Definition (pre 5.14)}{here}.
\section1 Overview
The package manifest or metadata file, \c info.yaml, is a \l {YAML syntax}
{YAML file following the same rules} as all the other YAML files used in the application manager.
While the application manager can support other file formats, such as XML, currently the only
metadata loader implemented is based on YAML.
All packages and their contained applications are described by a single \c info.yaml file, in the
root directory of the package.
\section1 Package Manifest
This is an example of a full-featured \c info.yaml file, that also shows how you can mix and match
classic YAML and JSON style in YAML 1.1 documents:
\badcode
%YAML 1.1
---
formatVersion: 1
formatType: am-package
---
id: 'com.pelagicore.radio'
icon: 'FM-Radio.png'
name:
en: "FM Radio"
de: "UKW-Rundfunk"
version: '1.2.1-alpha3'
applications:
- id: com.pelagicore.radio.app
code: "radio.qml"
runtime: qml
runtimeParameters: { quitTime: 100 }
capabilities:
- cameraAccess
- locationAccess
intents:
- id: setFrequency
handlingApplicationId: com.pelagicore.radio.app
name:
en: "Change the radio frequency"
- id: systemAboutToShutDown # broadcast from the sys-ui
handleOnlyWhenRunning: yes
\endcode
The fields within the \c info.yaml file header (first YAML document) are as follows:
\table
\header
\li Field Name
\li Type
\li Description
\row
\li \c formatVersion
\li int
\li \e Required. Currently always \c 1.
\row
\li \c formatType
\li string
\li \e Required. Always \c am-package.
\endtable
The fields within the \c info.yaml manifest data (second YAML document) are as follows:
\table
\header
\li Field Name
\li Type
\li Description
\row
\li \c id
\li string
\li The unique ID of the package represented as a string with a maximum length of 150
characters. This ID can be used to look up information about the package in the
\l{PackageManager}{PackageManager QML Type}. Since this ID is used in the file system, only
a subset of the printable ASCII characters are allowed: \c{0-9}, \c{a-z}, \c{A-Z} as well as
any of \c{!#$%&'`^~_+-=.,;()[]{}}. If you are building a larger system with third party
applications, it is good practice to use reverse DNS notation for the package IDs to
help keep track of your IDs in the long run. The helper function
\l{PackageManager::validateDnsName} can help you to enforce this policy from the
System UI.
\row
\li \c icon
\li string
\li The icon's file name. The file must be located in the same directory as \c info.yaml and
can be in any image format that Qt supports. The file size cannot exceed \c 1MB.
\row
\li \c name
\li object
\target package-name-map
\li An optional object containing language (\c string) to display name (\c string)
mappings. The language identifiers need to adhere to the standard POSIX locale definition.
For more information, see \l{QLocale}. It is good practice to supply at least the English
(\c en) mapping, as a fallback. If not supplying any mapping at all, the name will be the
same as the \c id.
\row
\li \c description
\li object
\li An optional object containing language (\c string) to descriptive name (\c string)
mappings. This field uses the same syntax as the \c name field.
\row
\li \c categories
\li list<string>
\li The list of category names the package should be associated with. This is mainly for
the automated app-store uploads as well as displaying the packages's applications or
intents within a fixed set of categories in the System UI.
\row
\li \c version
\li string
\li The version of the package as a string.
This will also be used to set up QCoreApplication::applicationVersion for multi-process QML
applications.
\row
\li \c applications
\li list
\li \e Required. The list of applications contained in this package. At least one application
has to be defined.
\row
\li \c intents
\li list
\li \e The list of intents provided by applications in this package.
\endtable
The fields used for each item within the \c applications list are as follows:
\table
\header
\li Field Name
\li Type
\li Description
\row
\li \c id
\li string
\li The unique ID of an application represented as a string with a maximum length of 150
characters. This ID can be used to look up information about the application in the
\l{ApplicationModel}{ApplicationModel QML Type}. Since this ID is used in the file system, only a subset of
the printable ASCII characters are allowed: \c{0-9}, \c{a-z}, \c{A-Z} as well as any of
\c{!#$%&'`^~_+-=.,;()[]{}}. If you are building a larger system with third party
applications, it is good practice to use reverse DNS notation for the application IDs to
help keep track of your IDs in the long run. The helper function
\l{PackageManager::validateDnsName} can help you to enforce this policy from the
System UI.
This ID will also be used to set up QCoreApplication::applicationName for multi-process QML
applications. If you are using reverse DNS notation, the QCoreApplication::organizationName
and QCoreApplication::organizationDomain properties will both be set to the domain part of
the ID. Otherwise the organization name and domain will default to \e{QtProject} and
\e{qt-project.org} respectively.
\row
\li \c code
\li string
\li \e Required. The main executable - interpreted by the \c runtime.
\row
\li \c runtime
\li string
\li \e Required. A runtime ID, referencing a runtime plugin. Currently, \c qml,
\c qml-inprocess, and \c native are supported.
For the QML runtimes, the \c code field needs to point to the main QML file, which should
have an ApplicationManagerWindow as a root item.
For the native runtime, the \c code field can point to an arbitrary executable, which is
executed via QProcess::start(). The application manager will run the application with the
environment variable \c QT_QPA_PLATFORM set to \c wayland.
\note The application is expected to be a valid Wayland client.
\row
\li \c runtimeParameters
\li object
\li This object can contain \c runtime specific parameters - those are directly handed down to
the runtime plugin by the application manager.
See \l{runtime-parameters-details}{runtime parameters} for a full list.
\row
\li \c supportsApplicationInterface
\li bool
\target manifest supportsApplicationInterface
\li If set to \c true the application must implement the \l{ApplicationInterface}
{ApplicationInterface D-Bus API}.
In this case the application manager will wait until the application is connected to the
ApplicationInterface on the P2P D-Bus until it marks it as 'running'. For runtimes that
support quick launching (like the \c qml runtime) this is not required as it defaults to
\c true. Otherwise the default is \c false.
\row
\li \c capabilities
\li list<string>
\li An optional, platform specific list of special access rights for the application. Later,
the middleware can query these capabilities and verify them, via the application manager.
\note The application manager itself does not attach any meaning to this list of strings.
Instead, the application manager acts as a trustee between the (digitally signed)
application manifest and the (customer specific) middleware; this middleware may
require more information about the application it's communicating with and the
application manager can act as a trusted source of application \e capabilities.
\row
\li \c opengl
\li object
\li Gives you the possibility to specify the required OpenGL version and/or profile. For more
information, see \l{OpenGL Specification}.
\note Specifying an OpenGL configuration that is different from the default OpenGL
configuration in the main application manager configuration, disables the use of
the quick-launch mechanism for this application.
\row
\li \c applicationProperties
\li object
\li Exports user-defined properties (key/value pairs) to the application and the System UI. The
actual properties must be listed under the \c private and \c protected access control
tag; other properties are ignored. These properties are exposed as
ApplicationManager::application() to the System UI and as
ApplicationInterface::applicationProperties to the QML application:
\list
\li The application has access to private and protected properties. Private keys overwrite
identical protected ones.
\li The System UI has access to protected properties only.
\endlist
While the properties are converted to QVariantMaps, the application manager won't interpret
them in any way.
\row
\li \c logging/dlt/id
\li string
\li If provided, this value is used as the automotive DLT application ID. The ID is limited to
four characters, additional characters are discarded. If an ID is not provided, it defaults
to 'A' followed by a three digit application number.
\note For QML runtimes, the ID is "PCLQ" from the very start of the application process,
until you change it as described.
\row
\li \c logging/dlt/description
\li string
\li If provided, it is used as the automotive DLT application description, which allows to
augment the short DLT application ID with a more verbose description. If not explicitly
provided, a default description is used.
\row
\li \c name
\li object
\li The name of the application. It will default to the \c name field in the global package
section, but it can be overwritten for each application by specifying this field.
\row
\li \c icon
\li string
\li The icon of the application. It will default to the \c icon field in the global package
section, but it can be overwritten for each application by specifying this field.
Contrary to the package's icon, there are no restrictions regarding file location, type or
size.
\row
\li \c description
\li object
\li The description of the application. It will default to the \c description field in the
global package section, but it can be overwritten for each application by specifying this
field.
\row
\li \c categories
\li list<string>
\li The list of categories for this application. It will default to the \c categories field in
the global package section, but it can be overwritten for each application by specifying
this field.
\row
\li \c watchdog
\li object
\li Use this field to override the global watchdog settings for this application. This allows
you to set different timeouts for this application, or to enable/disable the watchdog for
this application specifically. See the \l{Watchdog} documentation for more information.
\endtable
\target manifest-intent
The fields used for each item within the \c intents list are as follows:
\table
\header
\li Field Name
\li Type
\li Description
\row
\li \c id
\li string
\li Required. The id of the intent. Make sure to only specify intent IDs that the applications
in this package are actually handling.
\row
\li \c visibility
\li string
\li The visibility of this intent outside of this package: Can be either \c private or \c public
(which is the default, if this field is not specified at all). Private intents can only be
requested by applications from this package, while public intents can also be requested by
other applications in the system.
\row
\li \c handlingApplicationId
\li string
\li If this package contains more than one application, then it is mandatory to specify which
application is handling this intent; if there is only one application defined, then this
application will be used as the default handler for all intents.
The given application id has to be from within this package.
\row
\li \c handleOnlyWhenRunning
\li bool
\li By default, applications are automatically started when a request is targeted at them, but
they are not currently running. Setting the \c handleOnlyWhenRunning flag to \c true will
prevent this behavior and any requests for this intent will only be forwarded to its
handling application, if the application is actuallly running.
This is useful for system-wide broadcasts that are only relevant if an application is active
(e.g. changes in internet availability).
\row
\li \c requiredCapabilities
\li list<string>
\li Limit the client applications that are able to call this intent to applications having at
least one of the capabilities given in this list. An empty list or by simply not specifying
this field at all will lead to no capability restrictions.
\row
\li \c parameterMatch
\li object
\li Filter the intent based on the incoming parameters. This can be used to have multiple
applications being able to handle the same intent, dependent on the actual parameters in
the intent request. See the IntentObject::parameterMatch documentation for a detailed
explanation for this field.
\row
\li \c name
\li object
\li The name of the intent. It will default to the \c name field in the global package section,
but it can be overwritten for each intent by specifying this field.
\row
\li \c icon
\li string
\li The icon of the intent. It will default to the \c icon field in the global package section,
but it can be overwritten for each intent by specifying this field.
Contrary to the package's icon, there are no restrictions regarding file location, type or
size.
\row
\li \c description
\li object
\li The description of the intent. It will default to the \c description field in the global
package section, but it can be overwritten for each intent by specifying this field.
\row
\li \c categories
\li list<string>
\li The list of categories for this intent. It will default to the \c categories field in the
global package section, but it can be overwritten for each intent by specifying this field.
\endtable
\target runtime-parameters-details
The \c runtimeParameters are specific to the runtimes, so the table below has an additional column
that specifies which runtime a configuration option applies to:
\table
\header
\li Name
\li Runtimes
\li Type
\li Description
\row
\li \c loadDummyData
\li qml, qml-in-process
\li bool
\li Deprecated and ignored.
\row
\li \c importPaths
\li qml, qml-in-process
\li list<string>
\li A list of paths to add to the QML-engine's import paths. Use of this parameter is
equivalent to setting \c QML2_IMPORT_PATH for a program started from the command line.
\row
\li \c resources
\li qml, qml-in-process
\li list<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 application
process. Resources can be accessed with the ":" or "qrc://" file path prefix.
\row
\li \c pluginPaths
\li qml, qml-in-process
\li list<string>
\li A list of paths to add to Qt's library paths, which are used to find plugins. Use of this
parameter is equivalent to setting \c QT_PLUGIN_PATH for a program started from the command
line.
\row
\li \c arguments
\li native
\li list<string>
\li A list of command line parameters to use when starting the application's executable.
\row
\li \c environmentVariables
\li native, qml
\li object
\li A simple string-to-string map, describing the environment variables that should be set when
spawning the runtime process. You can remove a variable from the default environment by
setting it to \c null.
\note This feature is meant for development and demos only, as it has the following
limitations and side-effects:
\list
\li These variables are completely ignored, if you are running the application manager
with security checks enabled.
\li Setting these variables disables the use of the quick launch mechanism for this
application.
\endlist
\row
\li \c documentUrl
\li native, qml, qml-in-process
\li string
\li An optional default document URL to use if the application is started without
specifying a document URL (see \l{ApplicationManager::startApplication}).
\endtable
*/
|