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