1 Configuration file - config.xml
2 ===============================
4 The widgets are described by the W3C's technical recommendations
5 [Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig]
6 that specifies the configuration file **config.xml**.
11 The file **config.xml** describes important data of the application
14 - the unique identifier of the application
15 - the name of the application
16 - the type of the application
17 - the icon of the application
18 - the permissions linked to the application
19 - the services and dependencies of the application
21 The file MUST be at the root of the widget and MUST be case sensitively name
24 The file **config.xml** is a XML file described by the document
27 Here is the example of the config file for the QML application SmartHome.
30 <?xml version="1.0" encoding="UTF-8"?>
31 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
32 <name>SmartHome</name>
33 <icon src="smarthome.png"/>
34 <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
35 <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
36 automated house. The user interface is completely done with QML.</description>
37 <author>Qt team</author>
38 <license>GPL</license>
42 The most important items are:
44 - **<widget id="......"\>**: gives the id of the widget. It must be unique.
46 - **<widget version="......"\>**: gives the version of the widget
48 - **<icon src="..."\>**: gives a path to the icon of the application
49 (can be repeated with different sizes)
51 - **<content src="..." type="..."\>**: this indicates the entry point and its type.
53 Standard elements of "config.xml"
54 ---------------------------------
56 ### The element widget
58 #### the attribute id of widget
60 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
62 Values for *id* are any non empty string containing only latin letters,
63 arabic digits, and the three characters '.' (dot), '-' (dash) and
66 Authors can use a mnemonic id or can pick a unique id using
67 command **uuid** or **uuidgen**.
69 ### the attribute version of widget
71 The attribute *version* is mandatory (for version 2.x, blowfish).
73 Values for *version* are any non empty string containing only latin letters,
74 arabic digits, and the three characters '.' (dot), '-' (dash) and
77 Version values are dot separated fields MAJOR.MINOR.REVISION.
78 Such version would preferably follow guidelines of
79 [semantic versioning][semantic-version].
81 ### The element content
83 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
84 (subject to localization) with its attribute *src*.
86 The content designed depends on its type. See below for the known types.
90 The element *icon* is mandatory (for version 2.x, blowfish) and must
91 be unique. It must designate an image file with its attribute *src*.
96 The AGL framework uses the feature tag for specifying security and binding
97 requirement of the widget.
99 Since the migration of the framework to leverage systemd power,
100 the features are of important use to:
102 - declare more than just an application
103 - declare the expected dependencies
104 - declare the expected permissions
105 - declare the exported apis
107 The specification of [widgets][widgets] is intended to describe
108 only one application. In the present case, we expect to describe
109 more than just an application. For example, a publisher could
110 provide a widget containing a service, an application for tuning
111 that service, an application that leverage the service.
112 Here, the term of service means a background application that
113 runs without IHM and whose public api can be accessed by other
116 So the features are used to describe each of the possible
117 units of widgets. The "standard" unit in the
118 meaning of [widgets][widgets] is called the "main" unit.
120 ### feature name="urn:AGL:widget:required-api"
122 List of the api required by the widget.
124 Each required api must be explicited using a <param> entry.
128 <feature name="urn:AGL:widget:required-api">
129 <param name="#target" value="main" />>
130 <param name="gps" value="auto" />
131 <param name="afm-main" value="link" />
135 This will be *virtually* translated for mustaches to the JSON
138 { "name": "gps", "value": "auto" },
139 { "name": "afm-main", "value": "link" }
143 #### 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 #### 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.
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.
167 The framework set automatically the kind of
168 the connection to the API
172 The framework connect using internal websockets
176 The framework connect using internal dbus
180 The framework connect in memory by dynamically linking
182 - cloud: [PROPOSAL - NOT IMPLEMENTED]
184 The framework connect externally using websock.
185 In that case, the name includes data to access the service.
186 Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`
188 ### feature name="urn:AGL:widget:required-permission"
190 List of the permissions required by the unit.
192 Each required permission must be explicited using a <param> entry.
197 <feature name="urn:AGL:widget:required-permission">
198 <param name="#target" value="geoloc" />
199 <param name="urn:AGL:permission:real-time" value="required" />
200 <param name="urn:AGL:permission:syscall:*" value="required" />
204 This will be *virtually* translated for mustaches to the JSON
207 "required-permission":{
208 "urn:AGL:permission:real-time":{
209 "name":"urn:AGL:permission:real-time",
212 "urn:AGL:permission:syscall:*":{
213 "name":"urn:AGL:permission:syscall:*",
219 #### param name="#target"
223 Declares the name of the unit requiring the listed permissions.
224 Only one instance of the param "#target" is allowed.
225 When there is not instance of this param, it behave as if
226 the target main was specified.
228 #### param name=[required permission name]
232 - required: the permission is mandatorily needed except if the feature
233 isn't required (required="false") and in that case it is optional.
234 - optional: the permission is optional
237 ### feature name="urn:AGL:widget:provided-unit"
239 This feature is made for declaring new units
240 for the widget. Using this feature, a software publisher
241 can provide more than one application in the same widget.
245 <feature name="urn:AGL:widget:provided-unit">
246 <param name="#target" value="geoloc" />
247 <param name="description" value="binding of name geoloc" />
248 <param name="content.src" value="index.html" />
249 <param name="content.type" value="application/vnd.agl.service" />
253 This will be *virtually* translated for mustaches to the JSON
257 "description":"binding of name geoloc",
260 "type":"application\/vnd.agl.service"
266 #### param name="#target"
270 Declares the name of the unit. The default unit, the unit
271 of the main of the widget, has the name "main". The value
272 given here must be unique within the widget file. It will
273 be used in other places of the widget config.xml file to
276 Only one instance of the param "#target" is allowed.
277 The value can't be "main".
279 #### param name="content.type"
283 The mimetype of the provided unit.
285 #### param name="content.src"
289 #### other parameters
291 The items that can be set for the main unit
292 can also be set using the params if needed.
300 ### feature name="urn:AGL:widget:provided-api"
302 Use this feature for exporting one or more API of a unit
303 to other widgets of the platform.
305 This feature is an important feature of the framework.
310 <feature name="urn:AGL:widget:provided-api">
311 <param name="#target" value="geoloc" />
312 <param name="geoloc" value="auto" />
313 <param name="moonloc" value="auto" />
317 This will be *virtually* translated for mustaches to the JSON
332 #### param name="#target"
337 Declares the name of the unit exporting the listed apis.
338 Only one instance of the param "#target" is allowed.
339 When there is not instance of this param, it behave as if
340 the target main was specified.
343 #### param name=[name of exported api]
345 The name give the name of the api that is exported.
347 The value is one of the following values:
351 export the api using UNIX websocket
355 export the API using dbus
359 export the api using the default method(s).
365 The configuration file ***/etc/afm/afm-unit.conf*** defines
366 how to create systemd units for widgets.
368 Known types for the type of content are:
372 content.src designates the home page of the application
374 - ***application/vnd.agl.native***
375 AGL compatible native,
376 content.src designates the relative path of the binary.
378 - ***application/vnd.agl.service***:
379 AGL service, content.src is not used.
381 - ***application/x-executable***:
383 content.src designates the relative path of the binary.
384 For such application, only security setup is made.
386 Adding more types is easy, it just need to edit the configuration
387 file ***afm-unit.conf***.
389 ### Older content type currently not supported at the moment.
391 This types were defined previously when the framework was not
392 leveraging systemd. The transition to systemd let these types
395 - ***application/vnd.agl.url***
396 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
397 - ***application/vnd.agl.qml.hybrid***
398 - ***application/vnd.agl.html.hybrid***
401 The configuration file afm-unit.conf
402 ====================================
404 The integration of the framework with systemd
405 mainly consists of creating the systemd unit
406 files corresponding to the need and requirements
407 of the installed widgets.
409 This configuration file named `afm-unit.conf` installed
410 on the system with the path `/etc/afm/afm-unit.conf`
411 describes how to generate all units from the *config.xml*
412 configuration files of widgets. The description uses an extended
413 version of the templating formalism of [mustache][]
414 to describes all the units.
416 Let present how it works using the following diagram that
417 describes graphically the workflow of creating the unit
418 files for systemd `afm-unit.conf` from the configuration
419 file of the widget `config.xml`:
421 ![make-units][make-units]
423 In a first step, and because [mustache][] is intended
424 to work on JSON representations, the configuration file is
425 translated to an internal JSON representation. This
426 representation is shown along the examples of the documentation
427 of the config files of widgets.
429 In a second step, the mustache template `afm-unit.conf`
430 is instantiated using the C library [mustach][] that follows
431 the rules of [mustache][mustache] and with all its available
434 - use of colon (:) for explicit substitution
435 - test of values with = or =!
437 In a third step, the result of instantiating `afm-unit.conf`
438 for the widget is split in units. To achieve that goal,
439 the lines containing specific directives are searched.
440 Any directive occupy one full line. The directives are:
444 Produce an empty line at the end
446 - %begin systemd-unit
449 Delimit the produced unit, its begin and its end
452 - %systemd-unit system
454 Tells the kind of unit (user/system)
456 - %systemd-unit service NAME
457 - %systemd-unit socket NAME
459 Gives the name and type (service or socket) of the unit.
460 The extension is automatically computed from the type
461 and must not be set in the name.
463 - %systemd-unit wanted-by NAME
465 Tells to install a link to the unit in the wants of NAME
467 Then the computed units are then written to the filesystem
468 and inserted in systemd.
470 The generated unit files will contain variables for internal
471 use of the framework. These variables are starting with `X-AFM-`.
472 The variables starting with `X-AFM-` but not with `X-AFM--` are
473 the public variables. These variables will be returned by the
474 framework as the details of an application (see **afm-util detail ...**).
476 Variables starting with `X-AFM--` are private to the framework.
477 By example, the variable `X-AFM--http-port` is used to
478 record the allocated port for applications.
481 [mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache"
482 [mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates"
483 [make-units]: pictures/make-units.svg
484 [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps"
485 [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets"
486 [libxml2]: http://xmlsoft.org/html/index.html "libxml2"
487 [app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
490 [meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies"
491 [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps"
492 [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets"
493 [libxml2]: http://xmlsoft.org/html/index.html "libxml2"
494 [openssl]: https://www.openssl.org "OpenSSL"
495 [xmlsec]: https://www.aleksey.com/xmlsec "XMLSec"
496 [json-c]: https://github.com/json-c/json-c "JSON-c"
497 [d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus"
498 [libzip]: http://www.nih.at/libzip "libzip"
499 [cmake]: https://cmake.org "CMake"
500 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
501 [app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
502 [tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page"
503 [tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview"
504 [semantic-version]: http://semver.org/ "Semantic versioning"