docs/2.1-widgets.md

   1 # Tools for managing widgets
   2
   3 This project includes tools for managing widgets.
   4 These tools are:
   5
   6 - ***wgtpkg-info***: command line tool to display
   7   informations about a widget file.
   8
   9 - ***wgtpkg-install***: command line tool to
  10   install a widget file.
  11
  12 - ***wgtpkg-pack***: command line tool to create
  13   a widget file from a widget directory.
  14
  15 - ***wgtpkg-sign***: command line tool to add a signature
  16   to a widget directory.
  17
  18 For all these commands, a tiny help is available with
  19 options **-h** or **--help**.
  20
  21 There is no tool for unpacking a widget.
  22 For doing such operation, you can use the command **unzip**.
  23
  24 To list the files of a widget:
  25
  26 ```bash
  27 unzip -l WIDGET
  28 ```
  29
  30 To extract a widget in some directory:
  31
  32 ```bash
  33 unzip WIDGET -d DIRECTORY
  34 ```
  35
  36 *Note: that DIRECTORY will be created if needed*.
  37
  38 ## Getting data about a widget file
  39
  40 The command **wgtpkg-info** opens a widget file, reads its **config.xml**
  41 file and displays its content in a human readable way.
  42
  43 ## Signing and packing widget
  44
  45 ### Signing
  46
  47 To sign a widget, you need a private key and its certificate.
  48
  49 The tool **wgtpkg-sign** creates or replace a signature file in
  50 the directory of the widget BEFORE its packaging.
  51
  52 There are two types of signature files: author and distributor.
  53
  54 Example 1: add an author signature
  55
  56 ```bash
  57 wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY
  58 ```
  59
  60 Example 2: add a distributor signature
  61
  62 ```bash
  63 wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY
  64 ```
  65
  66 ### Packing
  67
  68 This operation can be done using the command **zip** but
  69 we provide the tool **wgtpkg-pack** that may add checking.
  70
  71 Example:
  72
  73 ```bash
  74 wgtpkg-pack DIRECTORY -o file.wgt
  75 ```
  76
  77 ## Writing a widget
  78
  79 ### App directory organization
  80
  81 There are few directories that are by default used in the binder. At the root
  82 directory of the widget folder, here are the directories that could be used:
  83
  84 - *lib* : default directory where lies external libraries needed for
  85  the binding. Binding could be stored here too or in another directory of your
  86  choice.
  87 - *htdocs* : root HTTP directory if binding has web UI.
  88
  89 ### The steps for writing a widget
  90
  91 1. make your application
  92 1. create its configuration file **config.xml**
  93 1. sign it
  94 1. pack it
  95
  96 Fairly easy, no?
  97
  98 ## Organization of directory of applications
  99
 100 ### directory where are stored applications
 101
 102 Applications can be installed in different places:
 103
 104 - the system itself, extension device.
 105
 106 On a phone application are typically installed on the sd card.
 107
 108 This translates to:
 109
 110 - /var/local/lib/afm/applications
 111
 112 From here this path is referenced as: "APPDIR".
 113
 114 The main path for applications is: APPDIR/PKGID/VER.
 115
 116 Where:
 117
 118 - APPDIR is as defined above
 119 - PKGID is a directory whose name is the package identifier
 120 - VER is the version of the package MAJOR.MINOR
 121
 122 This organization has the advantage to allow several versions
 123 to leave together.
 124 This is needed for some good reasons (rolling back) and also for less good reasons (user habits).
 125
 126 ### Identity of installed files
 127
 128 All files are installed as user "afm" and group "afm".
 129 All files have rw(x) for user and r-(x) for group and others.
 130
 131 This allows every user to read every file.
 132
 133 ### labeling the directories of applications
 134
 135 The data of a user are in its directory and are labelled by the security-manager using the application labels.
 136
 137 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 138 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 139 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 140 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 141 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 142 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 143 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 144 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 145 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 146 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 147 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 148 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 149 [cmake]:            https://cmake.org                                               "CMake"
 150 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 151 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 152 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 153 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"