# Widget configuration file - config.xml

The packages have a structure similar to the structure of the widget as described
by the W3C's technical recommendations [Packaged Web Apps (Widgets)][widgets]
and [XML Digital Signatures for Widgets][widgets-digsig]
that specifies the configuration file **config.xml**.

## Overview

The file **config.xml** describes important data of the application
to the framework:

- the unique identifier of the application
- the name of the application
- the type of the application
- the icon of the application
- the permissions linked to the application
- the services and dependencies of the application

The file MUST be at the root of the package and MUST be case sensitively name
***config.xml***.

The file **config.xml** is a XML file described by the document
[widgets].

Here is the example of the config file for the QML application SmartHome.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
  <name>SmartHome</name>
  <icon src="smarthome.png"/>
  <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
  <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
automated house. The user interface is completely done with QML.</description>
  <author>Qt team</author>
  <license>GPL</license>
</widget>
```

The most important items are:

- **<widget id="......"\>**: gives the id of the package. It must be unique.

- **<widget version="......"\>**: gives the version of the package

- **<icon src="..."\>**: gives a path to the icon of the application
  (can be repeated with different sizes)

- **<content src="..." type="..."\>**: this indicates the entry point and its type.

## Standard elements of "config.xml"

### The element package

#### the attribute id of package

The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.

Values for *id* are any non empty string containing only latin letters,
arabic digits, and the three characters '.' (dot), '-' (dash) and
'\_' (underscore).

Authors can use a mnemonic id or can pick a unique id using
command **uuid** or **uuidgen**.

### the attribute version of package

The attribute *version* is mandatory (for version 2.x, blowfish).

Values for *version* are any non empty string containing only latin letters,
arabic digits, and the three characters '.' (dot), '-' (dash) and
'\_' (underscore).

Version values are dot separated fields MAJOR.MINOR.REVISION.
Such version would preferably follow guidelines of
[semantic versioning][semantic-version].

### The element content

The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
(subject to localization) with its attribute *src*.

The content designed depends on its type. See below for the known types.

### The element icon

The element *icon* is mandatory (for version 2.x, blowfish) and must
be unique. It must designate an image file with its attribute *src*.

## AGL features

The AGL framework uses the feature tag for specifying security and binding
requirement of the package.

Since the migration of the framework to leverage systemd power,
the features are of important use to:

- declare more than just an application
- declare the expected dependencies
- declare the expected permissions
- declare the exported apis

The specification of [widgets][widgets] is intended to describe
only one application.
In the present case, we expect to describe more than just an application.
For example, a publisher could provide a package containing a service,
an application for tuning that service, an application that
leverage the service.
Here, the term of service means a background application that
runs without IHM and whose public api can be accessed by other
applications.

So the features are used to describe each of the possible
units of packages.
The "standard" unit in the meaning of [widgets][widgets]
is called the "main" unit.

### required-api: feature name="urn:AGL:widget:required-api"

List of the api required by the package.

Each required api must be explicit using a `<param>` entry.

Example:

```xml
<feature name="urn:AGL:widget:required-api">
  <param name="#target" value="main" />
  <param name="gps" value="auto" />
  <param name="afm-main" value="link" />
</feature>
```

This will be *virtually* translated for mustaches to the JSON

```json
"required-api": [
   { "name": "gps", "value": "auto" },
   { "name": "afm-main", "value": "link" }
 ]
```

#### required-api: param name="#target"

OPTIONAL

Declares the name of the unit requiring the listed apis.
Only one instance of the param "#target" is allowed.
When there is not instance of this param, it behave as if
the target main was specified.

#### required-api: param name=[required api name]

The name is the name of the required API.

The value describes how to connect to the required api.
It is either:

- auto:
  The framework set automatically the kind of
  the connection to the API

- ws:
  The framework connect using internal websockets

- dbus: [OBSOLETE, shouldn't be used currently]
  The framework connect using internal dbus

- tcp:
  In that case, the name is the URI to access the service.
  The framework connect using a URI of type
   HOST:PORT/API
  API gives the name of the imported api.

- cloud: [PROPOSAL - NOT IMPLEMENTED]
  The framework connect externally using websock.
  In that case, the name includes data to access the service.
  Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`

### required-binding: feature name="urn:AGL:widget:required-binding"

List of the bindings required by the package.

Note: Since AGL 6 (FF - Funky Flounder),
the binder implements bindings version 3 that allow the declaration
of 0, 1 or more APIs by one binding. In other words, the equivalency
one binding = one API is lost. At the same time the framework added
the ability to use bindings exported by other packages.

Each required binding must be explicit using a `<param>` entry.

Example:

```xml
<feature name="urn:AGL:widget:required-binding">
  <param name="libexec/binding-gps.so" value="local" />
  <param name="extra" value="extern" />
</feature>
```

This will be *virtually* translated for mustaches to the JSON

```json
"required-binding": [
   { "name": "libexec/binding-gps.so", "value": "local" },
   { "name": "extra", "value": "extern" }
 ]
```

#### required-binding: param name=[name or path]

The name or the path of the required BINDING.

The value describes how to connect to the required binding.
It is either:

- local:
  The binding is a local shared object.
  In that case, the name is the relative path of the
  shared object to be loaded.

- extern:
  The binding is external. The name is the exported binding name.
  See provided-binding.

### provided-binding: feature name="urn:AGL:widget:provided-binding"

This feature allows to export a binding to other binders.
The bindings whose relative name is given as value is exported to
other binders under the given name.

Each provided binding must be explicit using a `<param>` entry.

Example:

```xml
<feature name="urn:AGL:widget:provided-binding">
  <param name="extra" value="export/binding-gps.so" />
</feature>
```

This will be *virtually* translated for mustaches to the JSON

```json
"provided-binding": [
   { "name": "extra", "value": "export/binding-gps.so" }
 ]
```

#### provided-binding: param name=[exported name]

Exports a local binding to other applications.

The value must contain the path to the exported binding.

### required-permission: feature name="urn:AGL:widget:required-permission"

List of the permissions required by the unit.

Each required permission must be explicit using a `<param>` entry.

Example:

```xml
  <feature name="urn:AGL:widget:required-permission">
    <param name="#target" value="geoloc" />
    <param name="urn:AGL:permission:real-time" value="required" />
    <param name="urn:AGL:permission:syscall:*" value="required" />
  </feature>
```

This will be *virtually* translated for mustaches to the JSON

```json
"required-permission":{
  "urn:AGL:permission:real-time":{
    "name":"urn:AGL:permission:real-time",
    "value":"required"
  },
  "urn:AGL:permission:syscall:*":{
    "name":"urn:AGL:permission:syscall:*",
    "value":"required"
  }
}
```

#### required-permission: param name="#target"

OPTIONAL

Declares the name of the unit requiring the listed permissions.
Only one instance of the param "#target" is allowed.
When there is not instance of this param, it behave as if
the target main was specified.

#### required-permission: param name=[required permission name]

The value is either:

- required: the permission is mandatorily needed except if the feature
  isn't required (required="false") and in that case it is optional.
- optional: the permission is optional

### provided-unit: feature name="urn:AGL:widget:provided-unit"

This feature is made for declaring new units
for the package.
Using this feature, a software publisher
can provide more than one application in the same package.

Example:

```xml
  <feature name="urn:AGL:widget:provided-unit">
    <param name="#target" value="geoloc" />
    <param name="description" value="binding of name geoloc" />
    <param name="content.src" value="index.html" />
    <param name="content.type" value="application/vnd.agl.service" />
  </feature>
```

This will be *virtually* translated for mustaches to the JSON

```json
    {
      "#target":"geoloc",
      "description":"binding of name geoloc",
      "content":{
        "src":"index.html",
        "type":"application\/vnd.agl.service"
      },
      ...
    }
```

#### provided-unit: param name="#target"

REQUIRED

Declares the name of the unit. The default unit, the unit
of the main of the package, has the name "main".
The value given here must be unique within the widget file.
It will be used in other places of the package config.xml file to
designate the unit.

Only one instance of the param "#target" is allowed.
The value can't be "main".

#### provided-unit: param name="content.type"

REQUIRED

The mimetype of the provided unit.

#### provided-unit: param name="content.src"

A path to the source

#### other parameters

The items that can be set for the main unit
can also be set using the params if needed.

- description
- name.content
- name.short
- ...

### provided-api: feature name="urn:AGL:widget:provided-api"

Use this feature for exporting one or more API of a unit
to other packages of the platform.

This feature is an important feature of the framework.

Example:

```xml
  <feature name="urn:AGL:widget:provided-api">
    <param name="#target" value="geoloc" />
    <param name="geoloc" value="auto" />
    <param name="moonloc" value="auto" />
  </feature>
```

This will be *virtually* translated for mustaches to the JSON

```json
      "provided-api":[
        {
          "name":"geoloc",
          "value":"auto"
        },
        {
          "name":"moonloc",
          "value":"auto"
        }
      ],
```

#### provided-api: param name="#target"

OPTIONAL

Declares the name of the unit exporting the listed apis.
Only one instance of the param "#target" is allowed.
When there is not instance of this param, it behave as if
the target main was specified.

#### provided-api: param name=[name of exported api]

The name give the name of the api that is exported.

The value is one of the following values:

- ws:
  export the api using UNIX websocket

- dbus: [OBSOLETE, shouldn't be used currently]
  export the API using dbus

- auto:
  export the api using the default method(s).

- tcp:
  In that case, the name is the URI used for exposing the service.
  The URI is of type
   HOST:PORT/API
  API gives the name of the exported api.

### file-properties: feature name="urn:AGL:widget:file-properties"

Use this feature for setting properties to files of the package.
At this time, this feature only allows to set executable flag
for making companion program executable explicitly.

Example:

```xml
  <feature name="urn:AGL:widget:file-properties">
    <param name="flite" value="executable" />
    <param name="jtalk" value="executable" />
  </feature>
```

#### file-properties: param name="path"

The name is the relative path of the file whose property
must be set.

The value must be "executable" to make the file executable.


[mustach]:          https://gitlab.com/jobol/mustach                                "basic C implementation of mustache"
[mustache]:         http://mustache.github.io/mustache.5.html                       "mustache - Logic-less templates"
[widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
[widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
[libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
[app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
[meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
[openssl]:          https://www.openssl.org                                         "OpenSSL"
[xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
[json-c]:           https://github.com/json-c/json-c                                "JSON-c"
[d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
[libzip]:           http://www.nih.at/libzip                                        "libzip"
[cmake]:            https://cmake.org                                               "CMake"
[sec-lsm-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Sec-lsm-Manager"
[tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
[tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
[semantic-version]: http://semver.org/                                              "Semantic versioning"
