APT User's Guide
----------------
Jason Gunthorpe <jgg@debian.org>
$Id: guide.sgml,v 1.4 2001/04/10 07:02:55 jgg Exp $
-------------------------------------------------------------------------------
Abstract
--------
This document provides an overview of how to use the the APT package
manager.
Copyright Notice
----------------
Copyright (C) Jason Gunthorpe, 1998.
"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.
For more details, on Debian GNU/Linux systems, see the file
/usr/doc/copyright/GPL for the full license.
-------------------------------------------------------------------------------
Contents
--------
1. General
1.1. Anatomy of the Package System
2. apt-get
3. DSelect
4. The Interface
4.1. Startup
4.2. The Status Report
4.3. The Status Display
4.4. Dpkg
-------------------------------------------------------------------------------
1. General
----------
The APT package currently contains two sections, the APT `dselect'
method and the `apt-get' command line user interface. Both provide a
way to install and remove packages as well as download new packages
from the Internet.
1.1. Anatomy of the Package System
----------------------------------
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.
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.
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.
For instance, mailcrypt is an emacs extension that aids in encrypting
email with GPG. Without GPGP installed mail-crypt 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.
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.
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.
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.
-------------------------------------------------------------------------------
2. apt-get
----------
`apt-get' provides a simple way to install packages from the command
line. Unlike `dpkg', `apt-get' does not understand .deb files, it
works with the package's proper name and can only install .deb
archives from a _Source_.
The first [1] thing that should be done before using `apt-get' is to
fetch the package lists from the _Sources_ so that it knows what
packages are available. This is done with `apt-get update'. For
instance,
# apt-get update
Get http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
Get http://llug.sep.bnl.gov/debian/ frozen/contrib Packages
Reading Package Lists... Done
Building Dependency Tree... Done
Once updated there are several commands that can be used:
upgrade
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. `dselect' or
`apt-get install' can be used to force these packages to install.
install
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.
dist-upgrade
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 `dselect'. Once dist-upgrade has completed then
`dselect' can be used to install any packages that may have been
left out.
It is important to closely look at what dist-upgrade is going to
do, its decisions may sometimes be quite surprising.
`apt-get' has several command line options that are detailed in its
man page, apt-get(8). The most useful option is `-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 `-d' is used the downloaded archives
can be installed by simply running the command that caused them to be
downloaded again without `-d'.
[1] If you are using an http proxy server you must set the http_proxy
environment variable first, see sources.list(5)
-------------------------------------------------------------------------------
3. DSelect
----------
The APT `dselect' method provides the complete APT system with the
`dselect' package selection GUI. `dselect' is used to select the
packages to be installed or removed and APT actually installs them.
To enable the APT method you need to to select [A]ccess in `dselect'
and then choose the APT method. You will be prompted for a set of
_Sources_ which are places to fetch archives from. These can be
remote Internet sites, local Debian mirrors or CDROMs. 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 CDROM 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 CDROM before downloading from
the Internet.
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]:
The _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.
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 frozen non-US
Distribution [stable]:
The distribution refers to the Debian version in the archive, _stable_
refers to the latest released version and _unstable_ refers to the
developmental version. _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.
Please give the components to get
The components are typically something like: main contrib non-free
Components [main contrib non-free]:
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.
Any number of sources can be added, the setup script will continue to
prompt until you have specified all that you want.
Before starting to use `dselect' it is necessary to update the
available list by selecting [U]pdate from the menu. This is a
super-set of `apt-get update' that makes the fetched information
available to `dselect'. [U]pdate must be performed even if `apt-get
update' has been run before.
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.
By default APT will automatically remove the package (.deb) files once
they have been successfully installed. To change this behavior place
`Dselect::clean "prompt";' in /etc/apt/apt.conf.
-------------------------------------------------------------------------------
4. The Interface
----------------
Both that APT `dselect' method and `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. [1] 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.
[1] The `dselect' method actually is a set of wrapper scripts to
`apt-get'. The method actually provides more functionality than is
present in `apt-get' alone.
4.1. Startup
------------
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 `apt-get check'.
# apt-get check
Reading Package Lists... Done
Building Dependency Tree... Done
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.
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 `apt-get' will refuse to
run.
# 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)
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.
There are two ways a system can get into a broken state like this.
The first is caused by `dpkg' missing some subtle relationships
between packages when performing upgrades. [1]. 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.
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 `-f' option to `apt-get' will cause APT to
deduce a possible solution to the problem and then continue on. The
APT `dselect' method always supplies the `-f' option to allow for easy
continuation of failed maintainer scripts.
However, if the `-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.
[1] APT however considers all known dependencies and attempts to prevent
broken packages
4.2. The Status Report
----------------------
Before proceeding `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 `-f' option and any
other relevant activities to the command being executed.
4.2.1. The Extra Package list
-----------------------------
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
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 `install' command. The listed
packages are often the result of an Auto Install.
4.2.2. The Packages to Remove
-----------------------------
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
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 `-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.
4.2.3. The New Packages list
----------------------------
The following NEW packages will installed:
zlib1g xlib6g perl-base libgdbmg1 quake-lib gmp2 pgp-i python-base
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.
4.2.4. The Kept Back list
-------------------------
The following packages have been kept back
compface man-db tetex-base msql libpaper svgalib1
gs snmp arena lynx xpat2 groff xscreensaver
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 `apt-get install' or
by using `dselect' to resolve their problems.
4.2.5. Held Packages warning
----------------------------
The following held packages will be changed:
cvs
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.
4.2.6. Final summary
--------------------
Finally, APT will print out a summary of all the changes that will
occur.
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.
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.
Some other reports can be generated by using the -u option to show
packages to upgrade, they are similar to the previous examples.
4.3. The Status Display
-----------------------
During the download of archives and package files APT prints out a
series of status messages.
# 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/ frozen/contrib Packages
Hit http://llug.sep.bnl.gov/debian/ frozen/main Packages
Get:4 http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
Get:5 http://llug.sep.bnl.gov/debian/ frozen/non-free Packages
11% [5 frozen/non-free `Waiting for file' 0/32.1k 0%] 2203b/s 1m52s
The lines starting with _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 `apt-get update' estimates the percent done
which causes some inaccuracies.
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 _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.
Inside of the single quote is an informative string indicating the
progress of the negotiation phase of the download. Typically it
progresses from _Connecting_ to _Waiting for file_ to _Downloading_ or
_Resuming_. The final value is the number of bytes downloaded from
the remote site. Once the download begins this is represented as
`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.
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
`-q' option to remove the status display.
4.4. Dpkg
---------
APT uses `dpkg' for installing the archives and will switch over to
the `dpkg' interface once downloading is completed. `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.
-------------------------------------------------------------------------------
APT User's Guide
Jason Gunthorpe <jgg@debian.org>
$Id: guide.sgml,v 1.4 2001/04/10 07:02:55 jgg Exp $