1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
<!DOCTYPE html>
<html>
<head>
<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>
<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>
<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>
<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>
<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>
<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>
|
