X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=doc%2Fwidgets.md;h=5637f2c90756cbf1aded44da2b523ece1f464311;hb=0257e4d58a25d328a971423d5fe5289d9985d046;hp=1b2df87aa759672478bfe8d596cd513fa2fa4b8c;hpb=f45bd5fbf8d1fe440b1855d93b387755d63ac8f0;p=src%2Fapp-framework-main.git diff --git a/doc/widgets.md b/doc/widgets.md index 1b2df87..5637f2c 100644 --- a/doc/widgets.md +++ b/doc/widgets.md @@ -1,72 +1,189 @@ - The widgets =========== - version: 1 - Date: 29 mai 2016 - Author: José Bollo - -TABLE-OF-CONTENT-HERE - The widgets ----------- The widgets are described by the technical recommendations [widgets] and [widgets-digsig]. -### signature of the +In summary, **widgets are ZIP files that can be signed and +whose content is described by the file **. -The application framework +### The configuration file config.xml -This is the original part of our work here +This is one of the important file of the widget. +It fully describes the widget. -### directory where are stored applications +Here is the example of the config file for the QML application SmartHome. -Applications can be installed in few places: on the system itself or on an extension device. -For my phone, for example, it is the sd card. +```xml + + + SmartHome + + + 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. + Qt team + GPL + +``` -This translates to: +The most important items are: - - /usr/applications: for system wide applications - - /opt/applications: for removable applications +- **\**: gives the id of the widget. It must be unique. -In the remaining of the document, these places are writen "APPDIR". +- **\**: gives the version of the widget +- **\**: gives a path to the icon of the application + (can be repeated with different sizes) -Organisation of directory of applications -========================================= +- **\**: this indicates the entry point and its type. + The types handled are set through the file /etc/afm/afm-launch.conf -The main path for applivcations are: APPDIR/PKGID/VER. +Further development will add handling of for requiring and providing +permissions and services. -Where: +### Tools for managing widgets - - APPDIR is as defined above - - PKGID is a directory whose name is the package identifier - - VER is the version of the package MAJOR.MINOR +This project includes tools for managing widgets. +These tools are: -This organisation has the advantage to allow several versions to leave together. -This is needed for some good reasons (rolling back) and also for less good reasons (user habits). +- ***wgtpkg-info***: command line tool to display + informations about a widget file. -Identity of installed files ---------------------------- +- ***wgtpkg-installer***: command line tool to + install a widget file. -All the files are installed as the user "userapp" and group "userapp". -All files have rw(x) for user and r-(x) for group and others. +- ***wgtpkg-pack***: command line tool to create + a widget file from a widget directory. + +- ***wgtpkg-sign***: command line tool to add a signature + to a widget directory. + +For all these commands, a tiny help is available with +options **-h** or **--help**. + +There is no tool for unpacking a widget. For doing such operation, +you can use the command **unzip**. + +To list the files of a widget: + +```bash +$ unzip -l WIDGET +``` + +To extract a widget in some directory: + +```bash +$ unzip WIDGET -d DIRECTORY +``` + +*Note that DIRECTORY will be created if needed*. + +### Signing a widget + +To sign a widget, you need a private key and its certificate. + +The tool **wgtpkg-sign** creates or replace a signature file in +the directory of the widget BEFORE its packaging. + +There are two types of signature files: author and distributor. + +Example 1: add an author signature + +```bash +$ wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY +``` + +Example 2: add a distributor signature + +```bash +$ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY +``` + +### Packing a widget + +This operation can be done using the command **zip** but +we provide the tool **wgtpkg-pack** that may add checking. + +Example: +```bash +$ wgtpkg-pack DIRECTORY -o file.wgt +``` -This allows any user to read the files. +### Getting data about a widget file +The command **wgtpkg-info** opens a widget file, reads its **config.xml** +file and displays its content in a human readable way. -Labelling the directories of applications +Writing a widget +---------------- + +### What kind of application? + +The file **/etc/afm/afm-launch.conf** explain how to launch applications. +(It is the current state that use afm-user-daemon. In a future, it may be +replace by systemd features.) + +Currently the applications that can be run are: + +- binary applications: their type is ***application/x-executable*** + +- HTML5 applications: their type is ***text/html*** + +- QML applications: their type is ***text/vnd.qt.qml*** + +### The steps for writing a widget + +1. make your application + +2. create its configuration file **config.xml** + +3. sign it + +4. pack it + +Fairly easy, no? + +Organization of directory of applications ----------------------------------------- +### directory where are stored applications -Organisation of data -==================== +Applications can be installed in different places: the system itself, extension device. +On a phone application are typically installed on the sd card. -The data of a user are in its directory and are labelled using the labels of the application +This translates to: + + - /usr/applications: system wide applications + - /opt/applications: removable applications + +From here those paths are referenced as: "APPDIR". + +The main path for applications is: APPDIR/PKGID/VER. + +Where: + + - APPDIR is as defined above + - PKGID is a directory whose name is the package identifier + - VER is the version of the package MAJOR.MINOR + +This organization has the advantage to allow several versions to leave together. +This is needed for some good reasons (rolling back) and also for less good reasons (user habits). + +### Identity of installed files + +All files are installed as user "afm" and group "afm". +All files have rw(x) for user and r-(x) for group and others. +This allows every user to read every file. +### labeling the directories of applications +The data of a user are in its directory and are labelled by the security-manager +using the labels of the application. [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"