1 # Configuration file - config.xml
3 The widgets are described by the W3C's technical recommendations
4 [Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig]
5 that specifies the configuration file **config.xml**.
9 The file **config.xml** describes important data of the application
12 - the unique identifier of the application
13 - the name of the application
14 - the type of the application
15 - the icon of the application
16 - the permissions linked to the application
17 - the services and dependencies of the application
19 The file MUST be at the root of the widget and MUST be case sensitively name
22 The file **config.xml** is a XML file described by the document
25 Here is the example of the config file for the QML application SmartHome.
28 <?xml version="1.0" encoding="UTF-8"?>
29 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
30 <name>SmartHome</name>
31 <icon src="smarthome.png"/>
32 <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
33 <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
34 automated house. The user interface is completely done with QML.</description>
35 <author>Qt team</author>
36 <license>GPL</license>
40 The most important items are:
42 - **<widget id="......"\>**: gives the id of the widget. It must be unique.
44 - **<widget version="......"\>**: gives the version of the widget
46 - **<icon src="..."\>**: gives a path to the icon of the application
47 (can be repeated with different sizes)
49 - **<content src="..." type="..."\>**: this indicates the entry point and its type.
51 ## Standard elements of "config.xml"
53 ### The element widget
55 #### the attribute id of widget
57 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
59 Values for *id* are any non empty string containing only latin letters,
60 arabic digits, and the three characters '.' (dot), '-' (dash) and
63 Authors can use a mnemonic id or can pick a unique id using
64 command **uuid** or **uuidgen**.
66 ### the attribute version of widget
68 The attribute *version* is mandatory (for version 2.x, blowfish).
70 Values for *version* are any non empty string containing only latin letters,
71 arabic digits, and the three characters '.' (dot), '-' (dash) and
74 Version values are dot separated fields MAJOR.MINOR.REVISION.
75 Such version would preferably follow guidelines of
76 [semantic versioning][semantic-version].
78 ### The element content
80 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
81 (subject to localization) with its attribute *src*.
83 The content designed depends on its type. See below for the known types.
87 The element *icon* is mandatory (for version 2.x, blowfish) and must
88 be unique. It must designate an image file with its attribute *src*.
92 The AGL framework uses the feature tag for specifying security and binding
93 requirement of the widget.
95 Since the migration of the framework to leverage systemd power,
96 the features are of important use to:
98 - declare more than just an application
99 - declare the expected dependencies
100 - declare the expected permissions
101 - declare the exported apis
103 The specification of [widgets][widgets] is intended to describe
104 only one application.
105 In the present case, we expect to describe more than just an application.
106 For example, a publisher could provide a widget containing a service,
107 an application for tuning that service, an application that
108 leverage the service.
109 Here, the term of service means a background application that
110 runs without IHM and whose public api can be accessed by other
113 So the features are used to describe each of the possible
115 The "standard" unit in the meaning of [widgets][widgets]
116 is called the "main" unit.
118 ### required-api: feature name="urn:AGL:widget:required-api"
120 List of the api required by the widget.
122 Each required api must be explicit using a `<param>` entry.
127 <feature name="urn:AGL:widget:required-api">
128 <param name="#target" value="main" />
129 <param name="gps" value="auto" />
130 <param name="afm-main" value="link" />
134 This will be *virtually* translated for mustaches to the JSON
138 { "name": "gps", "value": "auto" },
139 { "name": "afm-main", "value": "link" }
143 #### required-api: param name="#target"
147 Declares the name of the unit requiring the listed apis.
148 Only one instance of the param "#target" is allowed.
149 When there is not instance of this param, it behave as if
150 the target main was specified.
152 #### required-api: param name=[required api name]
154 The name is the name of the required API.
156 The value describes how to connect to the required api.
159 - local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY
160 Use the feature **urn:AGL:widget:required-binding** instead.
161 The binding is a local shared object.
162 In that case, the name is the relative path of the
163 shared object to be loaded.
166 The framework set automatically the kind of
167 the connection to the API
170 The framework connect using internal websockets
172 - dbus: [OBSOLETE, shouldn't be used currently]
173 The framework connect using internal dbus
176 In that case, the name is the URI to access the service.
177 The framework connect using a URI of type
179 API gives the name of the imported api.
181 - cloud: [PROPOSAL - NOT IMPLEMENTED]
182 The framework connect externally using websock.
183 In that case, the name includes data to access the service.
184 Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`
186 ### required-binding: feature name="urn:AGL:widget:required-binding"
188 List of the bindings required by the widget.
190 Note: Since AGL 6 (FF - Funky Flounder),
191 the binder implements bindings version 3 that allow the declaration
192 of 0, 1 or more APIs by one binding. In other words, the equivalency
193 one binding = one API is lost. At the same time the framework added
194 the ability to use bindings exported by other widgets.
196 Each required binding must be explicit using a `<param>` entry.
201 <feature name="urn:AGL:widget:required-binding">
202 <param name="libexec/binding-gps.so" value="local" />
203 <param name="extra" value="extern" />
207 This will be *virtually* translated for mustaches to the JSON
210 "required-binding": [
211 { "name": "libexec/binding-gps.so", "value": "local" },
212 { "name": "extra", "value": "extern" }
216 #### required-binding: param name=[name or path]
218 The name or the path of the required BINDING.
220 The value describes how to connect to the required binding.
224 The binding is a local shared object.
225 In that case, the name is the relative path of the
226 shared object to be loaded.
229 The binding is external. The name is the exported binding name.
230 See provided-binding.
232 ### provided-binding: feature name="urn:AGL:widget:provided-binding"
234 This feature allows to export a binding to other binders.
235 The bindings whose relative name is given as value is exported to
236 other binders under the given name.
238 Each provided binding must be explicit using a `<param>` entry.
243 <feature name="urn:AGL:widget:provided-binding">
244 <param name="extra" value="export/binding-gps.so" />
248 This will be *virtually* translated for mustaches to the JSON
251 "provided-binding": [
252 { "name": "extra", "value": "export/binding-gps.so" }
256 #### provided-binding: param name=[exported name]
258 Exports a local binding to other applications.
260 The value must contain the path to the exported binding.
262 ### required-permission: feature name="urn:AGL:widget:required-permission"
264 List of the permissions required by the unit.
266 Each required permission must be explicit using a `<param>` entry.
271 <feature name="urn:AGL:widget:required-permission">
272 <param name="#target" value="geoloc" />
273 <param name="urn:AGL:permission:real-time" value="required" />
274 <param name="urn:AGL:permission:syscall:*" value="required" />
278 This will be *virtually* translated for mustaches to the JSON
281 "required-permission":{
282 "urn:AGL:permission:real-time":{
283 "name":"urn:AGL:permission:real-time",
286 "urn:AGL:permission:syscall:*":{
287 "name":"urn:AGL:permission:syscall:*",
293 #### required-permission: param name="#target"
297 Declares the name of the unit requiring the listed permissions.
298 Only one instance of the param "#target" is allowed.
299 When there is not instance of this param, it behave as if
300 the target main was specified.
302 #### required-permission: param name=[required permission name]
306 - required: the permission is mandatorily needed except if the feature
307 isn't required (required="false") and in that case it is optional.
308 - optional: the permission is optional
310 ### provided-unit: feature name="urn:AGL:widget:provided-unit"
312 This feature is made for declaring new units
314 Using this feature, a software publisher
315 can provide more than one application in the same widget.
320 <feature name="urn:AGL:widget:provided-unit">
321 <param name="#target" value="geoloc" />
322 <param name="description" value="binding of name geoloc" />
323 <param name="content.src" value="index.html" />
324 <param name="content.type" value="application/vnd.agl.service" />
328 This will be *virtually* translated for mustaches to the JSON
333 "description":"binding of name geoloc",
336 "type":"application\/vnd.agl.service"
342 #### provided-unit: param name="#target"
346 Declares the name of the unit. The default unit, the unit
347 of the main of the widget, has the name "main".
348 The value given here must be unique within the widget file.
349 It will be used in other places of the widget config.xml file to
352 Only one instance of the param "#target" is allowed.
353 The value can't be "main".
355 #### provided-unit: param name="content.type"
359 The mimetype of the provided unit.
361 #### provided-unit: param name="content.src"
365 #### other parameters
367 The items that can be set for the main unit
368 can also be set using the params if needed.
375 ### provided-api: feature name="urn:AGL:widget:provided-api"
377 Use this feature for exporting one or more API of a unit
378 to other widgets of the platform.
380 This feature is an important feature of the framework.
385 <feature name="urn:AGL:widget:provided-api">
386 <param name="#target" value="geoloc" />
387 <param name="geoloc" value="auto" />
388 <param name="moonloc" value="auto" />
392 This will be *virtually* translated for mustaches to the JSON
407 #### provided-api: param name="#target"
411 Declares the name of the unit exporting the listed apis.
412 Only one instance of the param "#target" is allowed.
413 When there is not instance of this param, it behave as if
414 the target main was specified.
416 #### provided-api: param name=[name of exported api]
418 The name give the name of the api that is exported.
420 The value is one of the following values:
423 export the api using UNIX websocket
425 - dbus: [OBSOLETE, shouldn't be used currently]
426 export the API using dbus
429 export the api using the default method(s).
432 In that case, the name is the URI used for exposing the service.
435 API gives the name of the exported api.
437 ### file-properties: feature name="urn:AGL:widget:file-properties"
439 Use this feature for setting properties to files of the widget.
440 At this time, this feature only allows to set executable flag
441 for making companion program executable explicitly.
446 <feature name="urn:AGL:widget:file-properties">
447 <param name="flite" value="executable" />
448 <param name="jtalk" value="executable" />
452 #### file-properties: param name="path"
454 The name is the relative path of the file whose property
457 The value must be "executable" to make the file executable.
459 ## Known content types
461 The configuration file ***/etc/afm/afm-unit.conf*** defines
462 how to create systemd units for widgets.
464 Known types for the type of content are:
468 content.src designates the home page of the application
470 - ***application/vnd.agl.native***
471 AGL compatible native,
472 content.src designates the relative path of the binary.
474 - ***application/vnd.agl.service***:
475 AGL service, content.src is not used.
477 - ***application/x-executable***:
479 content.src designates the relative path of the binary.
480 For such application, only security setup is made.
482 Adding more types is easy, it just need to edit the configuration
483 file ***afm-unit.conf***.
485 ### Older content type currently not supported at the moment
487 This types were defined previously when the framework was not
489 The transition to systemd let these types out at the moment.
491 - ***application/vnd.agl.url***
492 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
493 - ***application/vnd.agl.qml.hybrid***
494 - ***application/vnd.agl.html.hybrid***
498 ## The configuration file afm-unit.conf
500 The integration of the framework with systemd
501 mainly consists of creating the systemd unit
502 files corresponding to the need and requirements
503 of the installed widgets.
505 This configuration file named `afm-unit.conf` installed
506 on the system with the path `/etc/afm/afm-unit.conf`
507 describes how to generate all units from the *config.xml*
508 configuration files of widgets.
509 The description uses an extended version of the templating
510 formalism of [mustache][] to describes all the units.
512 Let present how it works using the following diagram that
513 describes graphically the workflow of creating the unit
514 files for systemd `afm-unit.conf` from the configuration
515 file of the widget `config.xml`:
517 ![make-units](pictures/make-units.svg)
519 In a first step, and because [mustache][] is intended
520 to work on JSON representations, the configuration file is
521 translated to an internal JSON representation.
522 This representation is shown along the examples of the documentation
523 of the config files of widgets.
525 In a second step, the mustache template `afm-unit.conf`
526 is instantiated using the C library [mustach][] that follows
527 the rules of [mustache][mustache] and with all its available
530 - use of colon (:) for explicit substitution
531 - test of values with = or =!
533 In a third step, the result of instantiating `afm-unit.conf`
534 for the widget is split in units.
535 To achieve that goal, the lines containing specific directives are searched.
536 Any directive occupy one full line.
540 Produce an empty line at the end
541 - %begin systemd-unit
543 Delimit the produced unit, its begin and its end
545 - %systemd-unit system
546 Tells the kind of unit (user/system)
547 - %systemd-unit service NAME
548 - %systemd-unit socket NAME
549 Gives the name and type (service or socket) of the unit.
550 The extension is automatically computed from the type
551 and must not be set in the name.
552 - %systemd-unit wanted-by NAME
553 Tells to install a link to the unit in the wants of NAME
555 Then the computed units are then written to the filesystem
556 and inserted in systemd.
558 The generated unit files will contain variables for internal
559 use of the framework.
560 These variables are starting with `X-AFM-`.
561 The variables starting with `X-AFM-` but not with `X-AFM--` are
562 the public variables.
563 These variables will be returned by the
564 framework as the details of an application (see **afm-util detail ...**).
566 Variables starting with `X-AFM--` are private to the framework.
567 By example, the variable `X-AFM--http-port` is used to
568 record the allocated port for applications.
570 [mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache"
571 [mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates"
572 [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps"
573 [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets"
574 [libxml2]: http://xmlsoft.org/html/index.html "libxml2"
575 [app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
576 [meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies"
577 [openssl]: https://www.openssl.org "OpenSSL"
578 [xmlsec]: https://www.aleksey.com/xmlsec "XMLSec"
579 [json-c]: https://github.com/json-c/json-c "JSON-c"
580 [d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus"
581 [libzip]: http://www.nih.at/libzip "libzip"
582 [cmake]: https://cmake.org "CMake"
583 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
584 [tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page"
585 [tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview"
586 [semantic-version]: http://semver.org/ "Semantic versioning"