- initial import of revision 374 from cnc
[apt.git] / doc / design.sgml
1 <!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
2 <debiandoc>
3   <book>
4     <titlepag>
5       <title> The APT project design document</title>
6       <author>
7         <name>Manoj Srivastava</name>
8         <email>srivasta@debian.org</email>
9       </author>
10       <version>$Id: design.sgml,v 1.4 2003/02/12 15:05:45 doogie Exp $</version>
11       <abstract>
12         This document is an overview of the specifications and design
13         goals of the APT project. It also attempts to give a broad
14         description of the implementation as well.
15       </abstract>
16       <copyright>
17         <copyrightsummary>Copyright &copy;1997 Manoj Srivastava
18         </copyrightsummary>
19         <p>
20           APT, including this document, is free software; you may
21           redistribute it and/or modify it under the terms of the GNU
22           General Public License as published by the Free Software
23           Foundation; either version 2, or (at your option) any later
24           version.</p>
25         <p>
26           This is distributed in the hope that it will be useful, but
27           <em>without any warranty</em>; without even the implied
28           warranty of merchantability or fitness for a particular
29           purpose.  See the GNU General Public License for more
30           details.</p>
31
32         <p>
33           You should have received a copy of the GNU General Public
34           License with your Debian GNU/Linux system, in
35           <tt>/usr/share/common-licenses/GPL</tt>, or with the
36           <prgn/debiandoc-sgml/ source package as the file
37           <tt>COPYING</tt>.  If not, write to the Free Software
38           Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
39           USA.</p>
40       </copyright>
41     </titlepag>
42     <chapt id="introduction">
43       <heading>Introduction</heading>
44       <p>APT is supposed to be a replacement for dselect, and not a 
45         replacement for dpkg. However, since addition functionality
46         has been required for APT, and given the fact that this is
47         very closely related to dpkg, it is not unreasonable to expect
48         that additional functionality in the underlying dpkg would
49         also be requested.</p>
50
51       <p> Diety/dselect are the first introduction that people have to
52         Debian, and unfortunately this first impression contributes
53         greatly to the public perception of the distribution. It is
54         imperative that this be a showcase for Debian, rather than
55         frighten novices away (which has been an accusation often
56         levelled at the current system)</p>
57     </chapt>
58     <chapt>
59       <heading>Requirements</heading>
60       <p>
61         <enumlist compact="compact">
62           <item>
63             <p>
64               APT should be a replacement for dselect. Therefore it
65               should have all the functionality that dselect has
66               currently. This is the primary means of interaction
67               between the user and the package management system, and
68               it should be able to handle all tasks involved in
69               installing, upgrading, and routine management without
70               having the users take recourse to the underlying
71               management system.</p>
72           </item>
73           <item>
74             <p>
75               It should be easier to use and less confusing for novice
76               users. The primary stimulus for the creation of APT
77               was the perceived intractability, complexity, and
78               non-intuitive behavior of the existing user interface,
79               and as such, human factors must be a primary mandate of
80               APT.</p>
81           </item>
82           <item>
83             <p>
84               It should be able to group packages more flexibly, and
85               possibly allow operations based on a group. One should
86               be able to select, or deselect, a coherent group of
87               related packages simultaneously, allowing one to add,
88               remove, or upgrade functionality to a machine as one
89               step.
90             </p>
91           </item>
92           <item>
93             <p>
94               This would allow APT to handle <em>standard
95                 installations</em>, namely, one could then install a
96               set of packages to enable a machine to fulfill specific
97               tasks.  Define a few standard installations, and which
98               packages are included therein. The packages should be
99               internally consistent.</p>
100           </item>
101           <item>
102             <p>
103               Make use of a keywords field in package headers; provide
104               a standard list of keywords for people to use. This
105               could be the underpinning to allow the previous two
106               requirements to work (though the developers are not
107               constrained to implement the previous requirements using
108               keywords)
109             </p>
110           </item>
111           <item>
112             <p>
113               Use dependencies, conflicts, and reverse dependencies to
114               properly order packages for installation and
115               removal. This has been a complaint in the past that the
116               installation methods do not really understand
117               dependencies, causing the upgrade process to break, or
118               allowing the removal of packages that left the system in
119               an untenable state by breaking the dependencies on
120               packages that were dependent on the package being
121               removed. A special emphasis is placed on handling
122               pre-dependencies correctly; the target of a
123               predependency has to be fully configured before
124               attempting to install the pre-dependent package. Also,
125               <em>configure immediately</em> requests mentioned below
126               should be handled.</p>
127           </item>
128           <item>
129             <p>
130               Handle replacement of a package providing a virtual
131               package with another (for example, it has been very
132               difficult replacing <prgn>sendmail</prgn> with
133               <prgn>smail</prgn>, or vice versa), making sure that the
134               dependencies are still satisfied. </p>
135           </item>
136           <item>
137             <p>
138               Handle source lists for updates from multiple
139               sources. APT should also be able to handle diverse
140               methods of acquiring new packages; local filesystem,
141               mountable CD-ROM drives, FTP accessible repositories are
142               some of the methods that come to mind.  Also, the source
143               lists can be separated into categories, such as main,
144               contrib, non-us, non-local, non-free, my-very-own,
145               etc. APT should be set up to retrieve the Packages
146               files from these multiple source lists, as well as
147               retrieving the packages themselves. </p>
148           </item>
149           <item>
150             <p>
151               Handle base of source and acquire all Packages files
152               underneath.  (possibly select based on architecture),
153               this should be a simple extension of the previous
154               requirement.</p>
155           </item>
156           <item>
157             <p>
158               Handle remote installation (to be implemented maybe in a
159               future version, it still needs to be designed). This
160               would ease the burden of maintaining multiple Debian
161               machines on a site. In the authors opinion this is a
162               killer difference for the distribution, though it may be
163               too hard a problem to be implemented with the initial
164               version of APT. However, some thought must be given to
165               this to enable APT to retain hooks for future
166               functionality, or at least to refrain from methods that
167               may preclude remote activity. It is desirable that
168               adding remote installation not require a redesign of
169               APT from the ground up.</p>
170           </item>
171           <item>
172             <p>
173               Be scalable. Dselect worked a lot better with 400
174               packages, but at last count the number of packages was
175               around twelve hundred and climbing. This also requires
176               APT to pay attention to the needs of small machines
177               which are low on memory (though this requirement shall
178               diminish as we move towards bigger machines, it would
179               still be nice if Debian worked on all old machines where
180               Linux itself would work).</p>
181           </item>
182           <item>
183             <p>
184               Handle install immediately requests. Some packages, like
185               watchdog, are required to be working for the stability
186               of the machine itself. There are others which may be
187               required for the correct functioning of a production
188               machine, or which are mission critical
189               applications. APT should, in these cases, upgrade the
190               packages with minimal downtime; allowing these packages
191               to be one of potentially hundreds of packages being
192               upgraded concurrently may not satisfy the requirements
193               of the package or the site. (Watchdog, for example, if
194               not restarted quickly, may cause the machine to reboot
195               in the midst of installation, which may cause havoc on
196               the machine)</p>
197           </item>
198         </enumlist> 
199       </p>
200     </chapt>
201     <chapt>
202       <heading>Procedural description</heading>
203       <p><taglist>
204           <tag>Set Options</tag>
205           <item>
206             <p>
207               This process handles setting of user or
208               site options, and configuration of all aspects of
209               APT. It allows the user to set the location and order
210               of package sources, allowing them to set up source list
211               details, like ftp site locations, passwords,
212               etc. Display options may also be set.</p>
213           </item>
214           <tag>Updates</tag>
215           <item>
216             <p>
217               Build a list of available packages, using
218               source lists or a base location and trawling for
219               Packages files (needs to be aware of architecture). This
220               may involve finding and retrieving Packages files,
221               storing them locally for efficiency, and parsing the
222               data for later use. This would entail contacting various
223               underlying access modules (ftp, cdrom mounts, etc) Use a
224               backing store for speed. This may also require
225               downloading the actual package files locally for
226               speed.</p>
227           </item>
228           <tag>Local status</tag>
229           <item>
230             <p>
231               Build up a list of packages already
232               installed. This requires reading and writing the local??
233               status file. For remote installation, this should
234               probably use similar mechanisms as the Packages file
235               retrieval does. Use the backing store for speed. One
236               should consider multiple backing stores, one for each
237               machine.
238             </p>
239           </item>
240           <tag>Relationship determination</tag>
241           <item>
242             <p>
243               Determine forward and reverse dependencies. All known
244               dependency fields should be acted upon, since it is
245               fairly cheap to do so. Update the backing store with
246               this information.</p>
247           </item>
248           <tag>Selection</tag>
249           <item>
250             <p>
251               Present the data to the user. Look at Behan Webster's
252               documentation for the user interface procedures. (Note:
253               In the authors opinion deletions and reverse
254               dependencies should also be presented to the user, in a
255               strictly symmetric fashion; this may make it easier to
256               prevent a package being removed that breaks
257               dependencies)
258             </p>
259           </item>
260           <tag>Ordering of package installations and configuration </tag>
261           <item>
262             <p>
263               Build a list of events. Simple topological sorting gives
264               order of packages in dependency order. At certain points
265               in this ordering, predependencies/immediate configure
266               directives cause an break in normal ordering. We need to
267               insert the uninstall/purge directive in the stream
268               (default: as early as possible).</p>
269           </item>
270           <tag>Action</tag>
271           <item>
272             <p>
273               Take the order of installations and removals and build
274               up a stream of events to send to the packaging system
275               (dpkg). Execute the list of events if successful. Do not
276               partially install packages and leave system in broken
277               state. Go to The Selection step as needed.</p>
278           </item>
279
280         </taglist>
281       </p>
282     </chapt>
283     <chapt>
284       <heading>Modules and interfaces</heading>
285       <p><taglist>
286           <tag>The user interface module</tag>
287           <item>
288             <p> Look at Behan Webster's documentation.</p> 
289           </item>
290           <tag>Widget set</tag>
291           <item>
292             <p>
293               Related closely to above Could some one present design
294               decisions of the widget set here?</p>
295           </item>
296           <tag>pdate Module</tag>
297           <item>
298             <p>     
299               Distinct versions of the same package are recorded
300               separately, but if multiple Packages files contain the
301               same version of a package, then only the first one is
302               recorded. For this reason, the least expensive update
303               source should be listed first (local file system is
304               better than a remote ftp site)</p>
305             <p>
306               This module should interact with the user interface
307               module to set and change configuration parameters for
308               the modules listed below. It needs to record that
309               information in an on disk data file, to be read on
310               future invocations. </p>
311             <p><enumlist>
312                 <item>
313                   <p>FTP methods</p>
314                 </item>
315                 <item>
316                   <p>mount and file traversal module(s)?</p>
317                 </item>
318                 <item>
319                   <p>Other methods ???</p>
320                 </item>
321               </enumlist>
322             </p>
323           </item>
324           <tag>Status file parser/generator</tag>
325           <item>
326             <p> 
327               The status file records the current state of the system,
328               listing the packages installed, etc. The status file is
329               also one method of communicating with dpkg, since it is
330               perfectly permissible for the user to use APT to
331               request packages be updated, put others on hold, mark
332               other for removal, etc, and then run <tt>dpkg
333                 -BORGiE</tt> on a file system.</p>
334           </item>
335           <tag>Package file parser/generator</tag>
336           <item>
337             <p>
338               Related to above. Handle multiple Packages files, from
339               different sources. Each package contains a link back to
340               the packages file structure that contains details about
341               the origin of the data. </p>
342           </item>
343           <tag>Dependency module</tag>
344           <item>
345             <p><list>
346                 <item>
347                   <p>dependency/conflict determination and linking</p>
348                 </item>
349                 <item>
350                   <p>reverse dependency generator. Maybe merged with above</p>
351                 </item>
352               </list>
353             </p>
354           </item>
355           <tag>Package ordering Module</tag>
356           <item>
357             <p>Create an ordering of the actions to be taken.</p>
358           </item>
359           <tag>Event generator</tag>
360           <item>
361             <p>module to interact with dpkg</p>
362           </item>
363         </taglist>
364     </chapt>
365     <chapt>
366       <heading>Data flow and conversions analysis.</heading>
367       <p> 
368         <example>
369                                                           ____________
370                                                        __\|ftp modules|
371                                                       /  /|___________|
372                                     _ ____________   /     ________________
373                                     |    update   | /     |mount/local file|
374         |==========================>|   module    |/_____\|  traversals    |
375         |                           |_____________|      /|________________|
376         |                             ^        ^
377         |                             |        |               ______________
378   ______|_______    _ _____ ______    |   _____v________      \|            |
379  |Configuration |   |configuration|   |   |Packages Files|  ===|Status file |
380  |  module      |<=>|    data     |   |   |______________| /  /|____________|
381  |______________|   |_____________|   |        ^          /
382          ^                            |        |         /
383          |                            | _______v_______|/_
384          |                            | |              |    ________________
385          |                            | |              |/_\|   Dependency  |
386          |                            | |backing store |\ /|     Module    |
387          |                            | |______________|  _|_______________|
388          |                             \       ^          /|       ^
389          |                              \      |         /         |
390          |                              _\|____v_______|/__    ____v_______
391          |_____________________________\| User interaction|    |    dpkg   |
392                                        /|_________________|<==>|  Invoker  |
393                                                                |___________|
394
395         </example>
396       <p> dpkg also interacts with status and available files.</p>
397
398
399       <p>
400         The backing store and the associated data structures are the
401         core of APT. All modules essentially revolve around the
402         backing store, feeding it data, adding and manipulating links
403         and relationships between data in the backing store, allowing
404         the user to interact with and modify the data in the backing
405         store, and finally writing it out as the status file and
406         possibly issuing directives to dpkg.</p>
407
408       <p>The other focal point for APT is the user interface.</p> 
409     </chapt>
410   </book>
411 </debiandoc>