docs/2.2-config.xml.md

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