Configuration of redpesk packages

Applications created for redpesk OS can include a subdirectory named .rpconfig.

That directory holds files used by redpesk OS framework.

Overview

When the directory .rpconfig is present in installed files its content is scanned for finding files of names:

  • manifest.yml: description of the application
  • signature-author.p7: signature of the author
  • signature-XXX.p7: signature of distributors

If these files are found, it is used by redpesk OS application framework to setup the installed RPM.

The manifest file

The file .rpconfig/manifest.yml is a YAML file describing for the framework important data of the installed RPM.

Here is an example of manifest file:

rp-manifest: 1

id: SmartHome
version: 1
author: Qt team
license: GPL

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.

targets:
  - target: main
    content:
	src: /usr/share/smarthome/smarthome.qml
	type: text/vnd.qt.qml
    icon:
	src: /usr/share/smarthome/smarthome-icon64x64.jpg
	type: image/jpeg
	size: { x: 64, y: 64 }

The manifest is made of two parts:

  • the global part: defines features globally
  • the targets part: defines the targets one by one

The global part MUST have the following fields:

  • rp-manifest
  • id
  • version

The global part MAY have the following fields:

  • description
  • author
  • license
  • file-properties
  • required-permission
  • provided-binding

The target part MUST have the following fields:

  • target
  • content

In all cases, unknown attributes are silently ignored.

Global part of the manifest file

rp-manifest

The attribute rp-manifest is mandatory. It is a number and it must be set to the value 1.

id

The attribute id is mandatory.

Values for id are any non empty string containing only latin letters, Arabic digits, and the three characters ‘.’ (dot), ‘-‘ (dash) and ‘_’ (underscore).

version

The attribute version is mandatory.

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.

name

The attribute name is optional. If not set, the id is taken as a replacement.

file-properties

Use this feature for setting properties to files or directories of the package.

Example:

file-properties:
  - name: /usr/bin/flite
    value: executable
  - name: /usr/bin/jtalk
    value: executable

The name is the relative path of the file whose property must be set, even when an absolute path is given. This means the example above applies to the files /usr/redpesk/<id>/usr/bin/xxx.

The value must be one of:

  • executable: the file is executable
  • public: the file is public read only
  • library: the file is a private library
  • config: the file is a private configuration
  • data: the file is a private data (default)
  • www: the file is world wide read only
  • plug
  • public-executable
  • public-library

provided-binding

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

Example:

provided-binding:
   - name: extra
     value: export/binding-gps.so

The value must contain the path of the exported binding.

The exported binding must be set public using the file-properties setting (see above) otherwise it can not be used by other applications.

required-permission

Dictionary of the permissions required globally, meaning by each target.

Example:

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

The key is the value of the required permission.

The name is optional.

The value is either:

  • required: the permission is required
  • optional: the permission is optional

plugs

Use this feature for exporting files to applications able to receive plugins.

Example:

plugs:
  - name: canbus/plug
    value: canbus-binding

The name is the name of the exported directory.

The value is the identifier of the application to which the files are exported.

Targets part of the manifest file

Targets are startable units of the package.

More than one target can be given.

If a target is given, at least one must be of id main.

target

Identifier of the target. Mandatory.

At least one target must be named main.

content

The attribute content is mandatory and must designate a file (subject to localization) with its mandatory attributes src and type.

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

icon

The attribute icon is optional. It must designate an image file with its attribute src.

The type and the size can optionally be given.

name

The attribute name is optional.

It is used for naming the target. If not defined, the value of attribute target is used.

description

The attribute description is optional.

This attribute is used for describing the target.

required-config

List of configuration files for the binder.

Example:

required-config:
   - etc/config-main.json
   - etc/config-aux1.json
   - etc/config-aux2.json

required-api

List of the api required by the target.

Example:

required-api:
   - name: gps
     value: auto
   - name: afm-main
     value: link

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

List of the bindings required by the package.

Example:

required-binding:
   - name: libexec/binding-gps.so
     value: local
   - name: extra
     value: extern

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-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:

provided-api:
  - name: geoloc
    value: auto
  - name: moonloc
    value: auto

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: [EXPERIMENTAL] 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.

required-permission

This attribute is the same than the global one but allows to require specific permissions for specific target.

required-systemd

These settings establish a requirement of the application to systemd’s units (socket, target, service, mount, …).

It enforce the application to start after the listed dependencies.

The setting lists the required units. For each 2 fields are required:

  • unit: the name of the required unit with its extension
  • mode: the mode of the dependency

Valid values for modes are:

  • weak: translated to systemd’s directive Wants
  • strong: translated to systemd’s directive Requires
  • strict: translated to systemd’s directive BindsTo

Example:

required-systemd:
   - unit: base.target
     mode: strict
   - unit: foo.socket
     mode: strong
   - unit: bar.service
     mode: weak