doc/widgets.md

   1 The widgets
   2 ===========
   3
   4     version: 1
   5     Date:    30 mai 2016
   6     Author:  José Bollo
   7
   8
   9 The widgets
  10 -----------
  11
  12 The widgets are described by the technical recommendations
  13 [widgets] and [widgets-digsig].
  14
  15 In summary, **widgets are ZIP files that can be signed and
  16 whose content is described by the file <config.xml>**.
  17
  18 ### The configuration file config.xml
  19
  20 This is one of the important file of the widget.
  21 It fully describes the widget.
  22
  23 Here is the example of the config file for the QML application SmartHome.
  24
  25 ```xml
  26 <?xml version="1.0" encoding="UTF-8"?>
  27 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
  28   <name>SmartHome</name>
  29   <icon src="smarthome.png"/>
  30   <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
  31   <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
  32 automated house. The user interface is completely done with QML.</description>
  33   <author>Qt team</author>
  34   <license>GPL</license>
  35 </widget>
  36 ```
  37
  38 The most important items are:
  39
  40 - **\<widget id="......"\>**: gives the id of the widget. It must be unique.
  41
  42 - **\<widget version="......"\>**: gives the version of the widget
  43
  44 - **\<icon src="..."\>**: gives a path to the icon of the application
  45   (can be repeated with different sizes)
  46
  47 - **\<content src="..." type="..."\>**: this indicates the entry point and its type.
  48   The types handled are set through the file /etc/afm/afm-launch.conf
  49
  50 Further development will add handling of <feature> for requiring and providing
  51 permissions and services.
  52
  53 ### Tools for managing widgets
  54
  55 This project includes tools for managing widgets.
  56 These tools are:
  57
  58 - ***wgtpkg-info***: command line tool to display
  59   informations about a widget file.
  60
  61 - ***wgtpkg-installer***: command line tool to
  62   install a widget file.
  63
  64 - ***wgtpkg-pack***: command line tool to create
  65   a widget file from a widget directory.
  66
  67 - ***wgtpkg-sign***: command line tool to add a signature
  68   to a widget directory.
  69
  70 For all these commands, a tiny help is available with
  71 options **-h** or **--help**.
  72
  73 There is no tool for unpacking a widget. For doing such operation,
  74 you can use the command **unzip**.
  75
  76 To list the files of a widget:
  77
  78 ```bash
  79 $ unzip -l WIDGET
  80 ```
  81
  82 To extract a widget in some directory:
  83
  84 ```bash
  85 $ unzip WIDGET -d DIRECTORY
  86 ```
  87
  88 *Note that DIRECTORY will be created if needed*.
  89
  90 ### Signing a widget
  91
  92 To sign a widget, you need a private key and its certificate.
  93
  94 The tool **wgtpkg-sign** creates or replace a signature file in
  95 the directory of the widget BEFORE its packaging.
  96
  97 There are two types of signature files: author and distributor.
  98
  99 Example 1: add an author signature
 100
 101 ```bash
 102 $ wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY
 103 ```
 104
 105 Example 2: add a distributor signature
 106
 107 ```bash
 108 $ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY
 109 ```
 110
 111 ### Packing a widget
 112
 113 This operation can be done using the command **zip** but
 114 we provide the tool **wgtpkg-pack** that may add checking.
 115
 116 Example:
 117 ```bash
 118 $ wgtpkg-pack DIRECTORY -o file.wgt
 119 ```
 120
 121 ### Getting data about a widget file
 122
 123 The command **wgtpkg-info** opens a widget file, reads its **config.xml**
 124 file and displays its content in a human readable way.
 125
 126 Writing a widget
 127 ----------------
 128
 129 ### What kind of application?
 130
 131 The file **/etc/afm/afm-launch.conf** explain how to launch applications.
 132 (It is the current state that use afm-user-daemon. In a future, it may be
 133 replace by systemd features.)
 134
 135 Currently the applications that can be run are:
 136
 137 - binary applications: their type is ***application/x-executable***
 138
 139 - HTML5 applications: their type is ***text/html***
 140
 141 - QML applications: their type is ***text/vnd.qt.qml***
 142
 143 ### The steps for writing a widget
 144
 145 1. make your application
 146
 147 2. create its configuration file **config.xml**
 148
 149 3. sign it
 150
 151 4. pack it
 152
 153 Fairly easy, no?
 154
 155 Organization of directory of applications
 156 -----------------------------------------
 157
 158 ### directory where are stored applications
 159
 160 Applications can be installed in different places: the system itself, extension device.
 161 On a phone application are typically installed on the sd card.
 162
 163 This translates to:
 164
 165  - /usr/applications: system wide applications
 166  - /opt/applications: removable applications
 167
 168 From here those paths are referenced as: "APPDIR".
 169
 170 The main path for applications is: APPDIR/PKGID/VER.
 171
 172 Where:
 173
 174  - APPDIR is as defined above
 175  - PKGID is a directory whose name is the package identifier
 176  - VER is the version of the package MAJOR.MINOR
 177
 178 This organization has the advantage to allow several versions to leave together.
 179 This is needed for some good reasons (rolling back) and also for less good reasons (user habits).
 180
 181 ### Identity of installed files
 182
 183 All files are installed as user "afm" and group "afm".
 184 All files have rw(x) for user and r-(x) for group and others.
 185
 186 This allows every user to read every file.
 187
 188 ### labeling the directories of applications
 189
 190 The data of a user are in its directory and are labelled by the security-manager
 191 using the labels of the application.
 192
 193 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 194 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 195 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 196 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 197 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 198 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 199 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 200 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 201 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 202 [cmake]:            https://cmake.org                                               "CMake"
 203 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 204 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 205 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 206 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
 207
 208
 209
 210