Mention red-pill.txt.
[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 - red-pill.txt
45
46   For power users.
47
48 About the implementation
49 ------------------------
50
51 If you want to dive into the code, this is your spring board (aka "The
52 Design Document").  This section gives a high level overview of the
53 implementation, highlights general principles and then describes how
54 the code is divided into files.  Further documentation of internal
55 APIs etc. is contained in the appropriate source code files.
56
57
58 The essential library that provides the actual package management
59 functionality is libapt-pkg.  It is used by the Application installer
60 in the same way as apt-get, Synaptic and aptitude use it and its use
61 integrates the Application installer seamlessly into the system-wide
62 package management.
63
64 The Application manager runs as two processes: The first process
65 implements the GUI and runs as the user who started the Application
66 Manager.  The second process is started in the background and is the
67 one that actually links to libapt-pkg and does all the package
68 management work.  It runs as "root".
69
70 The first process is called the "frontend", the second one is called
71 the "backend".
72
73 The frontend starts the backend by executing an appropriate "sudo"
74 command (in the Scratchbox environment, fakeroot is used instead).
75 The two processes communicate via named fifos using an ad-hoc, binary,
76 private protocol.  The frontend also captures stdout and stderr of the
77 backend and makes it available to the user as the "Log".
78
79 No attempt has been made to restrict access to the backend.  Every
80 program, not just the frontend, can start the backend without needig
81 to provide any credentials such as the root password.  Since the
82 backend can be instructed to execute arbitrary code (via the
83 maintainer scripts of a package), having the Application installer in
84 your system is like having a globally known password on the root
85 account.  This is deemed acceptable for the maemo platform since
86 devices built using that platform are not multi-user devices (yet) and
87 there is no system administrator.  Privilege separation is used only
88 to contain damage in the case of accidents, not to defend against
89 attacks.
90
91 The backend is command driven: it reads a request, executes it, ships
92 back a respose, and then loops to reads the next request.  It
93 asynchronously sends status upates.  Downloads performed by the
94 backend are interuptible, but in general commands are not
95 interruptible.
96
97 The frontend is event driven in the usual way.  It will send requests
98 to the backend and then react to it when the result arrives by
99 executing a registered callback.  Somewhat unusually, it will just run
100 one event loop and no recursive ones for modal dialogs or when waiting
101 for a reponse from the backend.  In effect, the control flow is
102 implemented in continuation passing style.  (The event loop is the
103 trampoline that gives us the desired tail-call elimination for this.)
104
105 The motivation for using continuation passing style was to avoid
106 spontanous reentry of event callbacks (which are not supported by Gtk+
107 and are tricky in general) but still have a fully concurrent 'UI
108 experience'.  Thus most of the code does not need to be reentrant,
109 which makes it easier to reason about its robustness.
110
111 Writing in continuation passing style in C is a bit cumbersome, but
112 worth it, in my opinion.
113
114 The backend and most of the frontend is written in C++, but a small
115 part of the GUI code is plain C to enable easier transportation into
116 external libraries or reuse.  Despite the use of C++, this is not a
117 object oriented program.  No inheritance, run-time types, exceptions
118 or templates are used.
119
120
121 The backend is contained in the single file "apt-worker.cc".
122
123 The protocol that is used between the frontend and the backend is
124 defined in "apt-worker-proto.h".  Support for encoding and decoding it
125 'for the wire' is contained in "apt-worker-proto.cc".  These two files
126 are used by both the frontend and the backend, but no other source
127 files are shared.
128
129 The frontend uses global variables without prejudice and in a
130 disciplined way.  Being a program (and not a library), the frontend
131 naturally has a well defined global state and the knowledge about this
132 is exploited to simplify the internal APIs.  For example, the function
133 'do_current_operation' takes no parameters and will start the
134 installation/upgrading/removal process of the currently highlighted
135 package, depending on the currently active view.  However, the global
136 package list and the global section list clearly go to far and need to
137 be 'unglobalized'.
138
139 The frontend implementation is divided into a number of files
140 according to easily recognizable UI features.  Internal APIs are
141 documented in the header files.
142
143 - main.h, main.cc
144
145   Contains the main logic, such as all the views and code for
146   installing/upgrading/removing packages and installing from a file.
147   The header file defines the main data structure used by the
148   frontend: package_info.
149
150 - menu.h, menu.cc
151
152   The main menu and the context menu for package lists.
153
154 - details.h, details.cc
155
156   The "Details" dialog.
157
158 - settings.h, settings.cc
159
160   The "Settings" dialog and loading saving of settings and persistent
161   state.
162
163 - search.h, search.cc
164
165   The "Search" dialog.  The actual searching is implemented in main.cc.
166
167 - repo.h, repo.cc
168
169   The "Catalogue" dialog.
170
171 - log.h, log.cc
172
173   The "Log" dialog.
174
175 - instr.h, instr.cc
176
177   For handling the MIME type application/x-install-instructions.
178
179 - util.h, util.cc
180
181   A host of general UI and non-UI related utilities such as
182   confirmation dialogs, scrollable text views, progress indicators,
183   etc.
184
185   These files also contain the implementation of the package list and
186   section list functionality.
187
188 - xexp.h, xexp.c
189
190   A implementation of a expressive, general purpose data structure,
191   inspired by S-Expressions but encoded in XML.  This data structure
192   is used for storing the catalogue settings and when scripting the
193   Application Manager via .install files.  Xexps can be exchanged
194   easily between the frontend and backend.
195
196 - confutils.h, confutils.cc
197
198   Utilities for handling configuration related tasks.  Used in the
199   frontend, backend, and the hildon-application-manager-config utility
200   program.
201
202 - hildonbreadcrumbtrail.h, hildonbreadcrumbtrail.c
203
204   A throw-away implementation of the breadcrumb trail 'widget'.  These
205   files might turn one-day into a real, reuseable widget, but right
206   now they only implement the bare necessities.
207
208 - apt-worker-client.h, apt-worker-client.cc
209
210   Support for starting the backend and communicating with it.
211
212 - hildon-application-manager-config.cc
213
214   A command line utility for managing the configuration data of the
215   Application Manager.
216
217 BUGS
218 ----
219
220 - Make reboot decision more flexible.  (from maintainer scripts?)
221 - Reenable apt-transport-https by using nss.
222 - Take update-notifier menu contents into account for the blinking state.
223 - Call reset_idle_timer more often
224 - Add "New Folder" functionality to maemo-select-menu-location.
225 - Explain non-removable system updates in Details dialog.
226 - Consider autolaunching.
227
228 Cleanup
229 -------
230
231 The code needs a serious cleanup.  For example
232
233 - the global package and section list needs to be unglobalized.
234 - likewise localize_file_and_keep_it_open.
235 - instead of recreating widgets all the time, we should hide/show them.