docs/2.2-config.xml.md

   1 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 dependencies 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 preferably follow guidelines of
  79 [semantic versioning][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 localization) 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 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
 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 dynamically 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/vnd.agl.native***
 375    AGL compatible native,
 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 - ***application/x-executable***:
 382    Native application,
 383    content.src designates the relative path of the binary.
 384    For such application, only security setup is made.
 385
 386 Adding more types is easy, it just need to edit the configuration
 387 file ***afm-unit.conf***.
 388
 389 ### Older content type currently not supported at the moment.
 390
 391 This types were defined previously when the framework was not
 392 leveraging systemd. The transition to systemd let these types
 393 out at the moment.
 394
 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***
 399
 400
 401 The configuration file afm-unit.conf
 402 ====================================
 403
 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.
 408
 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.
 415
 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`:
 420
 421 ![make-units][make-units]
 422
 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.
 428
 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
 432 extensions:
 433
 434  - use of colon (:) for explicit substitution
 435  - test of values with = or =!
 436
 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:
 441
 442   - %nl
 443
 444     Produce an empty line at the end
 445
 446   - %begin systemd-unit
 447   - %end systemd-unit
 448
 449     Delimit the produced unit, its begin and its end
 450
 451   - %systemd-unit user
 452   - %systemd-unit system
 453
 454     Tells the kind of unit (user/system)
 455
 456   - %systemd-unit service NAME
 457   - %systemd-unit socket NAME
 458
 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.
 462
 463   - %systemd-unit wanted-by NAME
 464
 465     Tells to install a link to the unit in the wants of NAME
 466
 467 Then the computed units are then written to the filesystem
 468 and inserted in systemd.
 469
 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 ...**).
 475
 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.
 479
 480
 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"
 488
 489
 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"
 505
 506
 507