diff options
| author |   José Bollo <jose.bollo@iot.bzh> | 2016-06-24 15:44:24 +0200 |
|---|---|---|
| committer | José Bollo <jose.bollo@iot.bzh> | 2016-06-24 15:52:23 +0200 |
| commit | bad30c92a1cbe0e411f52c277cef37b6570b623f (patch) | |
| tree | 15d6c00b37df9cb04e88acaf702e17dec6c36a7c /doc/widgets.html | |
| parent | 8b1af713cef4f66d658e304f0ace0820b47d2bc5 (diff) | |
improves the documentation
Change-Id: Ieea284220b2b088bf460093f745e8f5fb3633eca
Signed-off-by: José Bollo <jose.bollo@iot.bzh>
Diffstat (limited to 'doc/widgets.html')
| -rw-r--r-- | doc/widgets.html | 217 |
1 files changed, 140 insertions, 77 deletions
diff --git a/doc/widgets.html b/doc/widgets.html index 23bf891..1ea0178 100644 --- a/doc/widgets.html +++ b/doc/widgets.html @@ -1,98 +1,161 @@ +<!DOCTYPE html> <html> <head> - <link rel="stylesheet" type="text/css" href="doc.css"> - <meta charset="UTF-8"> + <meta charset="utf-8"> + <meta name="generator" content="pandoc"> + <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes"> + <meta name="author" content="José Bollo"> + <meta name="author" content="Fulup Ar Foll"> + <title>The widgets</title> + <style type="text/css">code{white-space: pre;}</style> + <!--[if lt IE 9]> + <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script> + <![endif]--> + <style type="text/css"> +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } +td.sourceCode { padding-left: 5px; } +code > span.kw { color: #007020; font-weight: bold; } +code > span.dt { color: #902000; } +code > span.dv { color: #40a070; } +code > span.bn { color: #40a070; } +code > span.fl { color: #40a070; } +code > span.ch { color: #4070a0; } +code > span.st { color: #4070a0; } +code > span.co { color: #60a0b0; font-style: italic; } +code > span.ot { color: #007020; } +code > span.al { color: #ff0000; font-weight: bold; } +code > span.fu { color: #06287e; } +code > span.er { color: #ff0000; font-weight: bold; } + </style> + <link rel="stylesheet" href="doc.css"> </head> <body> -<a name="The.widgets"></a> -<h1>The widgets</h1> - +<header> +<h1 class="title">The widgets</h1> +<h2 class="author">José Bollo</h2> +<h2 class="author">Fulup Ar Foll</h2> +<h3 class="date">24 juin 2016</h3> +</header> +<nav id="TOC"> +<ul> +<li><a href="#the-widgets">The widgets</a><ul> +<li><a href="#the-widgets-1">The widgets</a><ul> +<li><a href="#the-configuration-file-config.xml">The configuration file config.xml</a></li> +<li><a href="#tools-for-managing-widgets">Tools for managing widgets</a></li> +<li><a href="#signing-a-widget">Signing a widget</a></li> +<li><a href="#packing-a-widget">Packing a widget</a></li> +<li><a href="#getting-data-about-a-widget-file">Getting data about a widget file</a></li> +</ul></li> +<li><a href="#writing-a-widget">Writing a widget</a><ul> +<li><a href="#what-kind-of-application">What kind of application?</a></li> +<li><a href="#the-steps-for-writing-a-widget">The steps for writing a widget</a></li> +</ul></li> +<li><a href="#organization-of-directory-of-applications">Organization of directory of applications</a><ul> +<li><a href="#directory-where-are-stored-applications">directory where are stored applications</a></li> +<li><a href="#identity-of-installed-files">Identity of installed files</a></li> +<li><a href="#labeling-the-directories-of-applications">labeling the directories of applications</a></li> +</ul></li> +</ul></li> +</ul> +</nav> +<h1 id="the-widgets">The widgets</h1> <pre><code>version: 1 Date: 30 mai 2016 -Author: José Bollo -</code></pre> - -<p><ul> - <li><a href="#The.widgets">The widgets</a> - <ul> - <li><a href="#The.widgets">The widgets</a> - <ul> - <li><a href="#signature">signature</a></li> - <li><a href="#directory.where.are.stored.applications">directory where are stored applications</a> -</li> - </ul> - </li> - </ul> - </li> - <li><a href="#Organization.of.directory.of.applications">Organization of directory of applications</a> - <ul> - <li><a href="#Identity.of.installed.files">Identity of installed files</a></li> - <li><a href="#labeling.the.directories.of.applications">labeling the directories of applications</a></li> - </ul> - </li> - <li><a href="#organization.of.data">organization of data</a></li> -</ul></p> - -<a name="The.widgets"></a> -<h2>The widgets</h2> - -<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> - -<a name="signature"></a> -<h3>signature</h3> - -<p>The application framework</p> - -<p>This is the original part of our work here</p> - -<a name="directory.where.are.stored.applications"></a> -<h3>directory where are stored applications</h3> - -<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> - +Author: José Bollo</code></pre> +<h2 id="the-widgets-1">The widgets</h2> +<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> +<p>In summary, <strong>widgets are ZIP files that can be signed and whose content is described by the file <config.xml></strong>.</p> +<h3 id="the-configuration-file-config.xml">The configuration file config.xml</h3> +<p>This is one of the important file of the widget. It fully describes the widget.</p> +<p>Here is the example of the config file for the QML application SmartHome.</p> +<pre class="sourceCode xml"><code class="sourceCode xml"><span class="kw"><?xml</span> version="1.0" encoding="UTF-8"<span class="kw">?></span> +<span class="kw"><widget</span><span class="ot"> xmlns=</span><span class="st">"http://www.w3.org/ns/widgets"</span><span class="ot"> id=</span><span class="st">"smarthome"</span><span class="ot"> version=</span><span class="st">"0.1"</span><span class="kw">></span> + <span class="kw"><name></span>SmartHome<span class="kw"></name></span> + <span class="kw"><icon</span><span class="ot"> src=</span><span class="st">"smarthome.png"</span><span class="kw">/></span> + <span class="kw"><content</span><span class="ot"> src=</span><span class="st">"qml/smarthome/smarthome.qml"</span><span class="ot"> type=</span><span class="st">"text/vnd.qt.qml"</span><span class="kw">/></span> + <span class="kw"><description></span>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.<span class="kw"></description></span> + <span class="kw"><author></span>Qt team<span class="kw"></author></span> + <span class="kw"><license></span>GPL<span class="kw"></license></span> +<span class="kw"></widget></span></code></pre> +<p>The most important items are:</p> +<ul> +<li><p><strong><widget id="......"></strong>: gives the id of the widget. It must be unique.</p></li> +<li><p><strong><widget version="......"></strong>: gives the version of the widget</p></li> +<li><p><strong><icon src="..."></strong>: gives a path to the icon of the application (can be repeated with different sizes)</p></li> +<li><p><strong><content src="..." type="..."></strong>: this indicates the entry point and its type. The types handled are set through the file /etc/afm/afm-launch.conf</p></li> +</ul> +<p>Further development will add handling of <feature> for requiring and providing permissions and services.</p> +<h3 id="tools-for-managing-widgets">Tools for managing widgets</h3> +<p>This project includes tools for managing widgets. These tools are:</p> +<ul> +<li><p><strong><em>wgtpkg-info</em></strong>: command line tool to display informations about a widget file.</p></li> +<li><p><strong><em>wgtpkg-installer</em></strong>: command line tool to install a widget file.</p></li> +<li><p><strong><em>wgtpkg-pack</em></strong>: command line tool to create a widget file from a widget directory.</p></li> +<li><p><strong><em>wgtpkg-sign</em></strong>: command line tool to add a signature to a widget directory.</p></li> +</ul> +<p>For all these commands, a tiny help is available with options <strong>-h</strong> or <strong>--help</strong>.</p> +<p>There is no tool for unpacking a widget. For doing such operation, you can use the command <strong>unzip</strong>.</p> +<p>To list the files of a widget:</p> +<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">unzip</span> -l WIDGET</code></pre> +<p>To extract a widget in some directory:</p> +<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">unzip</span> WIDGET -d DIRECTORY</code></pre> +<p><em>Note that DIRECTORY will be created if needed</em>.</p> +<h3 id="signing-a-widget">Signing a widget</h3> +<p>To sign a widget, you need a private key and its certificate.</p> +<p>The tool <strong>wgtpkg-sign</strong> creates or replace a signature file in the directory of the widget BEFORE its packaging.</p> +<p>There are two types of signature files: author and distributor.</p> +<p>Example 1: add an author signature</p> +<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> +<p>Example 2: add a distributor signature</p> +<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> +<h3 id="packing-a-widget">Packing a widget</h3> +<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> +<p>Example:</p> +<pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">wgtpkg-pack</span> DIRECTORY -o file.wgt</code></pre> +<h3 id="getting-data-about-a-widget-file">Getting data about a widget file</h3> +<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> +<h2 id="writing-a-widget">Writing a widget</h2> +<h3 id="what-kind-of-application">What kind of application?</h3> +<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> +<p>Currently the applications that can be run are:</p> +<ul> +<li><p>binary applications: their type is <strong><em>application/x-executable</em></strong></p></li> +<li><p>HTML5 applications: their type is <strong><em>text/html</em></strong></p></li> +<li><p>QML applications: their type is <strong><em>text/vnd.qt.qml</em></strong></p></li> +</ul> +<h3 id="the-steps-for-writing-a-widget">The steps for writing a widget</h3> +<ol type="1"> +<li><p>make your application</p></li> +<li><p>create its configuration file <strong>config.xml</strong></p></li> +<li><p>sign it</p></li> +<li><p>pack it</p></li> +</ol> +<p>Fairly easy, no?</p> +<h2 id="organization-of-directory-of-applications">Organization of directory of applications</h2> +<h3 id="directory-where-are-stored-applications">directory where are stored applications</h3> +<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> <p>This translates to:</p> - <ul> <li>/usr/applications: system wide applications</li> <li>/opt/applications: removable applications</li> </ul> - - -<p>From here those paths are referenced as: “APPDIR”.</p> - -<a name="Organization.of.directory.of.applications"></a> -<h1>Organization of directory of applications</h1> - +<p>From here those paths are referenced as: "APPDIR".</p> <p>The main path for applications is: APPDIR/PKGID/VER.</p> - <p>Where:</p> - <ul> <li>APPDIR is as defined above</li> <li>PKGID is a directory whose name is the package identifier</li> <li>VER is the version of the package MAJOR.MINOR</li> </ul> - - -<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> - -<a name="Identity.of.installed.files"></a> -<h2>Identity of installed files</h2> - -<p>All files are installed as user “userapp” and group “userapp”. -All files have rw(x) for user and r-(x) for group and others.</p> - +<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> +<h3 id="identity-of-installed-files">Identity of installed files</h3> +<p>All files are installed as user "afm" and group "afm". All files have rw(x) for user and r-(x) for group and others.</p> <p>This allows every user to read every file.</p> - -<a name="labeling.the.directories.of.applications"></a> -<h2>labeling the directories of applications</h2> - -<a name="organization.of.data"></a> -<h1>organization of data</h1> - -<p>The data of a user are in its directory and are labelled using the labels of the application</p> +<h3 id="labeling-the-directories-of-applications">labeling the directories of applications</h3> +<p>The data of a user are in its directory and are labelled by the security-manager using the labels of the application.</p> </body> </html> |