2 title: Widget configuration file
5 # Configuration file - config.xml
7 The widgets are described by the W3C's technical recommendations
8 [Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for
9 Widgets][widgets-digsig]
10 that specifies the configuration file **config.xml**.
14 The file **config.xml** describes important data of the application
17 - the unique identifier of the application
18 - the name of the application
19 - the type of the application
20 - the icon of the application
21 - the permissions linked to the application
22 - the services and dependencies of the application
24 The file MUST be at the root of the widget and MUST be case sensitively name
27 The file **config.xml** is a XML file described by the document
30 Here is the example of the config file for the QML application SmartHome.
33 <?xml version="1.0" encoding="UTF-8"?>
34 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
35 <name>SmartHome</name>
36 <icon src="smarthome.png"/>
37 <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
38 <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
39 automated house. The user interface is completely done with QML.</description>
40 <author>Qt team</author>
41 <license>GPL</license>
45 The most important items are:
47 - **<widget id="......"\>**: gives the id of the widget. It must be unique.
49 - **<widget version="......"\>**: gives the version of the widget
51 - **<icon src="..."\>**: gives a path to the icon of the application
52 (can be repeated with different sizes)
54 - **<content src="..." type="..."\>**: this indicates the entry point and its type.
56 ## Standard elements of "config.xml"
58 ### The element widget
60 #### the attribute id of widget
62 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
64 Values for *id* are any non empty string containing only latin letters,
65 arabic digits, and the three characters '.' (dot), '-' (dash) and
68 Authors can use a mnemonic id or can pick a unique id using
69 command **uuid** or **uuidgen**.
71 ### the attribute version of widget
73 The attribute *version* is mandatory (for version 2.x, blowfish).
75 Values for *version* are any non empty string containing only latin letters,
76 arabic digits, and the three characters '.' (dot), '-' (dash) and
79 Version values are dot separated fields MAJOR.MINOR.REVISION.
80 Such version would preferably follow guidelines of
81 [semantic versioning][semantic-version].
83 ### The element content
85 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
86 (subject to localization) with its attribute *src*.
88 The content designed depends on its type. See below for the known types.
92 The element *icon* is mandatory (for version 2.x, blowfish) and must
93 be unique. It must designate an image file with its attribute *src*.
97 The AGL framework uses the feature tag for specifying security and binding
98 requirement of the widget.
100 Since the migration of the framework to leverage systemd power,
101 the features are of important use to:
103 - declare more than just an application
104 - declare the expected dependencies
105 - declare the expected permissions
106 - declare the exported apis
108 The specification of [widgets][widgets] is intended to describe
109 only one application.
110 In the present case, we expect to describe more than just an application.
111 For example, a publisher could provide a widget containing a service,
112 an application for tuning that service, an application that
113 leverage the service.
114 Here, the term of service means a background application that
115 runs without IHM and whose public api can be accessed by other
118 So the features are used to describe each of the possible
120 The "standard" unit in the meaning of [widgets][widgets]
121 is called the "main" unit.
123 ### required-api: feature name="urn:AGL:widget:required-api"
125 List of the api required by the widget.
127 Each required api must be explicit using a `<param>` entry.
132 <feature name="urn:AGL:widget:required-api">
133 <param name="#target" value="main" />
134 <param name="gps" value="auto" />
135 <param name="afm-main" value="link" />
139 This will be *virtually* translated for mustaches to the JSON
143 { "name": "gps", "value": "auto" },
144 { "name": "afm-main", "value": "link" }
148 #### required-api: param name="#target"
152 Declares the name of the unit requiring the listed apis.
153 Only one instance of the param "#target" is allowed.
154 When there is not instance of this param, it behave as if
155 the target main was specified.
157 #### required-api: param name=[required api name]
159 The name is the name of the required API.
161 The value describes how to connect to the required api.
164 - local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY
165 Use the feature **urn:AGL:widget:required-binding** instead.
166 The binding is a local shared object.
167 In that case, the name is the relative path of the
168 shared object to be loaded.
171 The framework set automatically the kind of
172 the connection to the API
175 The framework connect using internal websockets
177 - dbus: [OBSOLETE, shouldn't be used currently]
178 The framework connect using internal dbus
181 In that case, the name is the URI to access the service.
182 The framework connect using a URI of type
184 API gives the name of the imported api.
186 - cloud: [PROPOSAL - NOT IMPLEMENTED]
187 The framework connect externally using websock.
188 In that case, the name includes data to access the service.
189 Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`
191 ### required-binding: feature name="urn:AGL:widget:required-binding"
193 List of the bindings required by the widget.
195 Note: Since AGL 6 (FF - Funky Flounder),
196 the binder implements bindings version 3 that allow the declaration
197 of 0, 1 or more APIs by one binding. In other words, the equivalency
198 one binding = one API is lost. At the same time the framework added
199 the ability to use bindings exported by other widgets.
201 Each required binding must be explicit using a `<param>` entry.
206 <feature name="urn:AGL:widget:required-binding">
207 <param name="libexec/binding-gps.so" value="local" />
208 <param name="extra" value="extern" />
212 This will be *virtually* translated for mustaches to the JSON
215 "required-binding": [
216 { "name": "libexec/binding-gps.so", "value": "local" },
217 { "name": "extra", "value": "extern" }
221 #### required-binding: param name=[name or path]
223 The name or the path of the required BINDING.
225 The value describes how to connect to the required binding.
229 The binding is a local shared object.
230 In that case, the name is the relative path of the
231 shared object to be loaded.
234 The binding is external. The name is the exported binding name.
235 See provided-binding.
237 ### provided-binding: feature name="urn:AGL:widget:provided-binding"
239 This feature allows to export a binding to other binders.
240 The bindings whose relative name is given as value is exported to
241 other binders under the given name.
243 Each provided binding must be explicit using a `<param>` entry.
248 <feature name="urn:AGL:widget:provided-binding">
249 <param name="extra" value="export/binding-gps.so" />
253 This will be *virtually* translated for mustaches to the JSON
256 "provided-binding": [
257 { "name": "extra", "value": "export/binding-gps.so" }
261 #### provided-binding: param name=[exported name]
263 Exports a local binding to other applications.
265 The value must contain the path to the exported binding.
267 ### required-permission: feature name="urn:AGL:widget:required-permission"
269 List of the permissions required by the unit.
271 Each required permission must be explicit using a `<param>` entry.
276 <feature name="urn:AGL:widget:required-permission">
277 <param name="#target" value="geoloc" />
278 <param name="urn:AGL:permission:real-time" value="required" />
279 <param name="urn:AGL:permission:syscall:*" value="required" />
283 This will be *virtually* translated for mustaches to the JSON
286 "required-permission":{
287 "urn:AGL:permission:real-time":{
288 "name":"urn:AGL:permission:real-time",
291 "urn:AGL:permission:syscall:*":{
292 "name":"urn:AGL:permission:syscall:*",
298 #### required-permission: param name="#target"
302 Declares the name of the unit requiring the listed permissions.
303 Only one instance of the param "#target" is allowed.
304 When there is not instance of this param, it behave as if
305 the target main was specified.
307 #### required-permission: param name=[required permission name]
311 - required: the permission is mandatorily needed except if the feature
312 isn't required (required="false") and in that case it is optional.
313 - optional: the permission is optional
315 ### provided-unit: feature name="urn:AGL:widget:provided-unit"
317 This feature is made for declaring new units
319 Using this feature, a software publisher
320 can provide more than one application in the same widget.
325 <feature name="urn:AGL:widget:provided-unit">
326 <param name="#target" value="geoloc" />
327 <param name="description" value="binding of name geoloc" />
328 <param name="content.src" value="index.html" />
329 <param name="content.type" value="application/vnd.agl.service" />
333 This will be *virtually* translated for mustaches to the JSON
338 "description":"binding of name geoloc",
341 "type":"application\/vnd.agl.service"
347 #### provided-unit: param name="#target"
351 Declares the name of the unit. The default unit, the unit
352 of the main of the widget, has the name "main".
353 The value given here must be unique within the widget file.
354 It will be used in other places of the widget config.xml file to
357 Only one instance of the param "#target" is allowed.
358 The value can't be "main".
360 #### provided-unit: param name="content.type"
364 The mimetype of the provided unit.
366 #### provided-unit: param name="content.src"
370 #### other parameters
372 The items that can be set for the main unit
373 can also be set using the params if needed.
380 ### provided-api: feature name="urn:AGL:widget:provided-api"
382 Use this feature for exporting one or more API of a unit
383 to other widgets of the platform.
385 This feature is an important feature of the framework.
390 <feature name="urn:AGL:widget:provided-api">
391 <param name="#target" value="geoloc" />
392 <param name="geoloc" value="auto" />
393 <param name="moonloc" value="auto" />
397 This will be *virtually* translated for mustaches to the JSON
412 #### provided-api: param name="#target"
416 Declares the name of the unit exporting the listed apis.
417 Only one instance of the param "#target" is allowed.
418 When there is not instance of this param, it behave as if
419 the target main was specified.
421 #### provided-api: param name=[name of exported api]
423 The name give the name of the api that is exported.
425 The value is one of the following values:
428 export the api using UNIX websocket
430 - dbus: [OBSOLETE, shouldn't be used currently]
431 export the API using dbus
434 export the api using the default method(s).
437 In that case, the name is the URI used for exposing the service.
440 API gives the name of the exported api.
442 ### file-properties: feature name="urn:AGL:widget:file-properties"
444 Use this feature for setting properties to files of the widget.
445 At this time, this feature only allows to set executable flag
446 for making companion program executable explicitly.
451 <feature name="urn:AGL:widget:file-properties">
452 <param name="flite" value="executable" />
453 <param name="jtalk" value="executable" />
457 #### file-properties: param name="path"
459 The name is the relative path of the file whose property
462 The value must be "executable" to make the file executable.
464 ## Known content types
466 The configuration file ***/etc/afm/afm-unit.conf*** defines
467 how to create systemd units for widgets.
469 Known types for the type of content are:
473 content.src designates the home page of the application
475 - ***application/vnd.agl.native***
476 AGL compatible native,
477 content.src designates the relative path of the binary.
479 - ***application/vnd.agl.service***:
480 AGL service, content.src is not used.
482 - ***application/x-executable***:
484 content.src designates the relative path of the binary.
485 For such application, only security setup is made.
487 Adding more types is easy, it just need to edit the configuration
488 file ***afm-unit.conf***.
490 ### Older content type currently not supported at the moment
492 This types were defined previously when the framework was not
494 The transition to systemd let these types out at the moment.
496 - ***application/vnd.agl.url***
497 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
498 - ***application/vnd.agl.qml.hybrid***
499 - ***application/vnd.agl.html.hybrid***
501 ## The configuration file afm-unit.conf
503 The integration of the framework with systemd
504 mainly consists of creating the systemd unit
505 files corresponding to the need and requirements
506 of the installed widgets.
508 This configuration file named `afm-unit.conf` installed
509 on the system with the path `/etc/afm/afm-unit.conf`
510 describes how to generate all units from the *config.xml*
511 configuration files of widgets.
512 The description uses an extended version of the templating
513 formalism of [mustache][] to describes all the units.
515 Let present how it works using the following diagram that
516 describes graphically the workflow of creating the unit
517 files for systemd `afm-unit.conf` from the configuration
518 file of the widget `config.xml`:
520 ![make-units](pictures/make-units.svg)
522 In a first step, and because [mustache][] is intended
523 to work on JSON representations, the configuration file is
524 translated to an internal JSON representation.
525 This representation is shown along the examples of the documentation
526 of the config files of widgets.
528 In a second step, the mustache template `afm-unit.conf`
529 is instantiated using the C library [mustach][] that follows
530 the rules of [mustache][mustache] and with all its available
533 - use of colon (:) for explicit substitution
534 - test of values with = or =!
536 In a third step, the result of instantiating `afm-unit.conf`
537 for the widget is split in units.
538 To achieve that goal, the lines containing specific directives are searched.
539 Any directive occupy one full line.
543 Produce an empty line at the end
544 - %begin systemd-unit
546 Delimit the produced unit, its begin and its end
548 - %systemd-unit system
549 Tells the kind of unit (user/system)
550 - %systemd-unit service NAME
551 - %systemd-unit socket NAME
552 Gives the name and type (service or socket) of the unit.
553 The extension is automatically computed from the type
554 and must not be set in the name.
555 - %systemd-unit wanted-by NAME
556 Tells to install a link to the unit in the wants of NAME
558 Then the computed units are then written to the filesystem
559 and inserted in systemd.
561 The generated unit files will contain variables for internal
562 use of the framework.
563 These variables are starting with `X-AFM-`.
564 The variables starting with `X-AFM-` but not with `X-AFM--` are
565 the public variables.
566 These variables will be returned by the
567 framework as the details of an application (see **afm-util detail ...**).
569 Variables starting with `X-AFM--` are private to the framework.
570 By example, the variable `X-AFM--http-port` is used to
571 record the allocated port for applications.
573 [mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache"
574 [mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates"
575 [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps"
576 [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets"
577 [libxml2]: http://xmlsoft.org/html/index.html "libxml2"
578 [app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
579 [meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies"
580 [openssl]: https://www.openssl.org "OpenSSL"
581 [xmlsec]: https://www.aleksey.com/xmlsec "XMLSec"
582 [json-c]: https://github.com/json-c/json-c "JSON-c"
583 [d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus"
584 [libzip]: http://www.nih.at/libzip "libzip"
585 [cmake]: https://cmake.org "CMake"
586 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
587 [tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page"
588 [tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview"
589 [semantic-version]: http://semver.org/ "Semantic versioning"