
                              APT User's Guide


-----------------------------------------------------------------------------
                                      
                               Jason Gunthorpe

                              <jgg@debian.org>

                                Version 3.0.1

-----------------------------------------------------------------------------

Copyright © 1998 Jason Gunthorpe

License Notice

    "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 systems, see the file /usr/share/
    common-licenses/GPL for the full license.

Abstract

This document provides an overview of how to use the APT package manager.

-----------------------------------------------------------------------------

Table of 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.2.1. The Extra Package list
        4.2.2. The Packages to Remove
        4.2.3. The New Packages list
        4.2.4. The Kept Back list
        4.2.5. Held Packages warning
        4.2.6. Final summary
    4.3. The Status Display
    4.4. Dpkg

Chapter 1. General

Table of Contents

1.1. Anatomy of the Package System

    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 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.

    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.

Chapter 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/ stable/binary-i386/ Packages
    Get http://llug.sep.bnl.gov/debian/ testing/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)

Chapter 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 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 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.

       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,
          http://deb.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 an 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 testing

     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.

     Please give the components to get
     The components are typically something like: main contrib non-free non-free-firmware

     Components [main contrib non-free non-free-firmware]:

    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 superset 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.

Chapter 4. The Interface

Table of Contents

4.1. Startup
4.2. The Status Report
    4.2.1. The Extra Package list
    4.2.2. The Packages to Remove
    4.2.3. The New Packages list
    4.2.4. The Kept Back list
    4.2.5. Held Packages warning
    4.2.6. Final summary
4.3. The Status Display
4.4. Dpkg

    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. ^[2] 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.

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 --fix-broken 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. ^[3]. 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.

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/ stable/main 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/ 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

    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.


-----------------------------------------------------------------------------

    ^[2] 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.

    ^[3] APT however considers all known dependencies and attempts to prevent
    broken packages

