docs/config.xml.md

   1 The configuration file config.xml
   2 ===========
   3
   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**.
   7
   8 Overview
   9 --------
  10
  11 The file **config.xml** describes important data of the application
  12 to the framework:
  13
  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 dependancies of the application
  20
  21 The file MUST be at the root of the widget and MUST be case sensitively name
  22 ***config.xml***.
  23
  24 The file **config.xml** is a XML file described by the document
  25 [widgets].
  26
  27 Here is the example of the config file for the QML application SmartHome.
  28
  29 ```xml
  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>
  39 </widget>
  40 ```
  41
  42 The most important items are:
  43
  44 - **<widget id="......"\>**: gives the id of the widget. It must be unique.
  45
  46 - **<widget version="......"\>**: gives the version of the widget
  47
  48 - **<icon src="..."\>**: gives a path to the icon of the application
  49   (can be repeated with different sizes)
  50
  51 - **<content src="..." type="..."\>**: this indicates the entry point and its type.
  52
  53 Standard elements of "config.xml"
  54 ---------------------------------
  55
  56 ### The element widget
  57
  58 #### the attribute id of widget
  59
  60 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
  61
  62 Values for *id* are any non empty string containing only latin letters,
  63 arabic digits, and the three characters '.' (dot), '-' (dash) and
  64 '\_' (underscore).
  65
  66 Authors can use a mnemonic id or can pick a unique id using
  67 command **uuid** or **uuidgen**.
  68
  69 ### the attribute version of widget
  70
  71 The attribute *version* is mandatory (for version 2.x, blowfish).
  72
  73 Values for *version* are any non empty string containing only latin letters,
  74 arabic digits, and the three characters '.' (dot), '-' (dash) and
  75 '\_' (underscore).
  76
  77 Version values are dot separated fields MAJOR.MINOR.REVISION.
  78 Such version would preferabily follow guidelines of
  79 [semantic versionning][semantic-version].
  80
  81 ### The element content
  82
  83 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
  84 (subject to localisation) with its attribute *src*.
  85
  86 The content designed depends on its type. See below for the known types.
  87
  88 ### The element icon
  89
  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*.
  92
  93 AGL features
  94 ------------
  95
  96 The AGL framework uses the feature tag for specifying security and binding
  97 requirement of the widget.
  98
  99 Since the migration of the framework to leverage systemd power,
 100 the features are of important use to:
 101
 102  - declare more than just an application
 103  - declare the expected dependencies
 104  - declare the expected permissions
 105  - declare the exported apis
 106
 107 The specification of [widgets][widgets] is intentded 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
 114 applications.
 115
 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.
 119
 120 ### feature name="urn:AGL:widget:required-api"
 121
 122 List of the api required by the widget.
 123
 124 Each required api must be explicited using a <param> entry.
 125
 126 Example:
 127 ```xml
 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" />
 132 </feature>
 133 ```
 134
 135 This will be *virtually* translated for mustaches to the JSON
 136 ```json
 137 "required-api": [
 138    { "name": "gps", "value": "auto" },
 139    { "name": "afm-main", "value": "link" }
 140  ]
 141 ```
 142
 143 #### param name="#target"
 144
 145 OPTIONAL
 146
 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.
 151
 152 #### param name=[required api name]
 153
 154 The name is the name of the required API.
 155
 156 The value describes how to connect to the required api.
 157 It is either:
 158
 159  - local:
 160
 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.
 164
 165  - auto:
 166
 167    The framework set automatically the kind of
 168    the connection to the API
 169
 170  - ws:
 171
 172    The framework connect using internal websockets
 173
 174  - dbus:
 175
 176    The framework connect using internal dbus
 177
 178  - link:
 179
 180    The framework connect in memory by dinamically linking
 181
 182  - cloud: [PROPOSAL - NOT IMPLEMENTED]
 183
 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" />`
 187
 188 ### feature name="urn:AGL:widget:required-permission"
 189
 190 List of the permissions required by the unit.
 191
 192 Each required permission must be explicited using a <param> entry.
 193
 194 Example:
 195
 196 ```xml
 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" />
 201   </feature>
 202 ```
 203
 204 This will be *virtually* translated for mustaches to the JSON
 205
 206 ```json
 207 "required-permission":{
 208   "urn:AGL:permission:real-time":{
 209     "name":"urn:AGL:permission:real-time",
 210     "value":"required"
 211   },
 212   "urn:AGL:permission:syscall:*":{
 213     "name":"urn:AGL:permission:syscall:*",
 214     "value":"required"
 215   }
 216 }
 217 ```
 218
 219 #### param name="#target"
 220
 221 OPTIONAL
 222
 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.
 227
 228 #### param name=[required permission name]
 229
 230 The value is either:
 231
 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
 235
 236
 237 ### feature name="urn:AGL:widget:provided-unit"
 238
 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.
 242
 243 Example:
 244 ```xml
 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" />
 250   </feature>
 251 ```
 252
 253 This will be *virtually* translated for mustaches to the JSON
 254 ```json
 255     {
 256       "#target":"geoloc",
 257       "description":"binding of name geoloc",
 258       "content":{
 259         "src":"index.html",
 260         "type":"application\/vnd.agl.service"
 261       },
 262       ...
 263     }
 264 ```
 265
 266 #### param name="#target"
 267
 268 REQUIRED
 269
 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
 274 designate the unit.
 275
 276 Only one instance of the param "#target" is allowed.
 277 The value can't be "main".
 278
 279 #### param name="content.type"
 280
 281 REQUIRED
 282
 283 The mimetype of the provided unit.
 284
 285 #### param name="content.src"
 286
 287 A path to the
 288
 289 #### other parameters
 290
 291 The items that can be set for the main unit
 292 can also be set using the params if needed.
 293
 294  - description
 295  - name.content
 296  - name.short
 297  - ...
 298
 299
 300 ### feature name="urn:AGL:widget:provided-api"
 301
 302 Use this feature for exporting one or more API of a unit
 303 to other widgets of the platform.
 304
 305 This feature is an important feature of the framework.
 306
 307 Example:
 308
 309 ```xml
 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" />
 314   </feature>
 315 ```
 316
 317 This will be *virtually* translated for mustaches to the JSON
 318
 319 ```json
 320       "provided-api":[
 321         {
 322           "name":"geoloc",
 323           "value":"auto"
 324         },
 325         {
 326           "name":"moonloc",
 327           "value":"auto"
 328         }
 329       ],
 330 ```
 331
 332 #### param name="#target"
 333
 334
 335 OPTIONAL
 336
 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.
 341
 342
 343 #### param name=[name of exported api]
 344
 345 The name give the name of the api that is exported.
 346
 347 The value is one of the following values:
 348
 349  - ws:
 350
 351    export the api using UNIX websocket
 352
 353  - dbus:
 354
 355    export the API using dbus
 356
 357  - auto:
 358
 359    export the api using the default method(s).
 360
 361
 362 Known content types
 363 -------------------
 364
 365 The configuration file ***/etc/afm/afm-unit.conf*** defines
 366 how to create systemd units for widgets.
 367
 368 Known types for the type of content are:
 369
 370 - ***text/html***:
 371    HTML application,
 372    content.src designates the home page of the application
 373
 374 - ***application/x-executable***:
 375    Native application,
 376    content.src designates the relative path of the binary
 377
 378 - ***application/vnd.agl.service***:
 379    AGL service, content.src is not used.
 380
 381 Adding more types is easy, it just need to edit the configuration
 382 file ***afm-unit.conf***.
 383
 384 ### Older content type currently not supported at the moment.
 385
 386 This types were defined previously when the framework was not
 387 leveraging systemd. The transition to systemd let these types
 388 out at the moment.
 389
 390 - ***application/vnd.agl.url***
 391 - ***application/vnd.agl.native***
 392 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
 393 - ***application/vnd.agl.qml.hybrid***
 394 - ***application/vnd.agl.html.hybrid***
 395
 396
 397 The configuration file afm-unit.conf
 398 ====================================
 399
 400 The integration of the framework with systemd
 401 mainly consists of creating the systemd unit
 402 files corresponding to the need and requirements
 403 of the installed widgets.
 404
 405 This configuration file named `afm-unit.conf` installed
 406 on the system wiht the path `/etc/afm/afm-unit.conf`
 407 describes how to generate all units from the *config.xml*
 408 configuration files of widgets. The description uses an extended
 409 version of the templating formalism of [mustache][]
 410 to describes all the units.
 411
 412 Let present how it works using the following diagram that
 413 describes graphically the workflow of creating the unit
 414 files for systemd `afm-unit.conf` from the configuration
 415 file of the widget `config.xml`:
 416
 417 ![make-units][make-units]
 418
 419 In a first step, and because [mustache][] is intended
 420 to work on JSON representations, the configuration file is
 421 translated to an internal JSON representation. This
 422 representation is shown along the examples of the documentation
 423 of the config files of widgets.
 424
 425 In a second step, the mustache template `afm-unit.conf`
 426 is instanciated using the C library [mustach][] that follows
 427 the rules of [mustache][mustache] and with all its available
 428 extensions:
 429
 430  - use of colon (:) for explicit substitution
 431  - test of values with = or =!
 432
 433 In a third step, the result of instanciating `afm-unit.conf`
 434 for the widget is splited in units. To achieve that goal,
 435 the lines containing specific directives are searched.
 436 Any directive occupy one full line. The directives are:
 437
 438   - %nl
 439
 440     Produce an empty line at the end
 441
 442   - %begin systemd-unit
 443   - %end systemd-unit
 444
 445     Delimit the produced unit, its begin and its end
 446
 447   - %systemd-unit user
 448   - %systemd-unit system
 449
 450     Tells the kind of unit (user/system)
 451
 452   - %systemd-unit service NAME
 453   - %systemd-unit socket NAME
 454
 455     Gives the name and type (service or socket) of the unit.
 456     The extension is automatically computed from the type
 457     and must not be set in the name.
 458
 459   - %systemd-unit wanted-by NAME
 460
 461     Tells to install a link to the unit in the wants of NAME
 462
 463 Then the computed units are then written to the filesystem
 464 and inserted in systemd.
 465
 466 The generated unit files will contain variables for internal
 467 use of the framework. These variables are starting with `X-AFM-`.
 468 The variables starting with `X-AFM-` but not with `X-AFM--` are
 469 the public variables. These variables will be returned by the
 470 framework as the details of an application (see **afm-util detail ...**).
 471
 472 Variables starting with `X-AFM--` are private to the framework.
 473 By example, the variable  `X-AFM--http-port` is used to
 474 record the allocated port for applications.
 475
 476
 477 [mustach]:          https://gitlab.com/jobol/mustach                                "basic C implementation of mustache"
 478 [mustache]:         http://mustache.github.io/mustache.5.html                       "mustache - Logic-less templates"
 479 [make-units]:       pictures/make-units.svg
 480 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 481 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 482 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 483 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 484
 485
 486 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 487 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 488 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 489 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 490 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 491 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 492 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 493 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 494 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 495 [cmake]:            https://cmake.org                                               "CMake"
 496 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 497 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 498 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 499 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
 500 [semantic-version]: http://semver.org/                                              "Semantic versionning"
 501
 502
 503