git-svn-id: https://garage.maemo.org/svn/hildon-app-mgr/trunk@318 e55152ac-3a23-0410...
[hildon-application-manager:kalfa-ham.git] / README
1 This is hildon-application-manager, version 2
2 =============================================
3
4 The Hildon Application Manager is a program to manage add-on software
5 components for the Hildon Desktop.  It uses the Debian package
6 management tools provided by the maemo platform (namely APT and dpkg)
7 and presents a 'end user oriented' interface to them.
8
9 The Debian package management tools are powerful enough to manage the
10 whole system, but the Hildon Application Manager does not offer the
11 full power to the user.
12
13 Instead, the Hildon Application Manager is intended to be fully
14 compatible with existing and future interfaces to the package
15 management tools.  It should be possible to, for example, freely
16 alternate between apt-get, synaptic and the Hildon Application Manager
17 and not have anything break.  Thus, if you need more power, you can
18 use Debian package management tools directly, or use one of the more
19 powerful interfaces.
20
21
22 Documentation
23 -------------
24
25 Technical documentation can be found in the doc/ directory.  It mostly
26 explains how the apt technology is used in the context of maemo and
27 how it has been extended.  There are three main documents:
28
29 - packaging.txt
30
31   For package maintainers; explains things like how to make the
32   Application installer not hide your package from the user, how to
33   associate an icon with it, etc.
34
35 - repository.txt
36
37   For repository maintainers; explains things like how to "certify"
38   parts of a repository, etc.
39
40 - install.txt
41
42   For people writing .install files.
43
44
45 About the implementation
46 ------------------------
47
48 If you want to dive into the code, this is your spring board (aka "The
49 Design Document").  This section gives a high level overview of the
50 implementation, highlights general principles and then describes how
51 the code is divided into files.  Further documentation of internal
52 APIs etc. is contained in the appropriate source code files.
53
54
55 The essential library that provides the actual package management
56 functionality is libapt-pkg.  It is used by the Application installer
57 in the same way as apt-get, Synaptic and aptitude use it and its use
58 integrates the Application installer seamlessly into the system-wide
59 package management.
60
61 The Application manager runs as two processes: The first process
62 implements the GUI and runs as the user who started the Application
63 Manager.  The second process is started in the background and is the
64 one that actually links to libapt-pkg and does all the package
65 management work.  It runs as "root".
66
67 The first process is called the "frontend", the second one is called
68 the "backend".
69
70 The frontend starts the backend by executing an appropriate "sudo"
71 command (in the Scratchbox environment, fakeroot is used instead).
72 The two processes communicate via named fifos using an ad-hoc, binary,
73 private protocol.  The frontend also captures stdout and stderr of the
74 backend and makes it available to the user as the "Log".
75
76 No attempt has been made to restrict access to the backend.  Every
77 program, not just the frontend, can start the backend without needig
78 to provide any credentials such as the root password.  Since the
79 backend can be instructed to execute arbitrary code (via the
80 maintainer scripts of a package), having the Application installer in
81 your system is like having a globally known password on the root
82 account.  This is deemed acceptable for the maemo platform since
83 devices built using that platform are not multi-user devices (yet) and
84 there is no system administrator.  Privilege separation is used only
85 to contain damage in the case of accidents, not to defend against
86 attacks.
87
88 The backend is command driven: it reads a request, executes it, ships
89 back a respose, and then loops to reads the next request.  It
90 asynchronously sends status upates.  Downloads performed by the
91 backend are interuptible, but in general commands are not
92 interruptible.
93
94 The frontend is event driven in the usual way.  It will send requests
95 to the backend and then react to it when the result arrives by
96 executing a registered callback.  Somewhat unusually, it will just run
97 one event loop and no recursive ones for modal dialogs or when waiting
98 for a reponse from the backend.  In effect, the control flow is
99 implemented in continuation passing style.  (The event loop is the
100 trampoline that gives us the desired tail-call elimination for this.)
101
102 The motivation for using continuation passing style was to avoid
103 spontanous reentry of event callbacks (which are not supported by Gtk+
104 and are tricky in general) but still have a fully concurrent 'UI
105 experience'.  Thus most of the code does not need to be reentrant,
106 which makes it easier to reason about its robustness.
107
108 Writing in continuation passing style in C is a bit cumbersome, but
109 worth it, in my opinion.
110
111 The backend and most of the frontend is written in C++, but a small
112 part of the GUI code is plain C to enable easier transportation into
113 external libraries or reuse.  Despite the use of C++, this is not a
114 object oriented program.  No inheritance, run-time types, exceptions
115 or templates are used.
116
117
118 The backend is contained in the single file "apt-worker.cc".
119
120 The protocol that is used between the frontend and the backend is
121 defined in "apt-worker-proto.h".  Support for encoding and decoding it
122 'for the wire' is contained in "apt-worker-proto.cc".  These two files
123 are used by both the frontend and the backend, but no other source
124 files are shared.
125
126 The frontend uses global variables without prejudice and in a
127 disciplined way.  Being a program (and not a library), the frontend
128 naturally has a well defined global state and the knowledge about this
129 is exploited to simplify the internal APIs.  For example, the function
130 'do_current_operation' takes no parameters and will start the
131 installation/upgrading/removal process of the currently highlighted
132 package, depending on the currently active view.  However, the global
133 package list and the global section list clearly go to far and need to
134 be 'unglobalized'.
135
136 The frontend implementation is divided into a number of files
137 according to easily recognizable UI features.  Internal APIs are
138 documented in the header files.
139
140 - main.h, main.cc
141
142   Contains the main logic, such as all the views and code for
143   installing/upgrading/removing packages and installing from a file.
144   The header file defines the main data structure used by the
145   frontend: package_info.
146
147 - menu.h, menu.cc
148
149   The main menu and the context menu for package lists.
150
151 - details.h, details.cc
152
153   The "Details" dialog.
154
155 - settings.h, settings.cc
156
157   The "Settings" dialog and loading saving of settings and persistent
158   state.
159
160 - search.h, search.cc
161
162   The "Search" dialog.  The actual searching is implemented in main.cc.
163
164 - repo.h, repo.cc
165
166   The "Catalogue" dialog.
167
168 - log.h, log.cc
169
170   The "Log" dialog.
171
172 - instr.h, instr.cc
173
174   For handling the MIME type application/x-install-instructions.
175
176 - util.h, util.cc
177
178   A host of general UI and non-UI related utilities such as
179   confirmation dialogs, scrollable text views, progress indicators,
180   etc.
181
182   These files also contain the implementation of the package list and
183   section list functionality.
184
185 - xexp.h, xexp.c
186
187   A implementation of a expressive, general purpose data structure,
188   inspired by S-Expressions but encoded in XML.  This data structure
189   is used for storing the catalogue settings and when scripting the
190   Application Manager via .install files.  Xexps can be exchanged
191   easily between the frontend and backend.
192
193 - hildonbreadcrumbtrail.h, hildonbreadcrumbtrail.c
194
195   A throw-away implementation of the breadcrumb trail 'widget'.  These
196   files might turn one-day into a real, reuseable widget, but right
197   now they only implement the bare necessities.
198
199 - apt-worker-client.h, apt-worker-client.cc
200
201   Support for starting the backend and communicating with it.
202
203
204 BUGS
205 ----
206
207 - Don't backup pre-configured catalogues
208 - Polish multi-package flow
209 - "Unable to refresh all catalogues"
210 - Explain non-removable system updates in Details dialog.
211 - Implement Maemo-Upgrade-Description
212 - check filter_dist 
213 - check autoremoval
214 - Implement real trust domains
215 - Implement smart download location chosing.
216 - Implement catalogue filtering in instr.cc
217
218 Cleanup
219 -------
220
221 The code needs a serious cleanup.  For example
222
223 - the global package and section list needs to be unglobalized.
224 - likewise localize_file_and_keep_it_open.
225 - instead of recreating widgets all the time, we should hide/show them.
226
227 ThirdPartyApt
228 -------------
229
230 Here: https://wiki.ubuntu.com/ThirdPartyApt
231
232 Migration
233 ---------
234
235 Files to migrate when upgrading from osso-application-installer to
236 hildon-application-manager:
237
238   ~user/.osso/appinstaller
239   ~user/.osso/hildon-application-manager
240
241   /var/lib/osso-application-installer
242   /var/lib/hildon-application-manager
243   keep symlink
244
245   /etc/osso-application-installer
246   /etc/hildon-application-manager
247
248 External references
249
250   l10n textdomain
251   - use old name for now.
252
253   osso-application-installer-main-view in themes
254   - use old name for now.
255
256   window name in select-menu-location
257   - switch to new name.