prepare release 1.0.3

[apt.git] / doc / guide.sgml

<!-- -*- mode: sgml; mode: fold -*- -->
<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
<book>
<title>APT User's Guide</title>

<author>Jason Gunthorpe <email>jgg@debian.org</email></author>
<version>$Id: guide.sgml,v 1.7 2003/04/26 23:26:13 doogie Exp $</version>

<abstract>
This document provides an overview of how to use the the APT package manager.
</abstract>

<copyright>
Copyright &copy; Jason Gunthorpe, 1998.
<p>
"APT" and this document are free software; you can redistribute them and/or
modify them under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

<p>
For more details, on Debian systems, see the file
/usr/share/common-licenses/GPL for the full license.
</copyright>

<toc sect>

<!-- General                                                           {{{ -->
<!-- ===================================================================== -->
<chapt>General

<p>
The APT package currently contains two sections, the APT <prgn>dselect</>
method and the <prgn>apt-get</> command line user interface. Both provide 
a way to install and remove packages as well as download new packages from 
the Internet. 

<sect>Anatomy of the Package System
<p>
The Debian packaging system has a large amount of information associated with
each package to help assure that it integrates cleanly and easily into
the system. The most prominent of its features is the dependency system.

<p>
The dependency system allows individual programs to make use of shared 
elements in the system such as libraries. It simplifies placing infrequently 
used portions of a program in separate packages to reduce the
number of things the average user is required to install. Also, it allows
for choices in mail transport agents, X servers and 
so on.

<p>
The first step to understanding the dependency system is to grasp the concept
of a simple dependency. The meaning of a simple dependency is that a package
requires another package to be installed at the same time to work properly.

<p>
For instance, mailcrypt is an emacs extension that aids in encrypting email
with GPG. Without GPGP installed mailcrypt is useless, so mailcrypt has a
simple dependency on GPG. Also, because it is an emacs extension it has a 
simple dependency on emacs, without emacs it is completely useless.

<p>
The other important dependency to understand is a conflicting dependency. It
means that a package, when installed with another package, will not work and
may possibly be extremely harmful to the system. As an example consider a
mail transport agent such as sendmail, exim or qmail. It is not possible
to have two mail transport agents installed because both need to listen to
the network to receive mail. Attempting to install two will seriously
damage the system so all mail transport agents have a conflicting dependency
with all other mail transport agents.

<p>
As an added complication there is the possibility for a package to pretend
to be another package. Consider that exim and sendmail for many intents are
identical, they both deliver mail and understand a common interface. Hence,
the package system has a way for them to declare that they are both
mail-transport-agents. So, exim and sendmail both declare that they provide a
mail-transport-agent and other packages that need a mail transport agent
depend on mail-transport-agent. This can add a great deal of confusion when 
trying to manually fix packages.

<p>
At any given time a single dependency may be met by packages that are already
installed or it may not be. APT attempts to help resolve dependency issues
by providing a number of automatic algorithms that help in selecting packages
for installation.
</sect>

</chapt>
                                                                  <!-- }}} -->
<!-- apt-get                                                           {{{ -->
<!-- ===================================================================== -->
<chapt>apt-get

<p>
<prgn>apt-get</> provides a simple way to install packages from the command 
line. Unlike <prgn>dpkg</>, <prgn>apt-get</> does not understand .deb files, 
it works with the package's proper name and can only install .deb archives from 
a <em>Source</>.

<p>
The first <footnote>If you are using an http proxy server you must set the
http_proxy environment variable first, see sources.list(5)</footnote> thing that 
should be done before using <prgn>apt-get</> is to fetch the package lists
from the <em>Sources</> so that it knows what packages are 
available. This is done with <tt>apt-get update</>. For instance,

<p>
<example>
# apt-get update
Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
Get http://llug.sep.bnl.gov/debian/ testing/contrib Packages
Reading Package Lists... Done
Building Dependency Tree... Done
</example>

<p>
Once updated there are several commands that can be used:
<taglist>
<tag>upgrade<item>
Upgrade will attempt to gently upgrade the whole system. Upgrade will
never install a new package or remove an existing package, nor will it
ever upgrade a package that might cause some other package to break.
This can be used daily to relatively safely upgrade the system. Upgrade
will list all of the packages that it could not upgrade, this usually
means that they depend on new packages or conflict with some other package.
<prgn>dselect</> or <tt>apt-get install</> can be used to force these
packages to install.

<tag>install<item>
Install is used to install packages by name. The package is 
automatically fetched and installed. This can be useful if you already
know the name of the package to install and do not want to go into a GUI
to select it. Any number of packages may be passed to install, they will
all be fetched. Install automatically attempts to resolve dependency problems
with the listed packages and will print a summary and ask for confirmation
if anything other than its arguments are changed.

<tag>dist-upgrade<item>
Dist-upgrade is a complete upgrader designed to simplify upgrading between
releases of Debian. It uses a sophisticated algorithm to determine the best
set of packages to install, upgrade and remove to get as much of the system
to the newest release. In some situations it may be desired to use dist-upgrade
rather than spend the time manually resolving dependencies in <prgn>dselect</>.
Once dist-upgrade has completed then <prgn>dselect</> can be used to install
any packages that may have been left out.

<p>
It is important to closely look at what dist-upgrade is going to do, its
decisions may sometimes be quite surprising.
</taglist>

<p>
<prgn>apt-get</> has several command line options that are detailed in its
man page, <manref name="apt-get" section="8">. The most useful option is 
<tt>-d</> which does not install the fetched files. If the system has to
download a large number of package it would be undesired to start installing
them in case something goes wrong. When <tt>-d</> is used the downloaded
archives can be installed by simply running the command that caused them to
be downloaded again without <tt>-d</>.

</chapt>
                                                                  <!-- }}} -->
<!-- DSelect                                                           {{{ -->
<!-- ===================================================================== -->
<chapt>DSelect
<p>
The APT <prgn>dselect</> method provides the complete APT system with 
the <prgn>dselect</> package selection GUI. <prgn>dselect</> is used to
select the packages to be installed or removed and APT actually installs them.

<p>
To enable the APT method you need to select [A]ccess in <prgn>dselect</> 
and then choose the APT method. You will be prompted for a set of 
<em>Sources</> which are places to fetch archives from. These can be remote
Internet sites, local Debian mirrors or CD-ROMs. Each source can provide
a fragment of the total Debian archive, APT will automatically combine them
to form a complete set of packages. If you have a CD-ROM then it is a good idea
to specify it first and then specify a mirror so that you have access to
the latest bug fixes. APT will automatically use packages on your CD-ROM before
downloading from the Internet.

<p>
<example>
   Set up a list of distribution source locations
         
 Please give the base URL of the debian distribution.
 The access schemes I know about are: http file
           
 For example:
      file:/mnt/debian,
      ftp://ftp.debian.org/debian,
      http://ftp.de.debian.org/debian,
      
      
 URL [http://llug.sep.bnl.gov/debian]: 
</example>

<p>
The <em>Sources</> setup starts by asking for the base of the Debian
archive, defaulting to a HTTP mirror. Next it asks for the distribution to
get.

<p>
<example>
 Please give the distribution tag to get or a path to the
 package file ending in a /. The distribution
 tags are typically something like: stable unstable testing non-US
   
 Distribution [stable]: 
</example>

<p>
The distribution refers to the Debian version in the archive, <em>stable</>
refers to the latest released version and <em>unstable</> refers to the
developmental version. <em>non-US</> is only available on some mirrors and
refers to packages that contain encryption technology or other things that
cannot be exported from the United States. Importing these packages into the
US is legal however. 

<p>
<example>
 Please give the components to get
 The components are typically something like: main contrib non-free
  
 Components [main contrib non-free]:
</example>

<p>
The components list refers to the list of sub distributions to fetch. The
distribution is split up based on software licenses, main being DFSG free
packages while contrib and non-free contain things that have various 
restrictions placed on their use and distribution.

<p>
Any number of sources can be added, the setup script will continue to
prompt until you have specified all that you want.

<p>
Before starting to use <prgn>dselect</> it is necessary to update the 
available list by selecting [U]pdate from the menu. This is a superset of 
<tt>apt-get update</> that makes the fetched information available to
<prgn>dselect</>. [U]pdate must be performed even if <tt>apt-get update</>
has been run before.

<p>
You can then go on and make your selections using [S]elect and then 
perform the installation using [I]nstall. When using the APT method
the [C]onfig and [R]emove commands have no meaning, the [I]nstall command
performs both of them together. 

<p>
By default APT will automatically remove the package (.deb) files once they have been
successfully installed. To change this behavior place <tt>Dselect::clean 
"prompt";</> in /etc/apt/apt.conf.

</chapt>
                                                                  <!-- }}} -->
<!-- The Interfaces                                                    {{{ -->
<!-- ===================================================================== -->
<chapt>The Interface

<p>
Both that APT <prgn>dselect</> method and <prgn>apt-get</> share the same
interface. It is a simple system that generally tells you what it will do
and then goes and does it. 
<footnote>
The <prgn>dselect</> method actually is a set of wrapper scripts
to <prgn>apt-get</>. The method actually provides more functionality than
is present in <prgn>apt-get</> alone.
</footnote>
After printing out a summary of what will happen APT then will print out some
informative status messages so that you can estimate how far along it is and
how much is left to do.

<!-- ===================================================================== -->
<sect>Startup

<p>
Before all operations except update, APT performs a number of actions to
prepare its internal state. It also does some checks of the system's state.
At any time these operations can be performed by running <tt>apt-get check</>.
<p>
<example>
# apt-get check
Reading Package Lists... Done
Building Dependency Tree... Done
</example>

<p>
The first thing it does is read all the package files into memory. APT
uses a caching scheme so this operation will be faster the second time it
is run. If some of the package files are not found then they will be ignored
and a warning will be printed when apt-get exits. 

<p>
The final operation performs a detailed analysis of the system's dependencies.
It checks every dependency of every installed or unpacked package and considers
if it is OK. Should this find a problem then a report will be printed out and
<prgn>apt-get</> will refuse to run.

<p>
<example>
# apt-get check
Reading Package Lists... Done
Building Dependency Tree... Done
You might want to run apt-get -f install' to correct these.
Sorry, but the following packages have unmet dependencies:
  9fonts: Depends: xlib6g but it is not installed
  uucp: Depends: mailx but it is not installed
  blast: Depends: xlib6g (>= 3.3-5) but it is not installed
  adduser: Depends: perl-base but it is not installed
  aumix: Depends: libgpmg1 but it is not installed
  debiandoc-sgml: Depends: sgml-base but it is not installed
  bash-builtins: Depends: bash (>= 2.01) but 2.0-3 is installed
  cthugha: Depends: svgalibg1 but it is not installed
           Depends: xlib6g (>= 3.3-5) but it is not installed
  libreadlineg2: Conflicts:libreadline2 (<< 2.1-2.1)
</example>

<p>
In this example the system has many problems, including a serious problem
with libreadlineg2. For each package that has unmet dependencies a line
is printed out indicating the package with the problem and the dependencies
that are unmet. A short explanation of why the package has a dependency
problem is also included.

<p>
There are two ways a system can get into a broken state like this. The
first is caused by <prgn>dpkg</> missing some subtle relationships between 
packages when performing upgrades. <footnote>APT however considers all known 
dependencies and attempts to prevent broken packages</footnote>. The second is 
if a package installation fails during an operation. In this situation a 
package may have been unpacked without its dependents being installed.

<p>
The second situation is much less serious than the first because APT places
certain constraints on the order that packages are installed. In both cases
supplying the <tt>-f</> option to <prgn>apt-get</> will cause APT to deduce a
possible solution to the problem and then continue on. The APT <prgn>dselect</> 
method always supplies the <tt>-f</> option to allow for easy continuation
of failed maintainer scripts.

<p>
However, if the <tt>-f</> option is used to correct a seriously broken system
caused by the first case then it is possible that it will either fail 
immediately or the installation sequence will fail. In either case it is
necessary to manually use dpkg (possibly with forcing options) to correct
the situation enough to allow APT to proceed.
</sect>

<!-- ===================================================================== -->
<sect>The Status Report

<p>
Before proceeding <prgn>apt-get</> will present a report on what will happen.
Generally the report reflects the type of operation being performed but there
are several common elements. In all cases the lists reflect the final state
of things, taking into account the <tt>-f</> option and any other relevant
activities to the command being executed.

<sect1>The Extra Package list
<p>
<example>
The following extra packages will be installed:
  libdbd-mysql-perl xlib6 zlib1 xzx libreadline2 libdbd-msql-perl
  mailpgp xdpkg fileutils pinepgp zlib1g xlib6g perl-base
  bin86 libgdbm1 libgdbmg1 quake-lib gmp2 bcc xbuffy
  squake pgp-i python-base debmake ldso perl libreadlineg2
  ssh
</example>

<p>
The Extra Package list shows all of the packages that will be installed 
or upgraded in excess of the ones mentioned on the command line. It is
only generated for an <tt>install</> command. The listed packages are
often the result of an Auto Install.
</sect1>

<sect1>The Packages to Remove
<p>
<example>
The following packages will be REMOVED:
  xlib6-dev xpat2 tk40-dev xkeycaps xbattle xonix
  xdaliclock tk40 tk41 xforms0.86 ghostview xloadimage xcolorsel
  xadmin xboard perl-debug tkined xtetris libreadline2-dev perl-suid
  nas xpilot xfig 
</example>

<p>
The Packages to Remove list shows all of the packages that will be
removed from the system. It can be shown for any of the operations and 
should be given a careful inspection to ensure nothing important is to 
be taken off. The <tt>-f</> option is especially good at generating packages
to remove so extreme care should be used in that case. The list may contain
packages that are going to be removed because they are only 
partially installed, possibly due to an aborted installation.
</sect1>

<sect1>The New Packages list
<p>
<example>
The following NEW packages will installed:
  zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
</example>

<p>
The New Packages list is simply a reminder of what will happen. The packages
listed are not presently installed in the system but will be when APT is done.
</sect1>

<sect1>The Kept Back list
<p>
<example>
The following packages have been kept back
  compface man-db tetex-base msql libpaper svgalib1
  gs snmp arena lynx xpat2 groff xscreensaver
</example>

<p>
Whenever the whole system is being upgraded there is the possibility that
new versions of packages cannot be installed because they require new things
or conflict with already installed things. In this case the package will 
appear in the Kept Back list. The best way to convince packages listed
there to install is with <tt>apt-get install</> or by using <prgn>dselect</>
to resolve their problems.
</sect1>

<sect1>Held Packages warning
<p>
<example>
The following held packages will be changed:
  cvs 
</example>

<p>
Sometimes you can ask APT to install a package that is on hold, in such a 
case it prints out a warning that the held package is going to be
changed. This should only happen during dist-upgrade or install.
</sect1>

<sect1>Final summary
<p>
Finally, APT will print out a summary of all the changes that will occur.

<p>
<example>
206 packages upgraded, 8 newly installed, 23 to remove and 51 not upgraded.
12 packages not fully installed or removed.
Need to get 65.7M/66.7M of archives. After unpacking 26.5M will be used. 
</example>

<p>
The first line of the summary simply is a reduced version of all of the
lists and includes the number of upgrades - that is packages already 
installed that have new versions available. The second line indicates the
number of poorly configured packages, possibly the result of an aborted
installation. The final line shows the space requirements that the
installation needs. The first pair of numbers refer to the size of
the archive files. The first number indicates the number of bytes that
must be fetched from remote locations and the second indicates the
total size of all the archives required. The next number indicates the
size difference between the presently installed packages and the newly
installed packages. It is roughly equivalent to the space required in 
/usr after everything is done. If a large number of packages are being
removed then the value may indicate the amount of space that will be
freed.

<p>
Some other reports can be generated by using the -u option to show packages
to upgrade, they are similar to the previous examples.
</sect>

<!-- ===================================================================== -->
<sect>The Status Display
<p>
During the download of archives and package files APT prints out a series of
status messages.

<p>
<example>
# apt-get update
Get:1 http://ftp.de.debian.org/debian-non-US/ stable/non-US/ Packages
Get:2 http://llug.sep.bnl.gov/debian/ testing/contrib Packages
Hit http://llug.sep.bnl.gov/debian/ testing/main Packages
Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
Get:5 http://llug.sep.bnl.gov/debian/ testing/non-free Packages
11% [5 testing/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
</example>

<p>
The lines starting with <em>Get</> are printed out when APT begins to fetch 
a file while the last line indicates the progress of the download. The first 
percent  value on the progress line indicates the total percent done of all 
files. Unfortunately since the size of the Package files is unknown 
<tt>apt-get update</> estimates the percent done which causes some 
inaccuracies.

<p>
The next section of the status line is repeated once for each download thread
and indicates the operation being performed and some useful information
about what is happening. Sometimes this section will simply read <em>Forking</>
which means the OS is loading the download module. The first word after the [
is the fetch number as shown on the history lines. The next word
is the short form name of the object being downloaded. For archives it will
contain the name of the package that is being fetched.

<p>
Inside of the single quote is an informative string indicating the progress
of the negotiation phase of the download. Typically it progresses from 
<em>Connecting</> to <em>Waiting for file</> to <em>Downloading</> or
<em>Resuming</>. The final value is the number of bytes downloaded from the
remote site. Once the download begins this is represented as <tt>102/10.2k</>
indicating that 102 bytes have been fetched and 10.2 kilobytes is expected.
The total size is always shown in 4 figure notation to preserve space. After
the size display is a percent meter for the file itself.
The second last element is the instantaneous average speed. This values is 
updated every 5 seconds and reflects the rate of data transfer for that 
period. Finally is shown the estimated transfer time. This is updated
regularly and reflects the time to complete everything at the shown 
transfer rate.

<p> 
The status display updates every half second to provide a constant feedback 
on the download progress while the Get lines scroll back whenever a new
file is started. Since the status display is constantly updated it is
unsuitable for logging to a file, use the <tt>-q</> option to remove the
status display.
</sect>

<!-- ===================================================================== -->
<sect>Dpkg

<p>
APT uses <prgn>dpkg</> for installing the archives and will switch
over to the <prgn>dpkg</> interface once downloading is completed.
<prgn>dpkg</> will also ask a number of questions as it processes the packages
and the packages themselves may also ask several questions. Before each 
question there is usually a description of what it is asking and the
questions are too varied to discuss completely here.
</sect>

</chapt>
                                                                  <!-- }}} -->

</book>