3 title: Widget configuration file
5 https://git.automotivelinux.org/src/app-framework-main/plain/docs/2.2-config.xml.md?h=master
8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/app-framework-main-developer-guides-api-services-book.yml -->
10 # Configuration file - config.xml
12 The widgets are described by the W3C's technical recommendations
13 [Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig]
14 that specifies the configuration file **config.xml**.
18 The file **config.xml** describes important data of the application
21 - the unique identifier of the application
22 - the name of the application
23 - the type of the application
24 - the icon of the application
25 - the permissions linked to the application
26 - the services and dependencies of the application
28 The file MUST be at the root of the widget and MUST be case sensitively name
31 The file **config.xml** is a XML file described by the document
34 Here is the example of the config file for the QML application SmartHome.
37 <?xml version="1.0" encoding="UTF-8"?>
38 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
39 <name>SmartHome</name>
40 <icon src="smarthome.png"/>
41 <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
42 <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
43 automated house. The user interface is completely done with QML.</description>
44 <author>Qt team</author>
45 <license>GPL</license>
49 The most important items are:
51 - **<widget id="......"\>**: gives the id of the widget. It must be unique.
53 - **<widget version="......"\>**: gives the version of the widget
55 - **<icon src="..."\>**: gives a path to the icon of the application
56 (can be repeated with different sizes)
58 - **<content src="..." type="..."\>**: this indicates the entry point and its type.
60 ## Standard elements of "config.xml"
62 ### The element widget
64 #### the attribute id of widget
66 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
68 Values for *id* are any non empty string containing only latin letters,
69 arabic digits, and the three characters '.' (dot), '-' (dash) and
72 Authors can use a mnemonic id or can pick a unique id using
73 command **uuid** or **uuidgen**.
75 ### the attribute version of widget
77 The attribute *version* is mandatory (for version 2.x, blowfish).
79 Values for *version* are any non empty string containing only latin letters,
80 arabic digits, and the three characters '.' (dot), '-' (dash) and
83 Version values are dot separated fields MAJOR.MINOR.REVISION.
84 Such version would preferably follow guidelines of
85 [semantic versioning][semantic-version].
87 ### The element content
89 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
90 (subject to localization) with its attribute *src*.
92 The content designed depends on its type. See below for the known types.
96 The element *icon* is mandatory (for version 2.x, blowfish) and must
97 be unique. It must designate an image file with its attribute *src*.
101 The AGL framework uses the feature tag for specifying security and binding
102 requirement of the widget.
104 Since the migration of the framework to leverage systemd power,
105 the features are of important use to:
107 - declare more than just an application
108 - declare the expected dependencies
109 - declare the expected permissions
110 - declare the exported apis
112 The specification of [widgets][widgets] is intended to describe
113 only one application.
114 In the present case, we expect to describe more than just an application.
115 For example, a publisher could provide a widget containing a service,
116 an application for tuning that service, an application that
117 leverage the service.
118 Here, the term of service means a background application that
119 runs without IHM and whose public api can be accessed by other
122 So the features are used to describe each of the possible
124 The "standard" unit in the meaning of [widgets][widgets]
125 is called the "main" unit.
127 ### required-api: feature name="urn:AGL:widget:required-api"
129 List of the api required by the widget.
131 Each required api must be explicit using a `<param>` entry.
136 <feature name="urn:AGL:widget:required-api">
137 <param name="#target" value="main" />
138 <param name="gps" value="auto" />
139 <param name="afm-main" value="link" />
143 This will be *virtually* translated for mustaches to the JSON
147 { "name": "gps", "value": "auto" },
148 { "name": "afm-main", "value": "link" }
152 #### required-api: param name="#target"
156 Declares the name of the unit requiring the listed apis.
157 Only one instance of the param "#target" is allowed.
158 When there is not instance of this param, it behave as if
159 the target main was specified.
161 #### required-api: param name=[required api name]
163 The name is the name of the required API.
165 The value describes how to connect to the required api.
168 - local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY
169 Use the feature **urn:AGL:widget:required-binding** instead.
170 The binding is a local shared object.
171 In that case, the name is the relative path of the
172 shared object to be loaded.
175 The framework set automatically the kind of
176 the connection to the API
179 The framework connect using internal websockets
181 - dbus: [OBSOLETE, shouldn't be used currently]
182 The framework connect using internal dbus
185 In that case, the name is the URI to access the service.
186 The framework connect using a URI of type
188 API gives the name of the imported api.
190 - cloud: [PROPOSAL - NOT IMPLEMENTED]
191 The framework connect externally using websock.
192 In that case, the name includes data to access the service.
193 Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`
195 ### required-binding: feature name="urn:AGL:widget:required-binding"
197 List of the bindings required by the widget.
199 Note: Since AGL 6 (FF - Funky Flounder),
200 the binder implements bindings version 3 that allow the declaration
201 of 0, 1 or more APIs by one binding. In other words, the equivalency
202 one binding = one API is lost. At the same time the framework added
203 the ability to use bindings exported by other widgets.
205 Each required binding must be explicit using a `<param>` entry.
210 <feature name="urn:AGL:widget:required-binding">
211 <param name="libexec/binding-gps.so" value="local" />
212 <param name="extra" value="extern" />
216 This will be *virtually* translated for mustaches to the JSON
219 "required-binding": [
220 { "name": "libexec/binding-gps.so", "value": "local" },
221 { "name": "extra", "value": "extern" }
225 #### required-binding: param name=[name or path]
227 The name or the path of the required BINDING.
229 The value describes how to connect to the required binding.
233 The binding is a local shared object.
234 In that case, the name is the relative path of the
235 shared object to be loaded.
238 The binding is external. The name is the exported binding name.
239 See provided-binding.
241 ### provided-binding: feature name="urn:AGL:widget:provided-binding"
243 This feature allows to export a binding to other binders.
244 The bindings whose relative name is given as value is exported to
245 other binders under the given name.
247 Each provided binding must be explicit using a `<param>` entry.
252 <feature name="urn:AGL:widget:provided-binding">
253 <param name="extra" value="export/binding-gps.so" />
257 This will be *virtually* translated for mustaches to the JSON
260 "provided-binding": [
261 { "name": "extra", "value": "export/binding-gps.so" }
265 #### provided-binding: param name=[exported name]
267 Exports a local binding to other applications.
269 The value must contain the path to the exported binding.
271 ### required-permission: feature name="urn:AGL:widget:required-permission"
273 List of the permissions required by the unit.
275 Each required permission must be explicit using a `<param>` entry.
280 <feature name="urn:AGL:widget:required-permission">
281 <param name="#target" value="geoloc" />
282 <param name="urn:AGL:permission:real-time" value="required" />
283 <param name="urn:AGL:permission:syscall:*" value="required" />
287 This will be *virtually* translated for mustaches to the JSON
290 "required-permission":{
291 "urn:AGL:permission:real-time":{
292 "name":"urn:AGL:permission:real-time",
295 "urn:AGL:permission:syscall:*":{
296 "name":"urn:AGL:permission:syscall:*",
302 #### required-permission: param name="#target"
306 Declares the name of the unit requiring the listed permissions.
307 Only one instance of the param "#target" is allowed.
308 When there is not instance of this param, it behave as if
309 the target main was specified.
311 #### required-permission: param name=[required permission name]
315 - required: the permission is mandatorily needed except if the feature
316 isn't required (required="false") and in that case it is optional.
317 - optional: the permission is optional
319 ### provided-unit: feature name="urn:AGL:widget:provided-unit"
321 This feature is made for declaring new units
323 Using this feature, a software publisher
324 can provide more than one application in the same widget.
329 <feature name="urn:AGL:widget:provided-unit">
330 <param name="#target" value="geoloc" />
331 <param name="description" value="binding of name geoloc" />
332 <param name="content.src" value="index.html" />
333 <param name="content.type" value="application/vnd.agl.service" />
337 This will be *virtually* translated for mustaches to the JSON
342 "description":"binding of name geoloc",
345 "type":"application\/vnd.agl.service"
351 #### provided-unit: param name="#target"
355 Declares the name of the unit. The default unit, the unit
356 of the main of the widget, has the name "main".
357 The value given here must be unique within the widget file.
358 It will be used in other places of the widget config.xml file to
361 Only one instance of the param "#target" is allowed.
362 The value can't be "main".
364 #### provided-unit: param name="content.type"
368 The mimetype of the provided unit.
370 #### provided-unit: param name="content.src"
374 #### other parameters
376 The items that can be set for the main unit
377 can also be set using the params if needed.
384 ### provided-api: feature name="urn:AGL:widget:provided-api"
386 Use this feature for exporting one or more API of a unit
387 to other widgets of the platform.
389 This feature is an important feature of the framework.
394 <feature name="urn:AGL:widget:provided-api">
395 <param name="#target" value="geoloc" />
396 <param name="geoloc" value="auto" />
397 <param name="moonloc" value="auto" />
401 This will be *virtually* translated for mustaches to the JSON
416 #### provided-api: param name="#target"
420 Declares the name of the unit exporting the listed apis.
421 Only one instance of the param "#target" is allowed.
422 When there is not instance of this param, it behave as if
423 the target main was specified.
425 #### provided-api: param name=[name of exported api]
427 The name give the name of the api that is exported.
429 The value is one of the following values:
432 export the api using UNIX websocket
434 - dbus: [OBSOLETE, shouldn't be used currently]
435 export the API using dbus
438 export the api using the default method(s).
441 In that case, the name is the URI used for exposing the service.
444 API gives the name of the exported api.
446 ### file-properties: feature name="urn:AGL:widget:file-properties"
448 Use this feature for setting properties to files of the widget.
449 At this time, this feature only allows to set executable flag
450 for making companion program executable explicitly.
455 <feature name="urn:AGL:widget:file-properties">
456 <param name="flite" value="executable" />
457 <param name="jtalk" value="executable" />
461 #### file-properties: param name="path"
463 The name is the relative path of the file whose property
466 The value must be "executable" to make the file executable.
468 ## Known content types
470 The configuration file ***/etc/afm/afm-unit.conf*** defines
471 how to create systemd units for widgets.
473 Known types for the type of content are:
477 content.src designates the home page of the application
479 - ***application/vnd.agl.native***
480 AGL compatible native,
481 content.src designates the relative path of the binary.
483 - ***application/vnd.agl.service***:
484 AGL service, content.src is not used.
486 - ***application/x-executable***:
488 content.src designates the relative path of the binary.
489 For such application, only security setup is made.
491 Adding more types is easy, it just need to edit the configuration
492 file ***afm-unit.conf***.
494 ### Older content type currently not supported at the moment
496 This types were defined previously when the framework was not
498 The transition to systemd let these types out at the moment.
500 - ***application/vnd.agl.url***
501 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
502 - ***application/vnd.agl.qml.hybrid***
503 - ***application/vnd.agl.html.hybrid***
507 ## The configuration file afm-unit.conf
509 The integration of the framework with systemd
510 mainly consists of creating the systemd unit
511 files corresponding to the need and requirements
512 of the installed widgets.
514 This configuration file named `afm-unit.conf` installed
515 on the system with the path `/etc/afm/afm-unit.conf`
516 describes how to generate all units from the *config.xml*
517 configuration files of widgets.
518 The description uses an extended version of the templating
519 formalism of [mustache][] to describes all the units.
521 Let present how it works using the following diagram that
522 describes graphically the workflow of creating the unit
523 files for systemd `afm-unit.conf` from the configuration
524 file of the widget `config.xml`:
526 ![make-units](pictures/make-units.svg)
528 In a first step, and because [mustache][] is intended
529 to work on JSON representations, the configuration file is
530 translated to an internal JSON representation.
531 This representation is shown along the examples of the documentation
532 of the config files of widgets.
534 In a second step, the mustache template `afm-unit.conf`
535 is instantiated using the C library [mustach][] that follows
536 the rules of [mustache][mustache] and with all its available
539 - use of colon (:) for explicit substitution
540 - test of values with = or =!
542 In a third step, the result of instantiating `afm-unit.conf`
543 for the widget is split in units.
544 To achieve that goal, the lines containing specific directives are searched.
545 Any directive occupy one full line.
549 Produce an empty line at the end
550 - %begin systemd-unit
552 Delimit the produced unit, its begin and its end
554 - %systemd-unit system
555 Tells the kind of unit (user/system)
556 - %systemd-unit service NAME
557 - %systemd-unit socket NAME
558 Gives the name and type (service or socket) of the unit.
559 The extension is automatically computed from the type
560 and must not be set in the name.
561 - %systemd-unit wanted-by NAME
562 Tells to install a link to the unit in the wants of NAME
564 Then the computed units are then written to the filesystem
565 and inserted in systemd.
567 The generated unit files will contain variables for internal
568 use of the framework.
569 These variables are starting with `X-AFM-`.
570 The variables starting with `X-AFM-` but not with `X-AFM--` are
571 the public variables.
572 These variables will be returned by the
573 framework as the details of an application (see **afm-util detail ...**).
575 Variables starting with `X-AFM--` are private to the framework.
576 By example, the variable `X-AFM--http-port` is used to
577 record the allocated port for applications.
579 [mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache"
580 [mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates"
581 [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps"
582 [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets"
583 [libxml2]: http://xmlsoft.org/html/index.html "libxml2"
584 [app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
585 [meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies"
586 [openssl]: https://www.openssl.org "OpenSSL"
587 [xmlsec]: https://www.aleksey.com/xmlsec "XMLSec"
588 [json-c]: https://github.com/json-c/json-c "JSON-c"
589 [d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus"
590 [libzip]: http://www.nih.at/libzip "libzip"
591 [cmake]: https://cmake.org "CMake"
592 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
593 [tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page"
594 [tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview"
595 [semantic-version]: http://semver.org/ "Semantic versioning"