doc/widgets.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta charset="utf-8">
   5   <meta name="generator" content="pandoc">
   6   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
   7   <meta name="author" content="José Bollo">
   8   <meta name="author" content="Fulup Ar Foll">
   9   <title>The widgets</title>
  10   <style type="text/css">code{white-space: pre;}</style>
  11   <!--[if lt IE 9]>
  12     <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
  13   <![endif]-->
  14   <style type="text/css">
  15 table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
  16   margin: 0; padding: 0; vertical-align: baseline; border: none; }
  17 table.sourceCode { width: 100%; line-height: 100%; }
  18 td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
  19 td.sourceCode { padding-left: 5px; }
  20 code > span.kw { color: #007020; font-weight: bold; }
  21 code > span.dt { color: #902000; }
  22 code > span.dv { color: #40a070; }
  23 code > span.bn { color: #40a070; }
  24 code > span.fl { color: #40a070; }
  25 code > span.ch { color: #4070a0; }
  26 code > span.st { color: #4070a0; }
  27 code > span.co { color: #60a0b0; font-style: italic; }
  28 code > span.ot { color: #007020; }
  29 code > span.al { color: #ff0000; font-weight: bold; }
  30 code > span.fu { color: #06287e; }
  31 code > span.er { color: #ff0000; font-weight: bold; }
  32   </style>
  33   <link rel="stylesheet" href="doc.css">
  34 </head>
  35 <body>
  36 <header>
  37 <h1 class="title">The widgets</h1>
  38 <h2 class="author">José Bollo</h2>
  39 <h2 class="author">Fulup Ar Foll</h2>
  40 <h3 class="date">24 juin 2016</h3>
  41 </header>
  42 <nav id="TOC">
  43 <ul>
  44 <li><a href="#the-widgets">The widgets</a><ul>
  45 <li><a href="#the-widgets-1">The widgets</a><ul>
  46 <li><a href="#the-configuration-file-config.xml">The configuration file config.xml</a></li>
  47 <li><a href="#tools-for-managing-widgets">Tools for managing widgets</a></li>
  48 <li><a href="#signing-a-widget">Signing a widget</a></li>
  49 <li><a href="#packing-a-widget">Packing a widget</a></li>
  50 <li><a href="#getting-data-about-a-widget-file">Getting data about a widget file</a></li>
  51 </ul></li>
  52 <li><a href="#writing-a-widget">Writing a widget</a><ul>
  53 <li><a href="#what-kind-of-application">What kind of application?</a></li>
  54 <li><a href="#the-steps-for-writing-a-widget">The steps for writing a widget</a></li>
  55 </ul></li>
  56 <li><a href="#organization-of-directory-of-applications">Organization of directory of applications</a><ul>
  57 <li><a href="#directory-where-are-stored-applications">directory where are stored applications</a></li>
  58 <li><a href="#identity-of-installed-files">Identity of installed files</a></li>
  59 <li><a href="#labeling-the-directories-of-applications">labeling the directories of applications</a></li>
  60 </ul></li>
  61 </ul></li>
  62 </ul>
  63 </nav>
  64 <h1 id="the-widgets">The widgets</h1>
  65 <h2 id="the-widgets-1">The widgets</h2>
  66 <p>The widgets are described by the technical recommendations <a href="http://www.w3.org/TR/widgets" title="Packaged Web Apps">widgets</a> and <a href="http://www.w3.org/TR/widgets-digsig" title="XML Digital Signatures for Widgets">widgets-digsig</a>.</p>
  67 <p>In summary, <strong>widgets are ZIP files that can be signed and whose content is described by the file <config.xml></strong>.</p>
  68 <h3 id="the-configuration-file-config.xml">The configuration file config.xml</h3>
  69 <p>This is one of the important file of the widget. It fully describes the widget.</p>
  70 <p>Here is the example of the config file for the QML application SmartHome.</p>
  71 <pre class="sourceCode xml"><code class="sourceCode xml"><span class="kw">&lt;?xml</span> version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;<span class="kw">?&gt;</span>
  72 <span class="kw">&lt;widget</span><span class="ot"> xmlns=</span><span class="st">&quot;http://www.w3.org/ns/widgets&quot;</span><span class="ot"> id=</span><span class="st">&quot;smarthome&quot;</span><span class="ot"> version=</span><span class="st">&quot;0.1&quot;</span><span class="kw">&gt;</span>
  73   <span class="kw">&lt;name&gt;</span>SmartHome<span class="kw">&lt;/name&gt;</span>
  74   <span class="kw">&lt;icon</span><span class="ot"> src=</span><span class="st">&quot;smarthome.png&quot;</span><span class="kw">/&gt;</span>
  75   <span class="kw">&lt;content</span><span class="ot"> src=</span><span class="st">&quot;qml/smarthome/smarthome.qml&quot;</span><span class="ot"> type=</span><span class="st">&quot;text/vnd.qt.qml&quot;</span><span class="kw">/&gt;</span>
  76   <span class="kw">&lt;description&gt;</span>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
  77 automated house. The user interface is completely done with QML.<span class="kw">&lt;/description&gt;</span>
  78   <span class="kw">&lt;author&gt;</span>Qt team<span class="kw">&lt;/author&gt;</span>
  79   <span class="kw">&lt;license&gt;</span>GPL<span class="kw">&lt;/license&gt;</span>
  80 <span class="kw">&lt;/widget&gt;</span></code></pre>
  81 <p>The most important items are:</p>
  82 <ul>
  83 <li><p><strong>&lt;widget id=&quot;......&quot;&gt;</strong>: gives the id of the widget. It must be unique.</p></li>
  84 <li><p><strong>&lt;widget version=&quot;......&quot;&gt;</strong>: gives the version of the widget</p></li>
  85 <li><p><strong>&lt;icon src=&quot;...&quot;&gt;</strong>: gives a path to the icon of the application (can be repeated with different sizes)</p></li>
  86 <li><p><strong>&lt;content src=&quot;...&quot; type=&quot;...&quot;&gt;</strong>: this indicates the entry point and its type. The types handled are set through the file /etc/afm/afm-launch.conf</p></li>
  87 </ul>
  88 <p>Further development will add handling of <feature> for requiring and providing permissions and services.</p>
  89 <h3 id="tools-for-managing-widgets">Tools for managing widgets</h3>
  90 <p>This project includes tools for managing widgets. These tools are:</p>
  91 <ul>
  92 <li><p><strong><em>wgtpkg-info</em></strong>: command line tool to display informations about a widget file.</p></li>
  93 <li><p><strong><em>wgtpkg-installer</em></strong>: command line tool to install a widget file.</p></li>
  94 <li><p><strong><em>wgtpkg-pack</em></strong>: command line tool to create a widget file from a widget directory.</p></li>
  95 <li><p><strong><em>wgtpkg-sign</em></strong>: command line tool to add a signature to a widget directory.</p></li>
  96 </ul>
  97 <p>For all these commands, a tiny help is available with options <strong>-h</strong> or <strong>--help</strong>.</p>
  98 <p>There is no tool for unpacking a widget. For doing such operation, you can use the command <strong>unzip</strong>.</p>
  99 <p>To list the files of a widget:</p>
 100 <pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">unzip</span> -l WIDGET</code></pre>
 101 <p>To extract a widget in some directory:</p>
 102 <pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">unzip</span> WIDGET -d DIRECTORY</code></pre>
 103 <p><em>Note that DIRECTORY will be created if needed</em>.</p>
 104 <h3 id="signing-a-widget">Signing a widget</h3>
 105 <p>To sign a widget, you need a private key and its certificate.</p>
 106 <p>The tool <strong>wgtpkg-sign</strong> creates or replace a signature file in the directory of the widget BEFORE its packaging.</p>
 107 <p>There are two types of signature files: author and distributor.</p>
 108 <p>Example 1: add an author signature</p>
 109 <pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">wgtpkg-sign</span> -a -k me.key.pem -c me.cert.pem DIRECTORY</code></pre>
 110 <p>Example 2: add a distributor signature</p>
 111 <pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">wgtpkg-sign</span> -k authority.key.pem -c authority.cert.pem DIRECTORY</code></pre>
 112 <h3 id="packing-a-widget">Packing a widget</h3>
 113 <p>This operation can be done using the command <strong>zip</strong> but we provide the tool <strong>wgtpkg-pack</strong> that may add checking.</p>
 114 <p>Example:</p>
 115 <pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">wgtpkg-pack</span> DIRECTORY -o file.wgt</code></pre>
 116 <h3 id="getting-data-about-a-widget-file">Getting data about a widget file</h3>
 117 <p>The command <strong>wgtpkg-info</strong> opens a widget file, reads its <strong>config.xml</strong> file and displays its content in a human readable way.</p>
 118 <h2 id="writing-a-widget">Writing a widget</h2>
 119 <h3 id="what-kind-of-application">What kind of application?</h3>
 120 <p>The file <strong>/etc/afm/afm-launch.conf</strong> 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.)</p>
 121 <p>Currently the applications that can be run are:</p>
 122 <ul>
 123 <li><p>binary applications: their type is <strong><em>application/x-executable</em></strong></p></li>
 124 <li><p>HTML5 applications: their type is <strong><em>text/html</em></strong></p></li>
 125 <li><p>QML applications: their type is <strong><em>text/vnd.qt.qml</em></strong></p></li>
 126 </ul>
 127 <h3 id="the-steps-for-writing-a-widget">The steps for writing a widget</h3>
 128 <ol type="1">
 129 <li><p>make your application</p></li>
 130 <li><p>create its configuration file <strong>config.xml</strong></p></li>
 131 <li><p>sign it</p></li>
 132 <li><p>pack it</p></li>
 133 </ol>
 134 <p>Fairly easy, no?</p>
 135 <h2 id="organization-of-directory-of-applications">Organization of directory of applications</h2>
 136 <h3 id="directory-where-are-stored-applications">directory where are stored applications</h3>
 137 <p>Applications can be installed in different places: the system itself, extension device. On a phone application are typically installed on the sd card.</p>
 138 <p>This translates to:</p>
 139 <ul>
 140 <li>/usr/applications: system wide applications</li>
 141 <li>/opt/applications: removable applications</li>
 142 </ul>
 143 <p>From here those paths are referenced as: &quot;APPDIR&quot;.</p>
 144 <p>The main path for applications is: APPDIR/PKGID/VER.</p>
 145 <p>Where:</p>
 146 <ul>
 147 <li>APPDIR is as defined above</li>
 148 <li>PKGID is a directory whose name is the package identifier</li>
 149 <li>VER is the version of the package MAJOR.MINOR</li>
 150 </ul>
 151 <p>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).</p>
 152 <h3 id="identity-of-installed-files">Identity of installed files</h3>
 153 <p>All files are installed as user &quot;afm&quot; and group &quot;afm&quot;. All files have rw(x) for user and r-(x) for group and others.</p>
 154 <p>This allows every user to read every file.</p>
 155 <h3 id="labeling-the-directories-of-applications">labeling the directories of applications</h3>
 156 <p>The data of a user are in its directory and are labelled by the security-manager using the labels of the application.</p>
 157 </body>
 158 </html>