trunk/apt-howto/apt-howto.en.sgml

<!doctype debiandoc system>
<debiandoc>

<book>

<title>APT HOWTO (Obsolete Documentation)</title>

<author>
<name>Gustavo Noronha Silva</name> <email>kov@debian.org</email>
</author>

<version>1.8.11 - August 2005</version>

<abstract>
This document intends to provide the user with a good understanding
of the workings of the Debian package management utility, APT.  Its
goal is to make life easier for new Debian users and to help those
who wish to deepen their understanding of the administration of this
system.  It was created for the Debian project in order to help
improve the support available for users of this distribution.
</abstract>

<copyright>
<copyrightsummary>
Copyright &copy; 2001, 2002, 2003, 2004 Gustavo Noronha Silva
</copyrightsummary>
<p>
This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
</p>

<p>
This is distributed in the hope that it will be useful, but without
any warranty; without even the implied warranty of merchantability or
fitness for a particular purpose. See the GNU General Public License
for more details.
</p>

<p>
A copy of the GNU General Public License is available as
/usr/share/common-licenses/GPL in the Debian GNU/Linux distribution or
on the World Wide Web at the GNU General Public Licence. You can also
obtain it by writing to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA.
</p>
</copyright>

<toc>

<chapt>Introduction
<p>
In the beginning there was the .tar.gz.  Users had to compile each program
that they wanted to use on their GNU/Linux systems.  When Debian was created,
it was deemed necessary that the system include a method of managing the
packages installed on the machine.  The name <prgn>dpkg</prgn> was given to
this system.  Thus the famous `package' first came into being on GNU/Linux,
a while before Red Hat decided to create their own `rpm' system.
<p>
A new dilemma quickly took hold of the minds of the makers of
GNU/Linux.  They needed a rapid, practical, and efficient way to install
packages that would manage dependencies automatically and take care of
their configuration files while upgrading.  Here again, Debian led the way
and gave birth to APT, the Advanced Packaging Tool, which has since been
ported by Conectiva for use with rpm and has been adopted by some other
distributions.
<p>
This manual makes no attempt to address apt-rpm, as the Conectiva port of
APT is known, but "patches" to this document which do so would be welcome.
<p>
This manual is based on the next Debian release, <tt>Sarge</tt>.
</chapt>

<chapt id="basico">Basic Configuration

<sect id="sources.list">The /etc/apt/sources.list file
<p>
As part of its operation, APT uses a file that lists the 'sources' from
which packages can be obtained.  This file is <tt>/etc/apt/sources.list</tt>.
<p>
The entries in this file normally follow this format:

<p>
<example>
deb http://host/debian distribution section1 section2 section3
deb-src http://host/debian distribution section1 section2 section3
</example>

<p>
Of course, the above entries are fictitious and should not be used.  The
first word on each line, <tt>deb</tt> or <tt>deb-src</tt>, indicates the type
of archive: whether it contains binary packages (<tt>deb</tt>), that is, the
pre-compiled packages that we normally use, or source packages
(<tt>deb-src</tt>), which are the original program sources plus the Debian
control file (<tt>.dsc</tt>) and the <tt>diff.gz</tt> containing the
changes needed for `debianizing' the program.
<p>
We usually find the following in the default Debian sources.list:
<p>
<example>
# See sources.list(5) for more information, especially
# Remember that you can only use http, ftp or file URIs
# CDROMs are managed through the apt-cdrom tool.
deb http://http.us.debian.org/debian stable main contrib non-free
deb http://non-us.debian.org/debian-non-US stable/non-US main contrib non-free
deb http://security.debian.org stable/updates main contrib non-free

# Uncomment if you want the apt-get source function to work
#deb-src http://http.us.debian.org/debian stable main contrib non-free
#deb-src http://non-us.debian.org/debian-non-US stable/non-US main contrib non-free
</example>

<p>
These are the lines needed by a basic Debian install.  The first <tt>deb</tt>
line points to the official archive, the second to the non-US archive and
the third to the archive of Debian security updates.
<p>
The two last lines are commented out (with a `#' in front), so apt-get will
ignore them.  These are <tt>deb-src</tt> lines, that is, they point to
Debian source packages.  If you often download program sources for testing or
recompiling, uncomment them.
<p>
The <tt>/etc/apt/sources.list</tt> file can contain several types of lines.
APT knows how to deal with archives of types <tt>http</tt>, <tt>ftp</tt>,
<tt>file</tt> (local files, e.g., a directory containing a mounted ISO9660
filesystem) and <tt>ssh</tt>, that I know of.
<p>
Do not forget to run <tt>apt-get update</tt> after modifying the
<tt>/etc/apt/sources.list</tt> file. You must do this to let
APT obtain the package lists from the sources you specified.
</sect>

<sect id="dpkg-scanpackages">How to use APT locally
<p>
Sometimes you have lots of packages .deb that you would like to use
APT to install so that the dependencies would be automatically 
solved.
<p>
To do that create a directory and put the .debs you want to index
in it . For example:
<p>
<example>
# mkdir /root/debs
</example>
<p>
You may modify the definitions set on the package's control file
directly for your repository using an <tt>override</tt> file.
Inside this file you may want to define some options to override
the ones that come with the package. It looks like follows:
<p>
<example>
package priority section
</example>
<p>
package is the name of the package, priority is low, medium or
high and section is the section to which it belongs. The file
name does not matter, you'll have to pass it as an argument for
<prgn>dpkg-scanpackages</prgn> later. If you do not want to
write an <tt>override</tt> file, just use <file>/dev/null</file>.
when calling <prgn>dpkg-scanpackages</prgn>.
<p>
Still in the /root directory do:
<p>
<example>
# dpkg-scanpackages debs <var>file</var> | gzip &gt; debs/Packages.gz
</example>
<p>
In the above line, <var>file</var> is the <tt>override</tt> file, 
the command generates a file <file>Packages.gz</file> that contains 
various information about the packages, which are used by APT. To 
use the packages, finally, add:
<p>
<example>
deb file:/root debs/
</example>
<p>
After that just use the APT commands as usual. You may also generate
a sources repository. To do that use the same procedure,
but remember that you need to have the files <tt>.orig.tar.gz</tt>,
<tt>.dsc</tt> and <tt>.diff.gz</tt> in the directory and you
have to use <tt>Sources.gz</tt> instead of <tt>Packages.gz</tt>. 
The program used is also different. It is <prgn>dpkg-scansources</prgn>. 
The command line will look like this:
<p>
<example>
# dpkg-scansources debs | gzip &gt; debs/Sources.gz
</example>
<p>
Notice that <prgn>dpkg-scansources</prgn> doesn't need an 
<tt>override</tt> file. The sources.list's line is:
<p>
<example>
deb-src file:/root debs/
</example>
</sect>

<sect id="netselect">Deciding which mirror is the best to include in the sources.list file: netselect, netselect-apt
<p>
A very frequent doubt, mainly among the newest users is: "which Debian
mirror to include in <tt>sources.list</tt>?". There are many ways
to decide which mirror. The experts probably have a script that
measures the ping time through the several mirrors. But there's a
program that does this for us: <strong>netselect</strong>.
<p>
To install netselect, as usual:
<p>
<example>
# apt-get install netselect
</example>
<p>
Executing it without parameters shows the help. Executing it with a
space-separated list of hosts (mirrors), it will return a score and
one of the hosts. This score takes in consideration the estimated ping
time and the hops (hosts by which a network query will pass by to reach
the destination) number and is inversely proportional to the estimated
download speed (so, the lower, the better). The returned host is the
one that had the lowest score (the full list of scores can be seen adding
the -vv option). See this example: <p>
<example>
# netselect ftp.debian.org http.us.debian.org ftp.at.debian.org download.unesp.br ftp.debian.org.br
  365 ftp.debian.org.br
#
</example>
<p>
This means that, from the mirrors included as parameters to netselect,
<tt>ftp.debian.org.br</tt> was the best, with an score of 365. (Attention!!
As it was done on my computer and the network topography is extremely
different depending on the contact point, this value is not necessarily
the right speed in other computers).
<p>
Now, just put the fastest mirror found by netselect in the
<tt>/etc/apt/sources.list</tt> file (see <ref id="sources.list">) and
follow the tips in <ref id="apt-get">.
<p> <strong>Note:</strong> the list of mirrors may always be found in the
file <url id="http://www.debian.org/mirror/mirrors_full"
name="http://www.debian.org/mirror/mirrors_full">.
<p>
Beginning with the 0.3.ds1 version, the netselect source package includes the
<strong>netselect-apt</strong> binary package, which makes the process
above automatic. Just enter the distribution tree as parameter (the
default is stable) and the <tt>sources.list</tt> file will be
generated with the best main and non-US mirrors and will be saved
under the current directory. The following example generates a
sources.list of the stable distribution:
<p>
<example>
# ls sources.list
ls: sources.list: File or directory not found
# netselect-apt stable
(...)
# ls -l sources.list
sources.list
#
</example>
<p>
<strong>Remember:</strong> the <tt>sources.list</tt> file is generated
under the current directory, and must be moved to the <tt>/etc/apt</tt>
directory.
<p>
Then, follow the tips in <ref id="apt-get">.
</sect>

<sect id="cdrom">Adding a CD-ROM to the sources.list file
<p>
If you'd rather use your CD-ROM for installing packages or updating
your system automatically with APT, you can put it in your
<tt>sources.list</tt>.  To do so, you can use the <prgn>apt-cdrom</prgn>
program like this:

<p>
<example>
# apt-cdrom add
</example>

<p>
with the Debian CD-ROM in the drive.  It will mount the CD-ROM, and
if it's a valid Debian CD it will look for package information on the
disk.  If your CD-ROM configuration is a little unusual, you
can also use the following options:

<p>
<example>
-h           - program help
-d directory - CD-ROM mount point
-r           - Rename a recognized CD-ROM
-m           - No mounting
-f           - Fast mode, don't check package files
-a           - Thorough scan mode
</example>

<p>
For example:

<p>
<example>
# apt-cdrom -d /home/kov/mycdrom add
</example>

<p>
You can also identify a CD-ROM, without adding it to your list:

<p>
<example>
# apt-cdrom ident
</example>

<p>
Note that this program only works if your CD-ROM is properly
configured in your system's <tt>/etc/fstab</tt>.
</sect>

</chapt>

<chapt id="apt-get">Managing packages
<sect id="update">Updating the list of available packages
<p>
The packaging system uses a private database to keep track of which
packages are installed, which are not installed and which are available for
installation.  The <prgn>apt-get</prgn> program uses this database to
find out how to install packages requested by the user and to find out
which additional packages are needed in order for a selected package to
work properly.
<p>
To update this list, you would use the command <prgn>apt-get update</prgn>.
This command looks for the package lists in the archives found in
<tt>/etc/apt/sources.list</tt>; see <ref id="sources.list"> for more
information about this file.
<p>
It's a good idea to run this command regularly to keep yourself and your
system informed about possible package updates, particularly security
updates.
</sect>

<sect id="install">Installing packages
<p>
Finally, the process you've all been waiting for!  With your sources.list
ready and your list of available packages up to date, all you have to do is
run <tt>apt-get</tt> to get your desired package installed.  For example,
you can run:

<p>
<example>
# apt-get install xchat
</example>

<p>
APT will search it's database for the most recent version of this package and
will retrieve it from the corresponding archive as specified in
<tt>sources.list</tt>.  In the event that this package depends on another --
as is the case here -- APT will check the dependencies and install the
needed packages.  See this example:

<p>
<example>
# apt-get install nautilus
Reading Package Lists... Done
Building Dependency Tree... Done
The following extra packages will be installed:
  bonobo libmedusa0 libnautilus0 
The following NEW packages will be installed:
  bonobo libmedusa0 libnautilus0 nautilus 
0 packages upgraded, 4 newly installed, 0 to remove and 1  not upgraded.
Need to get 8329kB of archives. After unpacking 17.2MB will be used.
Do you want to continue? [Y/n] 
</example>

<p>
The package <package>nautilus</package> depends on the shared libraries cited,
therefore APT will get them from the archive.  If you had
specified the names of these libraries on the <tt>apt-get</tt> command line,
APT would not have asked if you wanted to continue; it would automatically
accept that you wanted to install all of those packages.
<p>
This means that APT only asks for confirmation when it needs to install
packages which weren't specified on the command line.
<p>
The following options to apt-get may be useful:

<p>
<example>
-h  This help text.
-d  Download only - do NOT install or unpack archives
-f  Attempt to continue if the integrity check fails
-s  No-act. Perform ordering simulation
-y  Assume Yes to all queries and do not prompt
-u  Show a list of upgraded packages as well
</example>

<p>
Multiple packages may be selected for installation in one line.
Files downloaded from the network are placed in the directory
<tt>/var/cache/apt/archives</tt> for later installation.
<p>
You can specify packages to be removed on the same command line, as well.
Just put a '-' immediately after the name of the package to be removed, like
this:

<p>
<example>
# apt-get install nautilus gnome-panel-       
Reading Package Lists... Done
Building Dependency Tree... Done
The following extra packages will be installed:
  bonobo libmedusa0 libnautilus0 
The following packages will be REMOVED:
  gnome-applets gnome-panel gnome-panel-data gnome-session 
The following NEW packages will be installed:
  bonobo libmedusa0 libnautilus0 nautilus 
0 packages upgraded, 4 newly installed, 4 to remove and 1  not upgraded.
Need to get 8329kB of archives. After unpacking 2594kB will be used.
Do you want to continue? [Y/n] 
</example>

<p>
See section <ref id="remove"> for more details on package removal.
<p>
If you somehow damage an installed package, or simply want the files of a
package to be reinstalled with the newest version that is available,
you can use the <tt>--reinstall</tt> option like so:

<p>
<example>
# apt-get --reinstall install gdm
Reading Package Lists... Done
Building Dependency Tree... Done
0 packages upgraded, 0 newly installed, 1 reinstalled, 0 to remove and 1  not upgraded.
Need to get 0B/182kB of archives. After unpacking 0B will be used.
Do you want to continue? [Y/n]
</example>
</sect>

<sect id="remove">Removing packages
<p>
If you no longer want to use a package, you can remove it from your system
using APT.  To do this just type: <tt>apt-get remove package</tt>.
For example:

<p>
<example>
# apt-get remove gnome-panel
Reading Package Lists... Done
Building Dependency Tree... Done
The following packages will be REMOVED:
  gnome-applets gnome-panel gnome-panel-data gnome-session 
0 packages upgraded, 0 newly installed, 4 to remove and 1  not upgraded.
Need to get 0B of archives. After unpacking 14.6MB will be freed.
Do you want to continue? [Y/n] 
</example>

<p>
As you can see in the above example, APT also takes care of removing
packages which depend on the package you have asked to remove.  There is no
way to remove a package using APT without also removing those packages that
depend on it.
<p>
Running <prgn>apt-get</prgn> as above will cause the packages to be removed
but their configuration files, if any, will remain intact on the system. 
For a complete removal of the package, run:

<p>
<example>
# apt-get --purge remove gnome-panel
Reading Package Lists... Done
Building Dependency Tree... Done
The following packages will be REMOVED:
  gnome-applets* gnome-panel* gnome-panel-data* gnome-session* 
0 packages upgraded, 0 newly installed, 4 to remove and 1  not upgraded.
Need to get 0B of archives. After unpacking 14.6MB will be freed.
Do you want to continue? [Y/n] 
</example>

<p>
Note the '*' after the names.  This indicates that the configuration
files for each of these packages will also be removed.
<p>
Just as in the case of the <tt>install</tt> method, you can use a symbol
with <tt>remove</tt> to invert the meaning for a particular package.  In the
case of removing, if you add a <tt>'+'</tt> right after the package name,
the package will be installed instead of being removed.

<p>
<example>
# apt-get --purge remove gnome-panel nautilus+
Reading Package Lists... Done
Building Dependency Tree... Done
The following extra packages will be installed:
  bonobo libmedusa0 libnautilus0 nautilus 
The following packages will be REMOVED:
  gnome-applets* gnome-panel* gnome-panel-data* gnome-session* 
The following NEW packages will be installed:
  bonobo libmedusa0 libnautilus0 nautilus 
0 packages upgraded, 4 newly installed, 4 to remove and 1  not upgraded.
Need to get 8329kB of archives. After unpacking 2594kB will be used.
Do you want to continue? [Y/n] 
</example>

<p>
Note that <prgn>apt-get</prgn> lists the extra packages which will be
installed (that is, the packages whose installation is needed for the proper
functioning of the package whose installation has been requested), those
which will be removed, and those which will be installed (including the
extra packages again).
</sect>

<sect id="upgrade">Upgrading packages
<p>
Package upgrades are a great success of the APT system.  They can be
achieved with a single command: <tt>apt-get upgrade</tt>.  You can use
this command to upgrade packages within the same distribution, as well
as to upgrade to a new distribution, although for the latter the command
<tt>apt-get dist-upgrade</tt> is preferred; see section
<ref id="dist-upgrade"> for more details.
<p>
It's useful to run this command with the <tt>-u</tt> option.  This option
causes APT to show the complete list of packages which will be upgraded. 
Without it, you'll be upgrading blindly.  APT will download the latest 
versions of each package and will install them in the proper order.  It's
important to always run <tt>apt-get update</tt> before you try this.  See
section <ref id="update">.  Look at this example:

<p>
<example>
# apt-get -u upgrade
Reading Package Lists... Done
Building Dependency Tree... Done
The following packages have been kept back
  cpp gcc lilo 
The following packages will be upgraded
  adduser ae apt autoconf debhelper dpkg-dev esound esound-common ftp indent
  ipchains isapnptools libaudiofile-dev libaudiofile0 libesd0 libesd0-dev
  libgtk1.2 libgtk1.2-dev liblockfile1 libnewt0 liborbit-dev liborbit0
  libstdc++2.10-glibc2.2 libtiff3g libtiff3g-dev modconf orbit procps psmisc 
29 packages upgraded, 0 newly installed, 0 to remove and 3 not upgraded.
Need to get 5055B/5055kB of archives. After unpacking 1161kB will be used.
Do you want to continue? [Y/n] 
</example>

<p>
The process is very simple.  Note that in the first few lines,
<tt>apt-get</tt> says that some packages were <tt>kept back</tt>.  This
means that there are new versions of these packages which will not be
installed for some reason.  Possible reasons are broken dependencies
(a package on which it depends doesn't have a version available for
download) or new dependencies (the package has come to depend on new
packages since the last version).
<p>
There's no clean solution for this first case.  For the second case, it's
sufficient to run <tt>apt-get install</tt> for the specific package in
question, as this will download the dependencies.  An even cleaner solution 
is to use <tt>dist-upgrade</tt>.  See section <ref id="dist-upgrade">.
</sect>

<sect id="dist-upgrade">Upgrading to a new release
<p>
This feature of APT allows you to upgrade an entire Debian system at once,
either through the Internet or from a new CD (purchased or downloaded as
an ISO image).
<p>
It is also used when changes are made to the relationships between installed
packages.  With <tt>apt-get upgrade</tt>, these packages would be kept
untouched (<tt>kept back</tt>).
<p>
For example, suppose that you're using revision 0 of the stable version of
Debian and you buy a CD with revision 3. You can use APT to upgrade your
system from this new CD. To do this, use <prgn>apt-cdrom</prgn>
(see section <ref id="cdrom">) to add the CD to your
<tt>/etc/apt/sources.list</tt> and run <tt>apt-get dist-upgrade</tt>.
<p>
It's important to note that APT always looks for the most recent
versions of packages.  Therefore, if your <tt>/etc/apt/sources.list</tt>
were to list an archive that had a more recent version of a package than
the version on the CD, APT would download the package from there.
<p>
In the example shown in section <ref id="upgrade">, we saw that
some packages were <tt>kept back</tt>.  We'll solve this problem now
with the <tt>dist-upgrade</tt> method:

<p>
<example>
# apt-get -u dist-upgrade
Reading Package Lists... Done
Building Dependency Tree... Done
Calculating Upgrade... Done
The following NEW packages will be installed:
  cpp-2.95 cron exim gcc-2.95 libident libopenldap-runtime libopenldap1
  libpcre2 logrotate mailx 
The following packages have been kept back
  lilo 
The following packages will be upgraded
  adduser ae apt autoconf cpp debhelper dpkg-dev esound esound-common ftp gcc
  indent ipchains isapnptools libaudiofile-dev libaudiofile0 libesd0
  libesd0-dev libgtk1.2 libgtk1.2-dev liblockfile1 libnewt0 liborbit-dev
  liborbit0 libstdc++2.10-glibc2.2 libtiff3g libtiff3g-dev modconf orbit
  procps psmisc 
31 packages upgraded, 10 newly installed, 0 to remove and 1 not upgraded.
Need to get 0B/7098kB of archives. After unpacking 3118kB will be used.
Do you want to continue? [Y/n]
</example>

<p>
Note now that the packages will be upgraded, and new packages will also be
installed (the new dependencies of the packages).  Note too that lilo is
still being <tt>kept back</tt>. It probably has a more serious problem
than a new dependency.  We can find out by running:

<p>
<example>
# apt-get -u install lilo
Reading Package Lists... Done
Building Dependency Tree... Done
The following extra packages will be installed:
  cron debconf exim libident libopenldap-runtime libopenldap1 libpcre2
  logrotate mailx 
The following packages will be REMOVED:
  debconf-tiny 
The following NEW packages will be installed:
  cron debconf exim libident libopenldap-runtime libopenldap1 libpcre2
  logrotate mailx 
The following packages will be upgraded
  lilo 
1 packages upgraded, 9 newly installed, 1 to remove and 31 not upgraded.
Need to get 225kB/1179kB of archives. After unpacking 2659kB will be used.
Do you want to continue? [Y/n]
</example>

<p>
As noted in the above, lilo has a new conflict with the package
<package>debconf-tiny</package>, which means it couldn't be installed
(or upgraded) without removing debconf-tiny.
<p>
To know what's keeping or removing a package you may use:

<p>
<example>
# apt-get -o Debug::pkgProblemResolver=yes dist-upgrade
Reading Package Lists... Done
Building Dependency Tree... Done
Calculating Upgrade... Starting
Starting 2
Investigating python1.5
Package python1.5 has broken dep on python1.5-base
  Considering python1.5-base 0 as a solution to python1.5 0
  Holding Back python1.5 rather than change python1.5-base
Investigating python1.5-dev
Package python1.5-dev has broken dep on python1.5
  Considering python1.5 0 as a solution to python1.5-dev 0
  Holding Back python1.5-dev rather than change python1.5
 Try to Re-Instate python1.5-dev
Done
Done
The following packages have been kept back
  gs python1.5-dev 
0 packages upgraded, 0 newly installed, 0 to remove and 2  not upgraded.
</example>

<p>
This way, it's easy to notice that the python1.5-dev package cannot
be installed because of an unsatisfied dependency: python1.5.

</sect>

<sect id="clean">Removing unused package files: apt-get clean and autoclean
<p>
When you install a package APT retrieves the needed files from the hosts 
listed in /etc/apt/sources.list, stores them in a local repository
(<file>/var/cache/apt/archives/</file>), and then proceeds with
installation, see <ref id="install">.
<p>
In time the local repository can grow and occupy a lot of disk space.
Fortunately, APT provides tools for managing its local repository:
<prgn>apt-get</prgn>'s <tt>clean</tt> and <tt>autoclean</tt> methods.
<p>
<prgn>apt-get clean</prgn> removes everything except lock files from
<file>/var/cache/apt/archives/</file> and
<file>/var/cache/apt/archives/partial/</file>. Thus, if you need to
reinstall a package APT should retrieve it again.
<p>
<prgn>apt-get autoclean</prgn> removes only package files that can
no longer be downloaded. 
<p>
The following example show how apt-get autoclean works:

<p>
<example>
# ls /var/cache/apt/archives/logrotate* /var/cache/apt/archives/gpm*
logrotate_3.5.9-7_i386.deb
logrotate_3.5.9-8_i386.deb
gpm_1.19.6-11_i386.deb
</example>

<p>
In /var/cache/apt/archives there are two files for the
package <package>logrotate</package> and one for the package
<package>gpm</package>.

<p>
<example>
# apt-show-versions -p logrotate
logrotate/stable uptodate 3.5.9-8
# apt-show-versions -p gpm
gpm/stable upgradeable from 1.19.6-11 to 1.19.6-12
</example>

<p>
<prgn>apt-show-versions</prgn> shows that
<file>logrotate_3.5.9-8_i386.deb</file> provides the up to date version
of <package>logrotate</package>, so
<file>logrotate_3.5.9-7_i386.deb</file> is useless. Also
<file>gpm_1.19.6-11_i386.deb</file> is useless because a more recent
version of the package can be retrieved.

<p>
<example>
# apt-get autoclean
Reading Package Lists... Done
Building Dependency Tree... Done
Del gpm 1.19.6-11 [145kB]
Del logrotate 3.5.9-7 [26.5kB]
</example>

<p>Finally, <tt>apt-get autoclean</tt> removes only the old files.
See <ref id="apt-show-versions"> for more information on
apt-show-versions.
</sect>

<sect id="dselect-upgrade">Using APT with dselect
<p>
<prgn>dselect</prgn> is a program that helps users select Debian packages
for installation.  It's considered somewhat complicated and rather boring,
but with practice you can get the hang of its console-based ncurses
interface.
<p>
One feature of dselect is that it knows how to make use of the capacity
Debian packages have for "recommending" and "suggesting" other packages
for installation.  To use the program, run <tt>`dselect'</tt> as root. 
Choose 'apt' as your access method.  This isn't truly necessary, but if
you're not using a CD ROM and you want to download packages from the
Internet, it's the best way to use dselect.
<p>
To gain a better understanding of dselect's usage, read the dselect
documentation found on the Debian page 
<url id="http://www.debian.org/doc/ddp" name="http://www.debian.org/doc/ddp">.
<p>
After making your selections with dselect, use:

<p>
<example>
# apt-get -u dselect-upgrade
</example>

<p>
as in the example below:

<p>
<example>
# apt-get -u dselect-upgrade
Reading Package Lists... Done
Building Dependency Tree... Done
The following packages will be REMOVED:
  lbxproxy 
The following NEW packages will be installed:
  bonobo console-tools-libs cpp-3.0 enscript expat fingerd gcc-3.0
  gcc-3.0-base icepref klogd libdigest-md5-perl libfnlib0 libft-perl
  libgc5-dev libgcc300 libhtml-clean-perl libltdl0-dev libsasl-modules
  libstdc++3.0 metamail nethack proftpd-doc psfontmgr python-newt talk tidy
  util-linux-locales vacation xbill xplanet-images 
The following packages will be upgraded
  debian-policy 
1 packages upgraded, 30 newly installed, 1 to remove and 0  not upgraded.
Need to get 7140kB of archives. After unpacking 16.3MB will be used.
Do you want to continue? [Y/n]
</example>

<p>
Compare with what we see when running apt-get dist-upgrade on the same
system:

<p>
<example>
# apt-get -u dist-upgrade   
Reading Package Lists... Done
Building Dependency Tree... Done
Calculating Upgrade... Done
The following packages will be upgraded
  debian-policy 
1 packages upgraded, 0 newly installed, 0 to remove and 0  not upgraded.
Need to get 421kB of archives. After unpacking 25.6kB will be freed.
Do you want to continue? [Y/n]
</example>

<p>
Note that many of the packages from above are being installed because other
packages "suggested" or "recommended" them.  Others are being installed or
removed (in the case of lbxproxy, for example) per the choices we made
while navigating through dselect's package listing.  Dselect can be a powerful
tool when used in conjunction with APT.
</sect>

<sect id="default-version">How to keep a mixed system
<p>
People are sometimes interested in using one of the Debian
versions as its main system distribution and one or more packages
from another branch.
<p>
To set up what is your main version of Debian you should edit the
<file>/etc/apt/apt.conf</file> (it does not usually exist, create it
if you don't have one) to contain the following line:
<p>
<example>
APT::Default-Release "<var>version</var>";
</example>
<p>
Where <var>version</var> is the version of Debian you want to
use as the main distribution. The versions you can use are 
<tt>stable</tt>, <tt>testing</tt> and <tt>unstable</tt>.
To install packages from another version, then, you must 
use APT in the following way:

<p>
<example>
# apt-get -t <var>distribution</var> install <var>package</var>
</example>
<p>

For that to work, though, you need at least one APT source line
in your <file>/etc/apt/sources.list</file> for the distribution
you want the package from, and the package must exist on that
source.
<p>
You can also request a specific version of a package using the
following sintax:

<example>
# apt-get install <var>package</var>=<var>version</var>
</example>

For example, the line below will install version <tt>2.2.4-1</tt>
of the <package>nautilus</package> package.:

<example>
# apt-get install nautilus=2.2.4-1
</example>

<p>
<em>IMPORTANT</em>: the `unstable' version of Debian is the version to
which the newest versions of Debian packages are uploaded first.  This
distribution sees all of the changes that packages go through, both
small ones and more drastic ones which affect many packages or the whole
system.  For this reason, this version of the distribution should
<em>not</em> be used by inexperienced users or by those who need proven
stability.
<p>
The `testing' distribution is not necessarily better than `unstable',
because it does not receive security updates quickly. For servers
and other production systems stable should always be used.
</sect>

<sect id="apt-show-versions">How to upgrade packages from specific versions of Debian
<p>
<prgn>apt-show-versions</prgn> provides a safe way for users of mixed
distributions to upgrade their systems without getting more of the
less-stable distribution than they had in mind.  For instance, it is
possible to upgrade just your unstable packages by running after
having installed the <package>apt-show-versions</package> package:
<p>
<example>
# apt-get install `apt-show-versions -u -b | grep unstable | cut -d ' ' -f 1`
</example>
</sect>

<sect id="pin">How to keep specific versions of packages installed (complex)
<p>
You may have occasion to modify something in a package and don't have
time or don't want to port those changes to a new version of the
program.  Or, for instance, you may have just upgraded your Debian
distribution to 3.0, but want to continue with the version of a certain
package from Debian 2.2.  You can "pin" the version you have installed
so that it will not be upgraded.
<p>
Using this resource is simple.  You just need to edit the file
<tt>/etc/apt/preferences</tt>.
<p>
The format is simple:
<p>
<example>
Package: &lt;package&gt;
Pin: &lt;pin definition&gt;
Pin-Priority: &lt;pin's priority&gt;
</example>
<p>
Each entry must be separated from any other entries by a blank 
line. For example, to keep package <package>sylpheed</package> that I
have modified to use "reply-to-list" at version 0.4.99, I add:
<p>
<example>
Package: sylpheed
Pin: version 0.4.99*
</example>
<p>
Note that I used an <tt>*</tt> (asterisk).  This is a "wildcard"; it say
that I want that this "pin" to be valid for all versions beginning with
0.4.99.  This is because Debian versions its packages with a "Debian
revision" and I don't want to avoid the installation of these revisions.
So, for instance, versions 0.4.99-1 and 0.4.99-10 will be installed as
soon as they are made available. Note that if you modified the package
you won't want to do things this way.
<p>
The pin priority helps determine whether a package matching the "Packages:"
and "Pin:" lines will be installed, with higher priorities making it more
likely that a matching package will be installed.  You can read
<manref name="apt_preferences" section="7"> for a thorough discussion of
priorities, but a few examples should give the basic idea.  The following
describes the effect of setting the priority field to different values in
the sylpheed example above.
</p>
<p>
<taglist>
<tag>1001</tag>
<item>
 Sylpheed version 0.4.99 will never be replaced by apt.  If available,
apt will install version 0.4.99 even if it would replace an installed
package with a higher version.  Only packages of priority greater than
1000 will ever downgrade an existing package.
</item>
<tag>1000</tag>
<item>
The effect is the same as priority 1001, except that apt will refuse
to downgrade an installed version to 0.4.99
</item>
<tag>990</tag>
<item>
Version 0.4.99 will be replaced only by a higher version available
from a release designated as preferred using the
"APT::Default-Release" variable (see <ref id="default-version">,
above).
</item>
<tag>500</tag>
<item>
Any version higher than 0.4.99 of sylpheed which is available from any
release will take preference over version 0.4.99, but 0.4.99 will
still be preferred to a lower version.
</item>
<tag>100</tag>
<item>
Higher versions of sylpheed available from any release will take
preference over version 0.4.99, as will any installed higher version
of slypheed; so 0.4.99 will be installed only if no version is
installed already. This is the priority of installed packages.
</item>
<tag>-1</tag>
<item>
Negative priorities are allowed as well, and prevent 0.4.99 from ever
being installed.
</item>
</taglist>
<p>
A pin can be specified on a package's <tt>version</tt>, <tt>release</tt>
or <tt>origin</tt>.
<p>
Pinning on a <tt>version</tt>, as we have seen, supports literal
version numbers as well as wildcards to specify several
versions at one time.
<!-- what's available?  standard shell globs?  ?*[]   or more? -->
<p>
Option <tt>release</tt> depends on the Release file from an APT
repository or from a CD.  This option may be of no use at all if you're
using package repositories that don't provide this file.  You may see
the contents of the Release files that you have on
<tt>/var/lib/apt/lists/</tt>.  The parameters for a release are:
<tt>a</tt> (archive), <tt>c</tt> (components), <tt>v</tt> (version),
<tt>o</tt> (origin) and <tt>l</tt> (label).
<p>
An example:
<p>
<example>
Package: *
Pin: release v=2.2*,a=stable,c=main,o=Debian,l=Debian
Pin-Priority: 1001
</example>
<p>
In this example, we chose version 2.2* of Debian (which can be 2.2r2,
2.2r3 -- this accommodates "point releases" that typically include
security fixes and other very important updates), the <tt>stable</tt>
repository, section <tt>main</tt> (as opposed to <tt>contrib</tt> or
<tt>non-free</tt>) and origin and label Debian.  Origin (o=) defines who
produced that Release file, the label (l=) defines the name of the
distribution: Debian for Debian itself and Progeny for Progeny, for
example.  A sample Release file:
<p>
<example>
$ cat /var/lib/apt/lists/ftp.debian.org.br_debian_dists_potato_main_binary-i386_Release
Archive: stable
Version: 2.2r3
Component: main
Origin: Debian
Label: Debian
Architecture: i386
</example>
</sect>
</chapt>

<chapt id="helpers">Very useful helpers
<sect id="equivs">How to install locally compiled packages: equivs
<p>
Sometimes, people want to use a specific version of a program
available only on source code, with no Debian package. But the
packaging system can be a trouble when doing this. Suppose
you want to compile a new version of your email server. All
is fine, but many packages in Debian depend on an MTA (Mail 
Transport Agent). Since you installed something you compiled 
by yourself, the packaging system doesn't know about it.
<p>
That's where <package>equivs</package> enters the scene. To use it,
install the package with that name. Equivs creates an empty package
that fullfills dependencies, making the package system believe that
the dependencies are satisfied.
<p>
Before we begin, it is good to remind you that there are safer
ways of compiling a program which is already packaged for Debian
with different options, and that one should not use equivs to
replace dependencies if you don't know what you are doing.
See section <ref id="sourcehandling"> for more information.
<p>
Let's continue with the MTA example, you just installed your
new compiled <prgn>postfix</prgn> and goes on for installing
<package>mutt</package>. Suddenly you discover that
<package>mutt</package> wants to install another MTA. But you
already have yours.
<p>
Go to some directory (<file>/tmp</file>, for example) and run:

<p>
<example>
# equivs-control <var>name</var>
</example>

<p>
Replace <var>name</var> for the name of the control file you
want to create. The file will be created as follows:

<p>
<example>
Section: misc
Priority: optional
Standards-Version: 3.0.1

Package: &lt;enter package name; defaults to equivs-dummy&gt;
Version: &lt;enter version here; defaults to 1.0&gt;
Maintainer: &lt;your name and email address; defaults to username&gt;
Pre-Depends: &lt;packages&gt;
Depends: &lt;packages&gt;
Recommends: &lt;packages&gt;
Suggests: &lt;package&gt;
Provides: &lt;(virtual)package&gt;
Architecture: all
Copyright: &lt;copyright file; defaults to GPL2&gt;
Changelog: &lt;changelog file; defaults to a generic changelog&gt;
Readme: &lt;README.Debian file; defaults to a generic one&gt;
Extra-Files: &lt;additional files for the doc directory, comma-separated&gt;
Description: &lt;short description; defaults to some wise words&gt;
 long description and info
 .
 second paragraph
</example>

<p>
We just need modify this to do what we want. Have a look at
the field's format and to their descriptions, there's no need
to explain each one here, let's do what's required:

<p>
<example>
Section: misc
Priority: optional
Standards-Version: 3.0.1

Package: mta-local
Provides: mail-transport-agent
</example>

<p>
Yes, that's all. <package>mutt</package> depends on
<package>mail-transport-agent</package>, that is a virtual
package provided by all MTAs, I could simply name
the package <package>mail-transport-agent</package>, but I preferred
to use the virtual package's schema, using Provides.
<p>
Now you only need to build the package:

<p>
<example>
# equivs-build <var>name</var>
dh_testdir
touch build-stamp
dh_testdir
dh_testroot
dh_clean -k
# Add here commands to install the package into debian/tmp.
touch install-stamp
dh_testdir
dh_testroot
dh_installdocs
dh_installchangelogs
dh_compress
dh_fixperms
dh_installdeb
dh_gencontrol
dh_md5sums
dh_builddeb
dpkg-deb: building package `<var>name</var>' in `../<var>name</var>_1.0_all.deb'.

The package has been created.
Attention, the package has been created in the current directory,
</example>

<p>
And install the resulting <tt>.deb</tt>.
<p>
As one can see, there are several uses for <prgn>equivs</prgn>. One
can even crate a <tt>my-favorites</tt> package, which depends on
the programs you usually installs, for example. Just free your imagination,
but be careful.
<p>
It is important to note that there are example control files in
<file>/usr/share/doc/equivs/examples</file>. Check them out.
</sect>

<sect id="localepurge">Removing unused locale files: localepurge
<p>
Many Debian users use only one locale. A Brazilian Debian user,
for example, usually uses the <tt>pt_BR</tt> locale all the time
and doesn't care about the <tt>es</tt> one.
<p>
<package>localepurge</package> is a very useful tool for these users.
You can free lots of space by having only the locales that you
really use. Just <tt>apt-get install localepurge</tt>.
<p>
It is very easy to configure it, debconf questions guide the
user in a step-by-step configuration. Be very careful on answering
the first question though, wrong answers may remove all the locales
files, even the ones you use. The only way to recover these files
is reinstalling all the packages that provide them.
</sect>

<sect id="helper-show-versions">How to know what packages may be upgraded
<p>
<prgn>apt-show-versions</prgn> is a program that shows what packages
in the system may be updated and several useful information.
The <tt>-u</tt> option displays a list of upgradeable packages:

<p>
<example>
$ apt-show-versions -u    
libeel0/unstable upgradeable from 1.0.2-5 to 1.0.2-7
libeel-data/unstable upgradeable from 1.0.2-5 to 1.0.2-7
</example>
</sect>

</chapt>

<chapt id="search">Getting information about packages.
<p>
There are some front-end programs for the APT system that make it
significantly easier to get listings of packages that are available
for installation or are already installed, as well as to find out what
section a package is in, what its priority is, what its description is, etc.
<p>
But... our goal here is to learn how to use pure APT.  So how can you find
out the name of a package that you want to install?
<p>
We have a number of resources for such a task.  We'll begin with
<tt>apt-cache</tt>.  This program is used by the APT system for maintaining
its database.  We'll take just a brief look at some of its more practical
applications.

<sect id="cache">Discovering package names
<p>
For example, suppose that you want to reminisce about the good old days of
the Atari 2600.  You want to use APT to install an Atari emulator, and then
download some games.  You can do:

<p>
<example>
# apt-cache search atari
atari-fdisk-cross - Partition editor for Atari (running on non-Atari)
circuslinux - The clowns are trying to pop balloons to score points!
madbomber - A Kaboom! clone
tcs - Character set translator.
atari800 - Atari emulator for svgalib/X/curses
stella - Atari 2600 Emulator for X windows
xmess-x - X binaries for Multi-Emulator Super System
</example>

<p>
We find several packages related to what we're looking for, together with
brief descriptions.  To get more information about a specific package, I can
then use:

<p>
<example>
# apt-cache show stella  
Package: stella
Priority: extra
Section: non-free/otherosfs
Installed-Size: 830
Maintainer: Tom Lear &lt;tom@trap.mtview.ca.us&gt;
Architecture: i386
Version: 1.1-2
Depends: libc6 (&gt;= 2.1), libstdc++2.10, xlib6g (&gt;= 3.3.5-1)
Filename: dists/potato/non-free/binary-i386/otherosfs/stella_1.1-2.deb
Size: 483430
MD5sum: 11b3e86a41a60fa1c4b334dd96c1d4b5
Description: Atari 2600 Emulator for X windows
 Stella is a portable emulator of the old Atari 2600 video-game console
 written in C++.  You can play most Atari 2600 games with it.  The latest
 news, code and binaries for Stella can be found at:
 http://www4.ncsu.edu/~bwmott/2600
</example>

<p>
In this output you have many details about the package that you want (or
don't want) to install, together with the full description of the package. 
If the package is already installed on your system and there is a newer
version, you'll see information about both versions.  For example:

<p>
<example>
# apt-cache show lilo
Package: lilo
Priority: important
Section: base
Installed-Size: 271
Maintainer: Russell Coker &lt;russell@coker.com.au&gt;
Architecture: i386
Version: 1:21.7-3
Depends: libc6 (&gt;= 2.2.1-2), debconf (&gt;=0.2.26), logrotate
Suggests: lilo-doc
Conflicts: manpages (&lt;&lt;1.29-3)
Filename: pool/main/l/lilo/lilo_21.7-3_i386.deb
Size: 143052
MD5sum: 63fe29b5317fe34ed8ec3ae955f8270e
Description: LInux LOader - The Classic OS loader can load Linux and others
 This Package contains lilo (the installer) and boot-record-images to
 install Linux, OS/2, DOS and generic Boot Sectors of other OSes.
 .
 You can use Lilo to manage your Master Boot Record (with a simple text screen)
 or call Lilo from other Boot-Loaders to jump-start the Linux kernel.

Package: lilo
Status: install ok installed
Priority: important
Section: base
Installed-Size: 190
Maintainer: Vincent Renardias &lt;vincent@debian.org&gt;
Version: 1:21.4.3-2
Depends: libc6 (&gt;= 2.1.2)
Recommends: mbr
Suggests: lilo-doc
Description: LInux LOader - The Classic OS loader can load Linux and others
 This Package contains lilo (the installer) and boot-record-images to
 install Linux, OS/2, DOS and generic Boot Sectors of other OSes.
 .
 You can use Lilo to manage your Master Boot Record (with a simple text screen)
 or call Lilo from other Boot-Loaders to jump-start the Linux kernel.
</example>

<p>
Note that the first in the list is the available package and the second is
the one already installed.  For more general information about a package,
you can use:

<p>
<example>
# apt-cache showpkg penguin-command
Package: penguin-command
Versions: 
1.4.5-1(/var/lib/apt/lists/download.sourceforge.net_debian_dists_unstable_main_binary-i386_Packages)(/var/lib/dpkg/status)

Reverse Depends: 
Dependencies: 
1.4.5-1 - libc6 (2 2.2.1-2) libpng2 (0 (null)) libsdl-mixer1.1 (2 1.1.0) libsdl1.1 (0 (null)) zlib1g (2 1:1.1.3) 
Provides: 
1.4.5-1 - 
Reverse Provides: 
</example>

<p>
And to just find out what packages it depends on:

<p>
<example>
# apt-cache depends penguin-command
penguin-command
  Depends: libc6
  Depends: libpng2
  Depends: libsdl-mixer1.1
  Depends: libsdl1.1
  Depends: zlib1g
</example>

<p>
In summary, we have a range of weapons we can use to find out the name of
a package we want.
</sect>

<sect id="dpkg-search">Using dpkg to find package names
<p>
One of the ways to locate the name of a package is to know the name of an
important file found within the package.  For example, to find the package
that provides a particular <tt>".h"</tt> file you need for compilation you
can run:

<p>
<example>
# dpkg -S stdio.h
libc6-dev: /usr/include/stdio.h
libc6-dev: /usr/include/bits/stdio.h
perl: /usr/lib/perl/5.6.0/CORE/nostdio.h
</example>

<p>
or:

<p>
<example>
# dpkg -S /usr/include/stdio.h
libc6-dev: /usr/include/stdio.h
</example>

<p>
To find out the names of packages installed on your system, which is useful,
for example, if you plan to clean up your hard drive, you can run:

<p>
<example>
# dpkg -l | grep mozilla
ii  mozilla-browse 0.9.6-7        Mozilla Web Browser
</example>
<p>
The problem with this command is that it can "break" the package name.  In
the example above, the full name of the package is <tt>mozilla-browser</tt>.
To fix this, you can use the <tt>COLUMNS</tt> environment variable this way:

<p>
<example>
[kov]@[couve] $ COLUMNS=132 dpkg -l | grep mozilla
ii  mozilla-browser             0.9.6-7                     Mozilla Web Browser - core and browser
</example>

<p>
or the description or part of it this way:

<p>
<example>
# apt-cache search "Mozilla Web Browser"
mozilla-browser - Mozilla Web Browser
</example>
</sect>

<sect id="auto-apt">How to install packages "on demand"
<p>
You're compiling a program and, all of a sudden, boom!  There's an error
because it needs a <tt>.h</tt> file you don't have.  The program
<prgn>auto-apt</prgn> can save you from such scenarios.  It asks you to
install packages if they're needed, stopping the relevant process and
continuing once the package is installed.
<p>
What you do, basically, is run:

<p>
<example>
# auto-apt run command
</example>

<p>
Where `command' is the command to be executed that may need some
unavailable file.  For example:

<p>
<example>
# auto-apt run ./configure
</example>

<p>
It will then ask to install the needed packages and call apt-get
automatically.  If you're running X, a graphical interface will
replace the default text interface.
<p>
Auto-apt keeps databases which need to be kept up-to-date in order for
it to be effective. This is achieved by calling the commands
<tt>auto-apt update</tt>, <tt>auto-apt updatedb</tt> and
<tt>auto-apt update-local</tt>.
</sect>

<sect id="apt-file">How to discover to which package a file belongs
<p>
If you want to install a package, and you can't find out what it is
called by searching with <prgn>apt-cache</prgn>, but know the filename 
of the program itself, or some other filename that belongs to the package,
then you can use <prgn>apt-file</prgn> to find the package name. This 
is done like this:

<p>
<example>
$ apt-file search <var>filename</var>
</example>

<p>
It works just like <tt>dpkg -S</tt>, but will also show you uninstalled
packages that contain the file. It could also be used to find what
packages contain necessary include files that are missing when
compiling programs, although <prgn>auto-apt</prgn> is a much better 
method of solving such issues, see <ref id="auto-apt">.
<p>
You can also list the contents of a package, by running:

<p>
<example>
$ apt-file list <var>packagename</var>
</example>

<p>
<prgn>apt-file</prgn> keeps a database of which files all packages 
contain, just like auto-apt does and it needs to be up-to-date. 
This is done by running:

<p>
<example>
# apt-file update
</example>

<p>
By default, <prgn>apt-file</prgn> uses the same database 
<prgn>auto-apt</prgn> is using, see <ref id="auto-apt">.

</sect>

<sect id="apt-listchanges">How to keep informed about the changes in the packages.
<p>
Every package installs in its documentation directory (<tt>/usr/share/doc/packagename</tt>)
a file called <tt>changelog.Debian.gz</tt> which contains the list of changes
made to the package since the last version. You can read these files with
<tt>zless</tt>' help, for example, but it is something not so easy, after an
complete system upgrade, to start searching changelogs for every upgraded
package.
<p>
There's a way to automatize this task by means of a tool called
<prgn>apt-listchanges</prgn>. To begin with one needs to install
the <package>apt-listchanges</package> package. During the package
installation, Debconf will configure it. Some questions may not be
shown to you depending on the priority you set up Debconf to use.
Answer to the questions as you want.
<p>
The first question asks how you want the changes to be showed by
apt-listchanges. You can have them mailed to you, which is good for
automatic upgrades, or you can ask them in a pager
like <prgn>less</prgn>, so you can inspect the changes before
leting the upgrade continue. If you don't
want <prgn>apt-listchanges</prgn> running automaticaly during
upgrades you can answer <tt>none</tt>.
<p>
After apt-listchanges is installed, as soon as packages are downloaded
(or gotten from a CD or mounted disk) by apt it will show the lists
of changes made to those packages before installing them.
</sect>
</chapt>

<chapt id="sourcehandling">Working with source packages
<sect id="source">Downloading source packages
<p>
It's common in the world of free software to study source code or
even make corrections to buggy code.  To do this, you would need to
download the source of the program.  The APT system provides an easy way
to obtain source code to the many programs contained in the
distribution, including all the files needed to create a .deb for the
program.
<p>
Another common use of Debian sources is to adapt a more recent version
of a program, from the unstable distribution, for example, for use with
the stable distribution.  Compiling a package against stable will
generate .debs with dependencies adjusted to match the packages
available in this distribution.
<p>
To accomplish this, the <tt>deb-src</tt> entry in your
<tt>/etc/apt/sources.list</tt> should be pointed at unstable.  It should
also be enabled (uncommented).  See section <ref id="sources.list">.
<p>
To download a source package, you would use the following command:

<p>
<example>
$ apt-get source packagename
</example>
<p>
This will download three files:  a <tt>.orig.tar.gz</tt>, a
<tt>.dsc</tt> and a <tt>.diff.gz</tt>. In the case of packages
made specifically for Debian, the last of these is not downloaded
and the first usually won't have <tt>"orig"</tt> in the name.
<p>
The <tt>.dsc</tt> file is used by dpkg-source for unpacking the source
package into the directory <var>packagename-version</var>. Within each
downloaded source package there is a <tt>debian/</tt> directory that
contains the files needed for creating the .deb package.
<p>
To auto-build the package when it's been downloaded, just add
<tt>-b</tt> to the command line, like this:

<p>
<example>
$ apt-get -b source packagename
</example>

<p>
If you decide not to create the .deb at the time of the download, you
can create it later by running:

<p>
<example>
$ dpkg-buildpackage -rfakeroot -uc -b
</example>

<p>
from within the directory that was created for the package after
downloading. To install the package built by the commands above
one must use the package manager directly, like this:

<p>
<example>
# dpkg -i <var>file.deb</var>
</example>

<p>
There's a difference between <prgn>apt-get</prgn>'s <tt>source</tt>
method and its other methods.  The <tt>source</tt> method can be used by
normal users, without needing special root powers.  The files are
downloaded to the directory from which the <tt>apt-get source package</tt>
command was called.
</sect>

<sect id="build-dep">Packages needed for compiling a source package
<p>
Normally, specific headers and shared libraries need to be present in
order for a source package to be compiled.  All source packages have a
field in their control files called 'Build-Depends:' that indicates
which additional packages are needed for the package to be built from
source.
<p>
APT has a simple way of downloading these packages.  Just run
<tt>apt-get build-dep package</tt>, where `package' is the name of the
package you're going to build.  For example:

<p>
<example>
# apt-get build-dep gmc
Reading Package Lists... Done
Building Dependency Tree... Done
The following NEW packages will be installed:
  comerr-dev e2fslibs-dev gdk-imlib-dev imlib-progs libgnome-dev libgnorba-dev
  libgpmg1-dev 
0 packages upgraded, 7 newly installed, 0 to remove and 1  not upgraded.
Need to get 1069kB of archives. After unpacking 3514kB will be used.
Do you want to continue? [Y/n]
</example>

<p>
The packages that will be installed are the packages needed in order for
<package>gmc</package> to be built correctly.  It's important to note
that this command doesn't look for the source package of the program to
be compiled.  You will therefore need to run <tt>apt-get source</tt>
separately to get it.

<p>
If all you want is checking what packages are needed to build a
given package, there's a variant of the <tt>apt-cache show</tt>
command (see <ref id="search">, which will show, among other
informations, the <tt>Build-Depends</tt> line that lists those
information, the <tt>Build-Depends</tt> line that lists those

<p>
<example>
# apt-cache showsrc <var>package</var>
</example>

</sect>
</chapt>

<chapt id="erros">How to deal with errors
<sect id="erros-comuns">Common errors
<p>
Errors will always happen, many of them caused by users not paying
attention.  The following is a list of some of the most frequently reported errors and
how to deal with them.
<p>
If you receive a message that looks like the one below when trying to
run <tt>apt-get install package</tt>...

<p>
<example>
Reading Package Lists... Done
Building Dependency Tree... Done
W: Couldn't stat source package list 'http://people.debian.org unstable/ Packages' (/var/state/apt/lists/people.debian.org_%7ekov_debian_unstable_Packages) - stat (2 No such file or directory)
W: You may want to run apt-get update to correct these missing files
E: Couldn't find package penguineyes
</example>

<p>
you forgot to run <tt>apt-get update</tt> after your last change to the
<tt>/etc/apt/sources.list</tt> file.
<p>
If the error looked like:

<p>
<example>
E: Could not open lock file /var/lib/dpkg/lock - open (13 Permission denied)
E: Unable to lock the administration directory (/var/lib/dpkg/), are you root?
</example>

<p>
when trying any <prgn>apt-get</prgn> method other than <tt>source</tt>,
you don't have root permission, that is, you're running as a normal
user.
<p>
There's an error similar to the above which happens when you run two
copies of <prgn>apt-get</prgn> at the same time, or even if you try to
run <prgn>apt-get</prgn> while a <prgn>dpkg</prgn> process is active.
The only method that can be used simultaneously with others is the
<tt>source</tt> method.
<p>
If an installation breaks in the middle of the process and you find that
it's no longer possible to install or remove packages, try running these
two commands:

<p>
<example>
# apt-get -f install
# dpkg --configure -a
</example>

<p>
And then try again.  It may be necessary to run the second of the above
commands more than once.  This is an important lesson for those
adventurers who use `unstable'.

<p>
If you receive the error "E: Dynamic MMap ran out of room" when running
<tt>apt-get update</tt>, add the following line to 
<file>/etc/apt/apt.conf</file>:

<example>
APT::Cache-Limit 10000000;
</example>

</sect>

<sect id="help">Where can I find help?
<p>
If you find yourself plagued by doubts, consult the extensive
documentation available for the Debian packaging system.
<tt>--help</tt>'s and manpages can be an enormous help to you, as can
the documentation contained in the <tt>/usr/share/doc</tt> directories
such as <tt>/usr/share/doc/apt</tt>.
<p>
If this documentation fails to drive your fears away, try looking for
the answer on the Debian mailing lists.  You can find more information
about specific user lists on the Debian website: <url
id="http://www.debian.org" name="http://www.debian.org">.
<p>
Remember that these lists and resources should be used only by Debian
users; users of other systems will find better support from the
community resources of their own distributions.
</sect>
</chapt>

<chapt id="distros">What distributions support APT?
<p>
Here are the names of some of the distributions that use APT:
<p>
Debian GNU/Linux (<url id="http://www.debian.org" name="http://www.debian.org">) 
- it was for this distribution that APT was developed
<p>
Conectiva (<url id="http://www.conectiva.com.br" name="http://www.conectiva.com.br">) 
- this was the first distribution to port APT for use with rpm
<p>
Libranet (<url id="http://www.libranet.com" name="http://www.libranet.com">)
<p>
Mandrake (<url id="http://www.mandrake.com" name="http://www.mandrake.com">)
<p>
PLD (<url id="http://www.pld.org.pl" name="http://www.pld.org.pl">)
<p>
Vine (<url id="http://www.vinelinux.org" name="http://www.vinelinux.org">)
<p>
APT4RPM (<url id="http://apt4rpm.sf.net" name="http://apt4rpm.sf.net">)
<p>
Alt Linux (<url id="http://www.altlinux.ru/" name="http://www.altlinux.ru/">)
<p>
Red Hat (<url id="http://www.redhat.com/" name="http://www.redhat.com/">)
<p>
Sun Solaris (<url id="http://www.sun.com/" name="http://www.sun.com/">)
<p>
SuSE (<url id="http://www.suse.de/" name="http://www.suse.de/">)
<p>
Yellow Dog Linux (<url id="http://www.yellowdoglinux.com/"
name="http://www.yellowdoglinux.com/">)
</chapt>

<chapt id="agradecimentos">Credits
<p>
A big thank you goes out to my great friends in the Debian-BR project,
and in Debian itself, who are a constant help to me and always give me
the strength to continue working for humanity's benefit, as well as
helping me with my goal of saving the world. :)
<p>
I also want to thank the CIPSGA for the enormous help it has given to
our project and to all the free projects that spring from great ideas.
<p>

And special thanks to:
<p>
Yooseong Yang &lt;yooseong@debian.org&gt;
<p>
Michael Bramer &lt;grisu@debian.org&gt;
<p>
Bryan Stillwell &lt;bryan@bokeoa.com&gt;
<p>
Pawel Tecza  &lt;pawel.tecza@poczta.fm&gt;
<p>
Hugo Mora &lt;h.mora@melix.com.mx&gt;
<p>
Luca Monducci &lt;luca.mo@tiscali.it&gt;
<p>
Tomohiro KUBOTA &lt;kubota@debian.org&gt;
<p>
Pablo Lorenzzoni &lt;spectra@debian.org&gt;
<p>
Steve Langasek &lt;vorlon@netexpress.net&gt;
<p>
Arnaldo Carvalho de Melo &lt;acme@conectiva.com.br&gt;
<p>
Erik Rossen &lt;rossen@freesurf.ch&gt;
<p>
Ross Boylan &lt;RossBoylan@stanfordalumni.org&gt;
<p>
Matt Kraai &lt;kraai@debian.org&gt;
<p>
Aaron M. Ucko &lt;ucko@debian.org&gt;
<p>
Jon &Aring;slund &lt;d98-jas@nada.kth.se&gt;
</chapt>

<chapt id="novas">New versions of this tutorial
<p>
This manual was created by the <url id="http://www.debian-br.org"
name="Debian-BR"> project, with the goal of aiding everyday use of
Debian.
<p>
New versions of this document will be made available in the Debian
Documentation Project's
page, at 
<url id="http://www.debian.org/doc/ddp" 
name="http://www.debian.org/doc/ddp">. 
<p>
Comments and criticisms can be sent to me directly by email at
<email>kov@debian.org</email>.
</chapt>

</book>

</debiandoc>