+++ /dev/null
-The configuration file config.xml
-===========
-
-The widgets are 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 dependancies of the application
-
-The file MUST be at the root of the widget 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 widget. It must be unique.
-
-- **<widget version="......"\>**: gives the version of the widget
-
-- **<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 widget
-
-#### the attribute id of widget
-
-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 widget
-
-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 preferabily follow guidelines of
-[semantic versionning][semantic-version].
-
-### The element content
-
-The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
-(subject to localisation) 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 widget.
-
-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 intentded 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 widget 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 widgets. The "standard" unit in the
-meaning of [widgets][widgets] is called the "main" unit.
-
-### feature name="urn:AGL:widget:required-api"
-
-List of the api required by the widget.
-
-Each required api must be explicited 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" }
- ]
-```
-
-#### 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.
-
-#### 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:
-
- - local:
-
- The binding is a local shared object.
- In that case, the name is the relative path of the
- shared object to be loaded.
-
- - auto:
-
- The framework set automatically the kind of
- the connection to the API
-
- - ws:
-
- The framework connect using internal websockets
-
- - dbus:
-
- The framework connect using internal dbus
-
- - link:
-
- The framework connect in memory by dinamically linking
-
- - 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" />`
-
-### feature name="urn:AGL:widget:required-permission"
-
-List of the permissions required by the unit.
-
-Each required permission must be explicited 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"
- }
-}
-```
-
-#### 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.
-
-#### 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
-
-
-### feature name="urn:AGL:widget:provided-unit"
-
-This feature is made for declaring new units
-for the widget. Using this feature, a software publisher
-can provide more than one application in the same widget.
-
-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"
- },
- ...
- }
-```
-
-#### param name="#target"
-
-REQUIRED
-
-Declares the name of the unit. The default unit, the unit
-of the main of the widget, has the name "main". The value
-given here must be unique within the widget file. It will
-be used in other places of the widget config.xml file to
-designate the unit.
-
-Only one instance of the param "#target" is allowed.
-The value can't be "main".
-
-#### param name="content.type"
-
-REQUIRED
-
-The mimetype of the provided unit.
-
-#### param name="content.src"
-
-A path to the
-
-#### 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
- - ...
-
-
-### feature name="urn:AGL:widget:provided-api"
-
-Use this feature for exporting one or more API of a unit
-to other widgets 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"
- }
- ],
-```
-
-#### 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.
-
-
-#### 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:
-
- export the API using dbus
-
- - auto:
-
- export the api using the default method(s).
-
-
-Known content types
--------------------
-
-The configuration file ***/etc/afm/afm-unit.conf*** defines
-how to create systemd units for widgets.
-
-Known types for the type of content are:
-
-- ***text/html***:
- HTML application,
- content.src designates the home page of the application
-
-- ***application/vnd.agl.native***
- AGL compatible native,
- content.src designates the relative path of the binary.
-
-- ***application/vnd.agl.service***:
- AGL service, content.src is not used.
-
-- ***application/x-executable***:
- Native application,
- content.src designates the relative path of the binary.
- For such application, only security setup is made.
-
-Adding more types is easy, it just need to edit the configuration
-file ***afm-unit.conf***.
-
-### Older content type currently not supported at the moment.
-
-This types were defined previously when the framework was not
-leveraging systemd. The transition to systemd let these types
-out at the moment.
-
-- ***application/vnd.agl.url***
-- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
-- ***application/vnd.agl.qml.hybrid***
-- ***application/vnd.agl.html.hybrid***
-
-
-The configuration file afm-unit.conf
-====================================
-
-The integration of the framework with systemd
-mainly consists of creating the systemd unit
-files corresponding to the need and requirements
-of the installed widgets.
-
-This configuration file named `afm-unit.conf` installed
-on the system wiht the path `/etc/afm/afm-unit.conf`
-describes how to generate all units from the *config.xml*
-configuration files of widgets. The description uses an extended
-version of the templating formalism of [mustache][]
-to describes all the units.
-
-Let present how it works using the following diagram that
-describes graphically the workflow of creating the unit
-files for systemd `afm-unit.conf` from the configuration
-file of the widget `config.xml`:
-
-![make-units][make-units]
-
-In a first step, and because [mustache][] is intended
-to work on JSON representations, the configuration file is
-translated to an internal JSON representation. This
-representation is shown along the examples of the documentation
-of the config files of widgets.
-
-In a second step, the mustache template `afm-unit.conf`
-is instanciated using the C library [mustach][] that follows
-the rules of [mustache][mustache] and with all its available
-extensions:
-
- - use of colon (:) for explicit substitution
- - test of values with = or =!
-
-In a third step, the result of instanciating `afm-unit.conf`
-for the widget is splited in units. To achieve that goal,
-the lines containing specific directives are searched.
-Any directive occupy one full line. The directives are:
-
- - %nl
-
- Produce an empty line at the end
-
- - %begin systemd-unit
- - %end systemd-unit
-
- Delimit the produced unit, its begin and its end
-
- - %systemd-unit user
- - %systemd-unit system
-
- Tells the kind of unit (user/system)
-
- - %systemd-unit service NAME
- - %systemd-unit socket NAME
-
- Gives the name and type (service or socket) of the unit.
- The extension is automatically computed from the type
- and must not be set in the name.
-
- - %systemd-unit wanted-by NAME
-
- Tells to install a link to the unit in the wants of NAME
-
-Then the computed units are then written to the filesystem
-and inserted in systemd.
-
-The generated unit files will contain variables for internal
-use of the framework. These variables are starting with `X-AFM-`.
-The variables starting with `X-AFM-` but not with `X-AFM--` are
-the public variables. These variables will be returned by the
-framework as the details of an application (see **afm-util detail ...**).
-
-Variables starting with `X-AFM--` are private to the framework.
-By example, the variable `X-AFM--http-port` is used to
-record the allocated port for applications.
-
-
-[mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache"
-[mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates"
-[make-units]: pictures/make-units.svg
-[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"
-[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"
-[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"
-[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
-[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest"
-[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 versionning"
-
-
-
Code Review / src / app-framework-main.git / blobdiff