APT Users Guide
Here is a quick users guide, the html is at
http://www.debian.org/~jgg/deity/guide.html
Jason
APT User's Guide
----------------
Jason Gunthorpe <jgg@debian.org>
$Id: guide.sgml,v 1.3 1998/04/06 23:22:57 jgg Exp $
0.1 Abstract
------------
This document provides an overview of how to use the the APT package
manager.
0.2 Contents
------------
1. General
1.1. Anatomy of the Package System
2. apt-get
3. DSelect
4. The Interface
4.1. The Pre-Checks
4.2. The Status Report
4.3. The Status Display
4.4. Dpkg
0.3. Copyright Notice
-------------------------------------------------------------------------------
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 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 a choices in for such things as 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, mail-crypt is an emacs extension that aids in encrypting
email with PGP. Without PGP installed mail-crypt is useless, so
mail-crypt has a simple dependency on PGP. 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 packages proper name and can only install .deb archives from
a *Source*.
The first 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
Updating package file cache...done
Updating package status cache...done
Checking system integrity...ok
Once updated there are several useful 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 single 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 it's arguments are changed
dist-upgrade
Dist-upgrade is a complete upgrader designed to make simple
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 it's 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'.
-------------------------------------------------------------------------------
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. [1]
[1] As of this writing the non-US distribution has not been created,
the only way to access it is by specifying stable/binary-i386/ at
this prompt and by specifying a URL ending in debian-non-US
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 copyright, 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.
-------------------------------------------------------------------------------
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. The Pre-Checks
--------------------
Before all operations, except update, APT performs a number of checks
on the systems. These are designed to safe guard the operations it is
about to undertake. At any time the full set of checks may be run by
performing `apt-get check'.
# apt-get check
Updating package file cache...done
Updating package status cache...done
Checking system integrity...ok
The first check is to ensure that the archive package lists are
matched to the pre-generated data cache, if they are not then the
cache is automatically refreshed. This may fail if `apt-get update'
has not been run to synchronize with the *Sources*. The next check
verifies that the state of the system matches the cached state and
automatically rebuilds the cached state if they are not synchronized.
This check should never fail and it indicates a serious error if it
ever does.
The final check performs a detailed analysis of the system integrity.
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
Updating package file cache...done
Updating package status cache...done
Checking system integrity...dependency error
You might want to run apt-get -f install' to correct these.
Sorry, but the following packages are broken - this means they have unmet
dependencies:
libdbd-mysql-perl: Depends:perl
xzx: Depends:xlib6
libdbd-msql-perl: Depends:perl
mailpgp: Depends:pgp-i Depends:pgp-us
xdpkg: Depends:python
squake: Depends:quake-lib Depends:quake-lib-stub
debmake: Depends:fileutils
libreadlineg2: Conflicts:libreadline2
ssh: Depends:gmp2 Depends:xlib6g Depends:zlib1g
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. For brevity the version
inter-relationships are omitted.
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.
[1] APT however considers all known dependencies and attempts to
prevent broken packages
The second situation is much less serious than the first because APT
places certain assurances on the order that packages are installed. In
both cases supplying the `-f' option to atp-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.
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 removed, 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. 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.
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 http://ftp.de.debian.org/debian-non-US/ stable/binary-i386/ Packages
Get http://llug.sep.bnl.gov/debian/ frozen/contrib Packages
Get http://llug.sep.bnl.gov/debian/ frozen/main Packages
Get http://ftp.de.debian.org/debian-non-US/ unstable/binary-i386/ Packages
Get http://llug.sep.bnl.gov/debian/ frozen/non-free Packages
11% Get: Packages 'Waiting for file' 0
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
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 thread
and indicates the operation being performed. *Get* indicates that the
file is being downloaded while *Cmp* indicates a fetched file is being
decompressed. Sometimes this section will simply read *Forking* which
means the OS is loading the download module.
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 beings 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.
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 as 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.
-------------------------------------------------------------------------------
0.3 Copyright Notice
--------------------
Copyright © 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.
-------------------------------------------------------------------------------
APT User's Guide
Jason Gunthorpe <jgg@debian.org> - $Id: guide.sgml,v 1.3 1998/04/06
23:22:57 jgg Exp $
--
To UNSUBSCRIBE, email to debian-devel-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: