arabic digits, and the three characters '.' (dot), '-' (dash) and
'\_' (underscore).
-Version values are dot separated fields MAJOR.MINOR.REVISION.
+Version values are dot separated fields MAJOR.MINOR.REVISION.
Such version would preferably follow guidelines of
[semantic versioning][semantic-version].
- 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.
+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.
+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]
+units of widgets.
+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 widget.
-Each required api must be explicit
ed using a `<param>` entry.
+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="#target" value="main" />
<param name="gps" value="auto" />
<param name="afm-main" value="link" />
</feature>
OPTIONAL
Declares the name of the unit requiring the listed apis.
-Only one instance of the param "#target" is allowed.
+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.
The name is the name of the required API.
-The value describes how to connect to the required api.
+The value describes how to connect to the required api.
It is either:
-- local:
+- local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY
+ Use the feature **urn:AGL:widget:required-binding** instead.
The binding is a local shared object.
In that case, the name is the relative path of the
shared object to be loaded.
-- auto:
+- auto:
The framework set automatically the kind of
the connection to the API
-- ws:
+- ws:
The framework connect using internal websockets
-- dbus:
+- dbus: [OBSOLETE, shouldn't be used currently]
The framework connect using internal dbus
-- link:
- The framework connect in memory by dynamically linking
+- 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.
+- 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 widget.
+
+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 widgets.
+
+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
ed using a `<param>` entry.
+Each required permission must be explicit using a `<param>` entry.
Example:
OPTIONAL
-Declares the name of the unit requiring the listed permissions.
-Only one instance of the param "#target" is allowed.
+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.
### provided-unit: feature name="urn:AGL:widget:provided-unit"
This feature is made for declaring new units
-for the widget.
+for the widget.
Using this feature, a software publisher
can provide more than one application in the same widget.
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.
+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.
+Only one instance of the param "#target" is allowed.
The value can't be "main".
#### provided-unit: param name="content.type"
OPTIONAL
-Declares the name of the unit exporting the listed apis.
-Only one instance of the param "#target" is allowed.
+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.
The value is one of the following values:
-- ws:
+- ws:
export the api using UNIX websocket
-- dbus:
+- dbus: [OBSOLETE, shouldn't be used currently]
export the API using dbus
-- auto:
+- 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 widget.
+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.
+
## Known content types
The configuration file ***/etc/afm/afm-unit.conf*** defines
Known types for the type of content are:
-- ***text/html***:
- HTML application,
+- ***text/html***:
+ HTML application,
content.src designates the home page of the application
-- ***application/vnd.agl.native***
- AGL compatible native,
+- ***application/vnd.agl.native***
+ AGL compatible native,
content.src designates the relative path of the binary.
-- ***application/vnd.agl.service***:
+- ***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.
+- ***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
### Older content type currently not supported at the moment
This types were defined previously when the framework was not
-leveraging systemd.
+leveraging systemd.
The transition to systemd let these types out at the moment.
- ***application/vnd.agl.url***
This configuration file named `afm-unit.conf` installed
on the system with 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
+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
In a first step, and because [mustache][] is intended
to work on JSON representations, the configuration file is
-translated to an internal JSON representation.
+translated to an internal JSON representation.
This representation is shown along the examples of the documentation
of the config files of widgets.
- test of values with = or =!
In a third step, the result of instantiating `afm-unit.conf`
-for the widget is split in units.
-To achieve that goal, the lines containing specific directives are searched.
-Any directive occupy one full line.
+for the widget is split in units.
+To achieve that goal, the lines containing specific directives are searched.
+Any directive occupy one full line.
The directives are:
- %nl
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.
+ 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
and inserted in systemd.
The generated unit files will contain variables for internal
-use of the framework.
-These variables are starting with `X-AFM-`.
+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.
+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.
+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.
Code Review / src / app-framework-main.git / blobdiff