- merge repomd branch
[apt.git] / doc / guide.sgml
1 <!-- -*- mode: sgml; mode: fold -*- -->
2 <!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
3 <book>
4 <title>APT User's Guide</title>
5
6 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
7 <version>$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $</version>
8
9 <abstract>
10 This document provides an overview of how to use the the APT package manager.
11 </abstract>
12
13 <copyright>
14 Copyright &copy; Jason Gunthorpe, 1998.
15 <p>
16 "APT" and this document are free software; you can redistribute them and/or
17 modify them under the terms of the GNU General Public License as published
18 by the Free Software Foundation; either version 2 of the License, or (at your
19 option) any later version.
20
21 <p>
22 For more details, on Debian GNU/Linux systems, see the file
23 /usr/share/common-licenses/GPL for the full license.
24 </copyright>
25
26 <toc sect>
27
28 <!-- General                                                           {{{ -->
29 <!-- ===================================================================== -->
30 <chapt>General
31
32 <p>
33 The APT package currently contains two sections, the APT <prgn>dselect</>
34 method and the <prgn>apt-get</> command line user interface. Both provide 
35 a way to install and remove packages as well as download new packages from 
36 the Internet. 
37
38 <sect>Anatomy of the Package System
39 <p>
40 The Debian packaging system has a large amount of information associated with
41 each package to help assure that it integrates cleanly and easily into
42 the system. The most prominent of its features is the dependency system.
43
44 <p>
45 The dependency system allows individual programs to make use of shared 
46 elements in the system such as libraries. It simplifies placing infrequently 
47 used portions of a program in separate packages to reduce the
48 number of things the average user is required to install. Also, it allows
49 for choices in mail transport agents, X servers and 
50 so on.
51
52 <p>
53 The first step to understanding the dependency system is to grasp the concept
54 of a simple dependency. The meaning of a simple dependency is that a package
55 requires another package to be installed at the same time to work properly.
56
57 <p>
58 For instance, mailcrypt is an emacs extension that aids in encrypting email
59 with GPG. Without GPGP installed mail-crypt is useless, so mailcrypt has a
60 simple dependency on GPG. Also, because it is an emacs extension it has a 
61 simple dependency on emacs, without emacs it is completely useless.
62
63 <p>
64 The other important dependency to understand is a conflicting dependency. It
65 means that a package, when installed with another package, will not work and
66 may possibly be extremely harmful to the system. As an example consider a
67 mail transport agent such as sendmail, exim or qmail. It is not possible
68 to have two mail transport agents installed because both need to listen to
69 the network to receive mail. Attempting to install two will seriously
70 damage the system so all mail transport agents have a conflicting dependency
71 with all other mail transport agents.
72
73 <p>
74 As an added complication there is the possibility for a package to pretend
75 to be another package. Consider that exim and sendmail for many intents are
76 identical, they both deliver mail and understand a common interface. Hence,
77 the package system has a way for them to declare that they are both
78 mail-transport-agents. So, exim and sendmail both declare that they provide a
79 mail-transport-agent and other packages that need a mail transport agent
80 depend on mail-transport-agent. This can add a great deal of confusion when 
81 trying to manually fix packages.
82
83 <p>
84 At any given time a single dependency may be met by packages that are already
85 installed or it may not be. APT attempts to help resolve dependency issues
86 by providing a number of automatic algorithms that help in selecting packages
87 for installation.
88 </sect>
89
90 </chapt>
91                                                                   <!-- }}} -->
92 <!-- apt-get                                                           {{{ -->
93 <!-- ===================================================================== -->
94 <chapt>apt-get
95
96 <p>
97 <prgn>apt-get</> provides a simple way to install packages from the command 
98 line. Unlike <prgn>dpkg</>, <prgn>apt-get</> does not understand .deb files, 
99 it works with the package's proper name and can only install .deb archives from 
100 a <em>Source</>.
101
102 <p>
103 The first <footnote>If you are using an http proxy server you must set the
104 http_proxy environment variable first, see sources.list(5)</footnote> thing that 
105 should be done before using <prgn>apt-get</> is to fetch the package lists
106 from the <em>Sources</> so that it knows what packages are 
107 available. This is done with <tt>apt-get update</>. For instance,
108
109 <p>
110 <example>
111 # apt-get update
112 Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
113 Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages
114 Reading Package Lists... Done
115 Building Dependency Tree... Done
116 </example>
117
118 <p>
119 Once updated there are several commands that can be used:
120 <taglist>
121 <tag>upgrade<item>
122 Upgrade will attempt to gently upgrade the whole system. Upgrade will
123 never install a new package or remove an existing package, nor will it
124 ever upgrade a package that might cause some other package to break.
125 This can be used daily to relatively safely upgrade the system. Upgrade
126 will list all of the packages that it could not upgrade, this usually
127 means that they depend on new packages or conflict with some other package.
128 <prgn>dselect</> or <tt>apt-get install</> can be used to force these
129 packages to install.
130
131 <tag>install<item>
132 Install is used to install packages by name. The package is 
133 automatically fetched and installed. This can be useful if you already
134 know the name of the package to install and do not want to go into a GUI
135 to select it. Any number of packages may be passed to install, they will
136 all be fetched. Install automatically attempts to resolve dependency problems
137 with the listed packages and will print a summary and ask for confirmation
138 if anything other than its arguments are changed.
139
140 <tag>dist-upgrade<item>
141 Dist-upgrade is a complete upgrader designed to simplify upgrading between
142 releases of Debian. It uses a sophisticated algorithm to determine the best
143 set of packages to install, upgrade and remove to get as much of the system
144 to the newest release. In some situations it may be desired to use dist-upgrade
145 rather than spend the time manually resolving dependencies in <prgn>dselect</>.
146 Once dist-upgrade has completed then <prgn>dselect</> can be used to install
147 any packages that may have been left out.
148
149 <p>
150 It is important to closely look at what dist-upgrade is going to do, its
151 decisions may sometimes be quite surprising.
152 </taglist>
153
154 <p>
155 <prgn>apt-get</> has several command line options that are detailed in its
156 man page, <manref name="apt-get" section="8">. The most useful option is 
157 <tt>-d</> which does not install the fetched files. If the system has to
158 download a large number of package it would be undesired to start installing
159 them in case something goes wrong. When <tt>-d</> is used the downloaded
160 archives can be installed by simply running the command that caused them to
161 be downloaded again without <tt>-d</>.
162
163 </chapt>
164                                                                   <!-- }}} -->
165 <!-- DSelect                                                           {{{ -->
166 <!-- ===================================================================== -->
167 <chapt>DSelect
168 <p>
169 The APT <prgn>dselect</> method provides the complete APT system with 
170 the <prgn>dselect</> package selection GUI. <prgn>dselect</> is used to
171 select the packages to be installed or removed and APT actually installs them.
172
173 <p>
174 To enable the APT method you need to to select [A]ccess in <prgn>dselect</> 
175 and then choose the APT method. You will be prompted for a set of 
176 <em>Sources</> which are places to fetch archives from. These can be remote
177 Internet sites, local Debian mirrors or CDROMs. Each source can provide
178 a fragment of the total Debian archive, APT will automatically combine them
179 to form a complete set of packages. If you have a CDROM then it is a good idea
180 to specify it first and then specify a mirror so that you have access to
181 the latest bug fixes. APT will automatically use packages on your CDROM before
182 downloading from the Internet.
183
184 <p>
185 <example>
186    Set up a list of distribution source locations
187          
188  Please give the base URL of the debian distribution.
189  The access schemes I know about are: http file
190            
191  For example:
192       file:/mnt/debian,
193       ftp://ftp.debian.org/debian,
194       http://ftp.de.debian.org/debian,
195       
196       
197  URL [http://llug.sep.bnl.gov/debian]: 
198 </example>
199
200 <p>
201 The <em>Sources</> setup starts by asking for the base of the Debian
202 archive, defaulting to a HTTP mirror. Next it asks for the distribution to
203 get.
204
205 <p>
206 <example>
207  Please give the distribution tag to get or a path to the
208  package file ending in a /. The distribution
209  tags are typically something like: stable unstable testing non-US
210    
211  Distribution [stable]: 
212 </example>
213
214 <p>
215 The distribution refers to the Debian version in the archive, <em>stable</>
216 refers to the latest released version and <em>unstable</> refers to the
217 developmental version. <em>non-US</> is only available on some mirrors and
218 refers to packages that contain encryption technology or other things that
219 cannot be exported from the United States. Importing these packages into the
220 US is legal however. 
221
222 <p>
223 <example>
224  Please give the components to get
225  The components are typically something like: main contrib non-free
226   
227  Components [main contrib non-free]:
228 </example>
229
230 <p>
231 The components list refers to the list of sub distributions to fetch. The
232 distribution is split up based on software licenses, main being DFSG free
233 packages while contrib and non-free contain things that have various 
234 restrictions placed on their use and distribution.
235
236 <p>
237 Any number of sources can be added, the setup script will continue to
238 prompt until you have specified all that you want.
239
240 <p>
241 Before starting to use <prgn>dselect</> it is necessary to update the 
242 available list by selecting [U]pdate from the menu. This is a super-set of 
243 <tt>apt-get update</> that makes the fetched information available to
244 <prgn>dselect</>. [U]pdate must be performed even if <tt>apt-get update</>
245 has been run before.
246
247 <p>
248 You can then go on and make your selections using [S]elect and then 
249 perform the installation using [I]nstall. When using the APT method
250 the [C]onfig and [R]emove commands have no meaning, the [I]nstall command
251 performs both of them together. 
252
253 <p>
254 By default APT will automatically remove the package (.deb) files once they have been
255 successfully installed. To change this behavior place <tt>Dselect::clean 
256 "prompt";</> in /etc/apt/apt.conf.
257
258 </chapt>
259                                                                   <!-- }}} -->
260 <!-- The Interfaces                                                    {{{ -->
261 <!-- ===================================================================== -->
262 <chapt>The Interface
263
264 <p>
265 Both that APT <prgn>dselect</> method and <prgn>apt-get</> share the same
266 interface. It is a simple system that generally tells you what it will do
267 and then goes and does it. 
268 <footnote>
269 The <prgn>dselect</> method actually is a set of wrapper scripts
270 to <prgn>apt-get</>. The method actually provides more functionality than
271 is present in <prgn>apt-get</> alone.
272 </footnote>
273 After printing out a summary of what will happen APT then will print out some
274 informative status messages so that you can estimate how far along it is and
275 how much is left to do.
276
277 <!-- ===================================================================== -->
278 <sect>Startup
279
280 <p>
281 Before all operations except update, APT performs a number of actions to
282 prepare its internal state. It also does some checks of the system's state.
283 At any time these operations can be performed by running <tt>apt-get check</>.
284 <p>
285 <example>
286 # apt-get check
287 Reading Package Lists... Done
288 Building Dependency Tree... Done
289 </example>
290
291 <p>
292 The first thing it does is read all the package files into memory. APT
293 uses a caching scheme so this operation will be faster the second time it
294 is run. If some of the package files are not found then they will be ignored
295 and a warning will be printed when apt-get exits. 
296
297 <p>
298 The final operation performs a detailed analysis of the system's dependencies.
299 It checks every dependency of every installed or unpacked package and considers
300 if it is OK. Should this find a problem then a report will be printed out and
301 <prgn>apt-get</> will refuse to run.
302
303 <p>
304 <example>
305 # apt-get check
306 Reading Package Lists... Done
307 Building Dependency Tree... Done
308 You might want to run apt-get -f install' to correct these.
309 Sorry, but the following packages have unmet dependencies:
310   9fonts: Depends: xlib6g but it is not installed
311   uucp: Depends: mailx but it is not installed
312   blast: Depends: xlib6g (>= 3.3-5) but it is not installed
313   adduser: Depends: perl-base but it is not installed
314   aumix: Depends: libgpmg1 but it is not installed
315   debiandoc-sgml: Depends: sgml-base but it is not installed
316   bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed
317   cthugha: Depends: svgalibg1 but it is not installed
318            Depends: xlib6g (>= 3.3-5) but it is not installed
319   libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)
320 </example>
321
322 <p>
323 In this example the system has many problems, including a serious problem
324 with libreadlineg2. For each package that has unmet dependencies a line
325 is printed out indicating the package with the problem and the dependencies
326 that are unmet. A short explanation of why the package has a dependency
327 problem is also included.
328
329 <p>
330 There are two ways a system can get into a broken state like this. The
331 first is caused by <prgn>dpkg</> missing some subtle relationships between 
332 packages when performing upgrades. <footnote>APT however considers all known 
333 dependencies and attempts to prevent broken packages</footnote>. The second is 
334 if a package installation fails during an operation. In this situation a 
335 package may have been unpacked without its dependents being installed.
336
337 <p>
338 The second situation is much less serious than the first because APT places
339 certain constraints on the order that packages are installed. In both cases
340 supplying the <tt>-f</> option to <prgn>apt-get</> will cause APT to deduce a
341 possible solution to the problem and then continue on. The APT <prgn>dselect</> 
342 method always supplies the <tt>-f</> option to allow for easy continuation
343 of failed maintainer scripts.
344
345 <p>
346 However, if the <tt>-f</> option is used to correct a seriously broken system
347 caused by the first case then it is possible that it will either fail 
348 immediately or the installation sequence will fail. In either case it is
349 necessary to manually use dpkg (possibly with forcing options) to correct
350 the situation enough to allow APT to proceed.
351 </sect>
352
353 <!-- ===================================================================== -->
354 <sect>The Status Report
355
356 <p>
357 Before proceeding <prgn>apt-get</> will present a report on what will happen.
358 Generally the report reflects the type of operation being performed but there
359 are several common elements. In all cases the lists reflect the final state
360 of things, taking into account the <tt>-f</> option and any other relevant
361 activities to the command being executed.
362
363 <sect1>The Extra Package list
364 <p>
365 <example>
366 The following extra packages will be installed:
367   libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl
368   mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base
369   bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy
370   squake pgp-i python-base debmake ldso perl libreadlineg2
371   ssh
372 </example>
373
374 <p>
375 The Extra Package list shows all of the packages that will be installed 
376 or upgraded in excess of the ones mentioned on the command line. It is
377 only generated for an <tt>install</> command. The listed packages are
378 often the result of an Auto Install.
379 </sect1>
380
381 <sect1>The Packages to Remove
382 <p>
383 <example>
384 The following packages will be REMOVED:
385   xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix
386   xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel
387   xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid
388   nas xpilot xfig 
389 </example>
390
391 <p>
392 The Packages to Remove list shows all of the packages that will be
393 removed from the system. It can be shown for any of the operations and 
394 should be given a careful inspection to ensure nothing important is to 
395 be taken off. The <tt>-f</> option is especially good at generating packages
396 to remove so extreme care should be used in that case. The list may contain
397 packages that are going to be removed because they are only 
398 partially installed, possibly due to an aborted installation.
399 </sect1>
400
401 <sect1>The New Packages list
402 <p>
403 <example>
404 The following NEW packages will installed:
405   zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
406 </example>
407
408 <p>
409 The New Packages list is simply a reminder of what will happen. The packages
410 listed are not presently installed in the system but will be when APT is done.
411 </sect1>
412
413 <sect1>The Kept Back list
414 <p>
415 <example>
416 The following packages have been kept back
417   compface man-db tetex-base msql libpaper svgalib1
418   gs snmp arena lynx xpat2 groff xscreensaver
419 </example>
420
421 <p>
422 Whenever the whole system is being upgraded there is the possibility that
423 new versions of packages cannot be installed because they require new things
424 or conflict with already installed things. In this case the package will 
425 appear in the Kept Back list. The best way to convince packages listed
426 there to install is with <tt>apt-get install</> or by using <prgn>dselect</>
427 to resolve their problems.
428 </sect1>
429
430 <sect1>Held Packages warning
431 <p>
432 <example>
433 The following held packages will be changed:
434   cvs 
435 </example>
436
437 <p>
438 Sometimes you can ask APT to install a package that is on hold, in such a 
439 case it prints out a warning that the held package is going to be
440 changed. This should only happen during dist-upgrade or install.
441 </sect1>
442
443 <sect1>Final summary
444 <p>
445 Finally, APT will print out a summary of all the changes that will occur.
446
447 <p>
448 <example>
449 206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded.
450 12 packages not fully installed or removed.
451 Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used. 
452 </example>
453
454 <p>
455 The first line of the summary simply is a reduced version of all of the
456 lists and includes the number of upgrades - that is packages already 
457 installed that have new versions available. The second line indicates the
458 number of poorly configured packages, possibly the result of an aborted
459 installation. The final line shows the space requirements that the
460 installation needs. The first pair of numbers refer to the size of
461 the archive files. The first number indicates the number of bytes that
462 must be fetched from remote locations and the second indicates the
463 total size of all the archives required. The next number indicates the
464 size difference between the presently installed packages and the newly
465 installed packages. It is roughly equivalent to the space required in 
466 /usr after everything is done. If a large number of packages are being
467 removed then the value may indicate the amount of space that will be
468 freed.
469
470 <p>
471 Some other reports can be generated by using the -u option to show packages
472 to upgrade, they are similar to the previous examples.
473 </sect>
474
475 <!-- ===================================================================== -->
476 <sect>The Status Display
477 <p>
478 During the download of archives and package files APT prints out a series of
479 status messages.
480
481 <p>
482 <example>
483 # apt-get update
484 Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages
485 Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages
486 Hit http://llug.sep.bnl.gov/debian/ testing/main Packages
487 Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
488 Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages
489 11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
490 </example>
491
492 <p>
493 The lines starting with <em>Get</> are printed out when APT begins to fetch 
494 a file while the last line indicates the progress of the download. The first 
495 percent  value on the progress line indicates the total percent done of all 
496 files. Unfortunately since the size of the Package files is unknown 
497 <tt>apt-get update</> estimates the percent done which causes some 
498 inaccuracies.
499
500 <p>
501 The next section of the status line is repeated once for each download thread
502 and indicates the operation being performed and some useful information
503 about what is happening. Sometimes this section will simply read <em>Forking</>
504 which means the OS is loading the download module. The first word after the [
505 is the fetch number as shown on the history lines. The next word
506 is the short form name of the object being downloaded. For archives it will
507 contain the name of the package that is being fetched.
508
509 <p>
510 Inside of the single quote is an informative string indicating the progress
511 of the negotiation phase of the download. Typically it progresses from 
512 <em>Connecting</> to <em>Waiting for file</> to <em>Downloading</> or
513 <em>Resuming</>. The final value is the number of bytes downloaded from the
514 remote site. Once the download begins this is represented as <tt>102/10.2k</>
515 indicating that 102 bytes have been fetched and 10.2 kilobytes is expected.
516 The total size is always shown in 4 figure notation to preserve space. After
517 the size display is a percent meter for the file itself.
518 The second last element is the instantaneous average speed. This values is 
519 updated every 5 seconds and reflects the rate of data transfer for that 
520 period. Finally is shown the estimated transfer time. This is updated
521 regularly and reflects the time to complete everything at the shown 
522 transfer rate.
523
524 <p> 
525 The status display updates every half second to provide a constant feedback 
526 on the download progress while the Get lines scroll back whenever a new
527 file is started. Since the status display is constantly updated it is
528 unsuitable for logging to a file, use the <tt>-q</> option to remove the
529 status display.
530 </sect>
531
532 <!-- ===================================================================== -->
533 <sect>Dpkg
534
535 <p>
536 APT uses <prgn>dpkg</> for installing the archives and will switch
537 over to the <prgn>dpkg</> interface once downloading is completed.
538 <prgn>dpkg</> will also ask a number of questions as it processes the packages
539 and the packages themselves may also ask several questions. Before each 
540 question there is usually a description of what it is asking and the
541 questions are too varied to discuss completely here.
542 </sect>
543
544 </chapt>
545                                                                   <!-- }}} -->
546
547 </book>