<!doctype debiandoc system>
<debiandoc>

<book>

<title>APT HOWTO</title>

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

<version>2.0.2 - October 2006</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, 2005 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., 51 Franklin St,
Fifth Floor, Boston, MA 02110-1301, 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>
<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>
<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>
<p>
This manual is based on the next Debian release, <tt>Etch</tt>, as of
31th of August, 2005.
</p>

<sect id="terminology">Basic terminology and concepts
<p>
Here you can find some basic terminology and concepts used on this
manual:
</p>
<p>
<strong>APT source</strong>: an APT source is a location (often on the
internet, or possibly on a CDROM or other location) which functions as
a repository of Debian packages, see <ref id="sources.list">.
</p>
<p>
<strong>APT source line</strong>: an APT source line is a line you add
to a configuration file to tell APT about the "Apt sources" you want
to use, see <ref id="sources.list">.
</p>
<p>
<strong>binary package</strong>: a binary package is a <tt>.deb</tt>
file prepared to be installed by the package manager (dpkg), it may
include binary files but may also carry just architecture-independent
data -- it's called binary package either way.
</p>
<p>
<strong>debian-native</strong>: package created specifically for
Debian, this kind of package usually has the debian control files
inside the original source and every new version of the package is
also a new version of the original program or data.
</p>
<p>
<strong>debianize</strong>: verb usually used to mean "prepare for
use with Debian" or, more simply put, packaged in <tt>.deb</tt>
format.
</p>
<p>
<strong>source  package</strong>:  a   source  package  is  really  an
abstract definition to  a set of two or three files  which are part of
the  deb   source  format:   a  <tt>.dsc</tt>  file,   which  contains
information  about  the  package,  also called  source  control  file;
a  <tt>.orig.tar.gz</tt> file,  which contains  the  original upstream
source   for  that   package  --   you  may   also  find   this  being
called  <tt>.tar.gz</tt>, simply,  with no  .orig, meaning  this  is a
debian-native  package; a  <tt>.diff.gz</tt> file,  which  carries the
modifications made  to the original source to  "debianize" the package
-- you will not find this kind of file on a debian-native package.
</p>
<p>
<strong>upstream</strong>: this word usually means something that comes
from the original developer of the software or data, or the developer
himself.
</p>
<p>
<strong>virtual packages</strong>: virtual  packages are packages that
do not really exist, but  that are generic services "provided" by some
specific    packages     --    the    most     common    example    is
the <package>mail-transport-agent</package> package, to which packages
that  need an  MTA<footnote>MTA means  Mail Transfer Agent  --- it's
usually a  server to  send and receive  mail</footnote> can  specify a
dependency while keeping the user choice as to which MTA to use.
</p>
</sect>
</chapt>

<chapt id="archive-layout">Introduction to the Debian archive

<sect id="archive:suites">Introduction to Debian suites

<p>
Debian development happens in a model where we have three main
"trees" which we call "suites": the stable suite is the last released
version of Debian; the testing suite contains theoretically a
always-ready-to-release version, packages come from the unstable
branch after being there for 10 days with no critical problems
reported and after being built on all release architectures; the
unstable suite is where development happens: all new packages go to
unstable to be tested for releasability and, then, end up in testing.
</p>

<p>
The stable suite never receives new versions of packages, just new
revisions to fix security or critical problems. It is supposed to
remain stable, meaning that the admin need not expect changes in
configuration or behavior of the software they administer.
</p>

<p>
There is another suite which is treated differently from the usual
ones by many tools: the experimental suite. First of all, it is not a
self-contained suite, meaning you cannot have a system installed
simply from it, you usually need to use it together with one of the
ones mentioned earlier: most times the unstable one is chosen.
</p>

<p>
It's treated differently because it is indeed highly experimental in
nature. Packages which maintainers think are broken or not really
ready to go in unstable come to experimental for wider testing by
fearless maintainers. Please do not use experimental if you're not
actually willing to help in development, taking care of the burden it
might bring to you yourself.
</p>
</sect>

<sect id="archive:suites:sections">Debian sections
<p>
Each suite of a Debian repository is usually composed of one or more
sections; their names and purposes may vary from one distributor to
the other. Debian itself has three sections: main, contrib and
non-free.
</p>

<p>
The <tt>main</tt> section is what Debian actually is, officially. All
the software that conforms to the <url
id="http://www.debian.org/social_contract#guidelines" name="Debian
Free Software Guidelines"> (DFSG) and only depends on
DFSG-conformant software come to this section of the archive,
complying with the <url id="http://www.debian.org/social_contract"
name="Social Contract">. Through these documents, and by promising
to only allow software that complies with them to enter the main
section, Debian provides a reasonably clear basic standard of freedom
which users can rely on when installing software from main.
</p>

<p>
The <tt>contrib</tt> section is composed of DFSG-compliant software
which depend on non-DFSG-compliant software or data to work. The
<tt>non-free</tt> section is composed of software which do not conform
to the DFSG but may be distributed. You should check the license of
each software from non-free you want to install to evaluate if they're
good enough for you to accept.
</p>
</sect>

<sect id="trustchain">APT's chain of trust
<p>
APT comes equipped with a cryptographic chain-of-trust that extends
from the debian developers to the end users.
</p>

<p>
The chain starts with the package maintainers who sign and upload
their packages.  Each signature is checked against the packager's key
which was uploaded when they became an official Debian developer.
This key was itself verified personally by other Debian
developers.
</p>

<p>
Once the uploaded package is verified as having been signed by the
maintainer, an MD5 sum of the package is computed and put in the
Packages file.  The MD5 sums of all of the Packages files are then
computed and put into the Release file.  The Release file is then
signed by the archive key which is created once a year and distributed
by the FTP server.  This key is also on the Debian keyring.
</p>

<p>
Therefore, the end user, having added the archive key to his keyring ,
can check that the <tt>Release</tt> file was signed by the proper key,
the MD5 sums of all the <tt>Packages</tt> files, and the MD5 sums of
all the Debian packages.  APT automates this process:
</p>

<p>
During update (see <ref id="update">), APT checks the signature of the
Release files by using its keyring (see <ref id="apt-key"> for
information on this) and the MD5 sums of the Packages files (which are
recorded in the Release files).
</p>

<p>
During upgrade or installation of a package (see <ref id="upgrade">
and <ref id="install"> respectively) APT checks the MD5 sums of the
packages (which are stored in the Packages files).
</p>

<p>
If any of these steps fails, the user is warned, and the process
halts.
</p>
</sect>

</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 'APT sources'
from which packages can be obtained.  This file is
<tt>/etc/apt/sources.list</tt>.
</p>
<p>
The entries in this file normally follow this format:
</p>

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

<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, check <ref id="sourcehandling">.
</p>
<p>
The word that goes where we read <tt>distribution</tt> in the above
example defines what is the Debian suite we're targeting. They can be
generic names, like "stable", "testing", or specific names like
"sarge" and "etch". Let's say the current testing is called "etch" and
you want to keep tracking "etch" even when it becomes stable; in this
case you should use "etch" for <tt>distribution</tt>. In case you want to
keep tracking testing you should use "testing" instead.
</p>
<p>
So, if you want to always have the latest stable distribution, and
upgrade as soon as a new release is made, you should be using "stable"
as <tt>distribution</tt>. This may not be a good idea, for you may want
to plan the upgrade for stable releases, which sometimes involves more
than simply answering a few new questions, besides doing some testing
and backuping before proceeding, so I recommend you always use the
codenames.
</p>
<p>
We usually find the following in the default Debian sources.list:
</p>
<p>
<example>
deb http://http.us.debian.org/debian stable main
deb http://security.debian.org stable/updates main

#deb-src http://http.us.debian.org/debian stable
#deb-src http://security.debian.org stable/updates main
</example>
</p>

<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
archive of Debian security updates.
</p>
<p>
The two last lines are commented out (with a `#' in front), so APT 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>
<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>
<p>
Remember: everytime you want to add a source for APT to grab packages
from this is the file you're going to edit.
</p>
<p>
Do not forget to update the list of packages after modifying
the <tt>/etc/apt/sources.list</tt> file, see <ref id="update">.  You
must do this to let APT know what packages are available from the
sources you specified.
</p>
</sect>

<sect id="apt-key">Authenticating packages
<p>
As of APT version 0.6, packages are authenticated to ensure that they
originate from the source that they claim to originate from.  This is
an optional security feature.  If the system can't authenticate the
package upon installation, it'll ask you whether or not you want to
abort the installation.
</p>

<p>
Since this authentication is based on cryptographic methods, APT
maintains it's own keyring.  Each of the entries in your
<tt>sources.list</tt> file will have a corresponding key. However, if
you're using unofficial APT sources, it's possible that a source
you're using won't be authenticated.  If this is the case, you should
encourage the maintainer of that source to implement authentication on
their site.
</p>

<p>
To take advantage of this security feature, you need to add a key to
APT's keyring for each authenticated source.  This can be done with
GPG, but APT provides a tool, <prgn>apt-key</prgn>, which is a
simplified wrapper to GPG.
</p>

<p>
<prgn>apt-key</prgn> is easy to use.  The tricky part of this process
is getting a key for each of your sources, and making sure that you
can trust that key.
</p>

<p>
Debian's archive key will be installed in
<file>/usr/share/apt/debian-archive.gpg</file>, so you can simply use
that file to add the official archives' key to your APT keyring by
doing this:
</p>

<p>
<example>
# apt-key add /usr/share/apt/debian-archive.gpg
</example>
</p>

<p>
For external, unofficial sources you'll need to find out where did
they provide their public key so that you can import it into your APT
keyring.
</p>

<p>
If you choose to disable the cryptographic checking of Release files
for some reason you can add the following to APT's configuration (see
<ref id="apt.conf">):
</p>
<p>
<example>
APT::Get::AllowUnauthenticated "true";
</example>
</p>
</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>

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

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

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

<p>
For example:
</p>

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

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

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

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

<sect id="apt.conf">The APT configuration file
<p>
APT uses <file>/etc/apt/apt.conf</file> as its main configuration
file. Although, as you will find out, there's no file named like that
in a default install, you can safely create one and add your edits
there. If you prefer, there's a more modular way of handling
configuration: you can place individual files with whatever names you
choose into <file>/etc/apt/apt.conf.d/</file>.
</p>
<p>
Beware of two facts when you choose the modular way: some Debian
packages will drop their configuration stuff into that directory, so
you have to try to prevent name clashes by, for example, adding a
<tt>-local</tt> suffix to the name. Also, the configuration is read
ordered by the file name, so you can add a number at the very
beginning of your filename to position it on the sequence. For
example, you can name it <tt>00000myconf-local</tt> if you want to
make sure it will be the first configuration to be considered.
</p>
<p>
To know the syntax and options accepted by those configuration files,
check out the <tt>apt.conf(5)</tt> manpage.
</p>
</sect>

<sect id="apt:policy">Adjusting APT priority for packages

<p>
APT uses a prioritization algorythm to decide what repository it
should grab a given package from. Here's a simple example:
</p>

<p>
<example>
$ apt-cache policy apt-howto
apt-howto:
  Installed: 1.8.10.3-1
  Candidate: 1.8.11-1
  Version table:
     1.8.11-1 0
        500 http://ftp.nl.debian.org sid/main Packages
 *** 1.8.10.3-1 0
        500 http://ftp.nl.debian.org sarge/main Packages
        100 /var/lib/dpkg/status
</example>
</p>

<p>
I have two sources here: a sid and a sarge one, and that's all.
</p>
<p>
The installed version is marked with <tt>***</tt>. We can see its
installed because of the mention of the
<file>/var/lib/dpkg/status</file> file, too, which holds the
information about the current state of the system. We can also see
that the package comes from sarge. The sid version is also listed as
available.
</p>

<p>
APT gives priority 100 for installed packages, as we can see, and 500
for all other sources with a single exception: the
<tt>experimental</tt> suite, which, as we already said, is treated in
a special way by many tool. APT's algorythm will prefer to install
packages from sources with higher priority. If priorities are the
same, then it will prefer the highest version. You can see that by
looking at the <tt>Candidate</tt> field, which lists the newer
version, from unstable, as candidate for instalation: it wants to
upgrade it.
</p>

<p>
If you want to have the sid source only to install selected packages
and don't want APT to automaticaly consider packages from that source
as candidates for upgrades, then you must tweak its priorities. You do
that using the <tt>Archive</tt> field of the <tt>Release</tt> file of
the source you want to give priority to. You can find that information
out by looking at the Release file which the update process
downloaded:
</p>

<p>
<example>
# grep ^Archive /var/lib/apt/lists/ftp.nl.debian.org_debian_dists_sarge_main_binary-i386_Release
Archive: stable
</example>
</p>

<p>
Notice that the filename changes depending on your source line. To
make APT keep your packages at the stable suite, then, you add a file
with the following contents to <file>/etc/apt/apt.conf.d/</file>:
</p>

<p>
<example>
APT::Default-Release "stable";
</example>
</p>

<p>
Then, APT policy will have changed:
</p>

<p>
<example>
$ apt-cache policy apt-howto
apt-howto:
  Installed: 1.8.10.3-1
  Candidate: 1.8.10.3-1
  Version table:
     1.8.11-1 0
        500 http://ftp.nl.debian.org sid/main Packages
 *** 1.8.10.3-1 0
        990 http://ftp.nl.debian.org sarge/main Packages
        100 /var/lib/dpkg/status
</example>
</p>

<p>
APT will give priority 990 for its default source for any package,
the other sources remain just like before. Packages from other sources
which are installed will have their priority raised from 100 to
500. Why is APT not going to downgrade them? Because APT will only
consider a downgrade in case something is given a priority above
1000. That means, though, that APT will not automaticaly upgrade the
versions from the non-default sources unless the tool you're using
wants to try to to help you there, which is the case for aptitude.
</p>

<p>
Defining priority for groups of packages based on many other criteria
is also possible by using the <file>/etc/apt/preferences</file>
configuration file. You can even convince APT to try to downgrade your
whole system, althought that's not supported and should not be tried
by the faint of heart. You can have more information about that by
reading the <tt>apt_preferences(5)</tt> manpage..
</p>
</sect>

<sect id="proxy">Using APT through a proxy
<p>
If you are using APT in a network in which all http and ftp
connections are made through a proxy, then you'll have to setup APT to
use that proxy.  You can do this by editing the
<file>/etc/apt/apt.conf</file> configuration file or by placing a
configuration file inside the <file>/etc/apt/apt.conf.d/</file>
directory, which makes it is easier to organize the configuration
stuff (take a look at <ref id="apt.conf">).
</p>
<p>
If that file does not exist, then create it and add lines like these:
</p>
<p>
<example>
Acquire::http::proxy "http://<var>proxy</var>:<var>port</var>";
Acquire::ftp::proxy "http://<var>proxy</var>:<var>port</var>";
</example>
</p>
<p>
Replace <var>proxy</var>  and <var>port</var> for those  given by your
network administrator. You  can also specify user and  password if the
proxy requires like this: 
</p>
<p>
<example>
Acquire::http::proxy "http://<var>user</var>:<var>password</var>@<var>proxy</var>:<var>port</var>";
</example>
</p>
<p>
There are many other useful options you can set for APT on the
<file>/etc/apt/apt.conf</file> configuration file, see <ref
id="apt.conf">.  
</p>
</sect> 
</chapt>

<chapt id="apt-get">Managing packages
<sect id="aptitude">Using the Debian Package Manager: aptitude
<p>
Debian has  long lived with  a package manager  which was known  to be
difficult  to understand  and use,  called  <prgn>dselect</prgn>.  The
Debian   system  is  now   moving  towards   a  new   default  manager
called <prgn>aptitude</prgn>, which is also based on the APT library.
</p>
<p>
If you  installed Sarge you will  have <prgn>aptitude</prgn> installed
by    default    on     the    base    system,    otherwise    install
the <package>aptitude</package> package  by running, for example, this
command before continuing:
</p>
<p>
<example>
# apt-get install aptitude
</example>
</p>
<p>
Try to avoid using  <prgn>apt-get</prgn>  and use  <prgn>aptitude</prgn>
instead, as it knows  much more about what APT is able  to do and have
some  unique features  like marking  packages that  were automatically
installed to satisfy dependencies and ask to remove them automatically
when they are no longer needed.
</p>
<p>
<prgn>aptitude</prgn> has two main  modes: a ncurses-based UI in which
you    can    navigate   through    a    list    of   packages    much
like   <prgn>dselect</prgn>  and   a  command   line-based   UI,  much
like  <prgn>apt-get</prgn>. Most  examples  in this  document use  the
command line-based UI, giving tips on which command is used to achieve
the same results in the <prgn>aptitude</prgn> dselect-like UI.
</p>
<p>
To fire up this UI, type <tt>aptitude</tt> in a terminal -- there's no
need to be  root at this time, aptitude will  request root powers when
it needs them automatically. Let's check out the basics: to access the
menubar at the top of the screen  you need to press F10, as the second
line suggests.   This second line has  a summary of  the most commonly
used features  like getting help,  quiting, updating list  of packages
and proceeding.
</p>
<p>
Do take a look at the <tt>User Manual</tt> which is located at the help
menu to understand how the thing works.
</p>
<p>
Notice  that <prgn>aptitude</prgn>  works in  a way  similar  to other
package    managers:    you    make    all   your    selections    and
then <tt>commits</tt> the changes. Almost all actions done in managing
the instalation of a package  will require pressing the <tt>g</tt> key
two times to be effective.   The first time you press <tt>g</tt> you'll
be  presented  with   the  list  of  changes  being   done,  then  you
press  <tt>g</tt> again  to confirm  the changes  or <tt>q</tt>  to go
back. 
</p>
<p>
Similarly, you  can press the  <tt>Enter</tt> key to get  more details
about  a  package  or  group  of  packages --  for  example,  you  can
press <tt>Enter</tt>  when the selection  is on 'New Packages'  to see
the a  list of sections. By  pressing <tt>Enter</tt> on  a section you
will see the list of new packages in that section and you can see more
details on  a package  by pressing <tt>Enter</tt>  on it.  Notice that
entering a package's  details will change <prgn>aptitude</prgn>'s view
context, so you'll need to press <tt>q</tt> to go back.
</p>
<p>
The packages are categorized by default based on their installation
status and some other special categories. You'll be seing this when
you first enter <prgn>aptitude</prgn>
</p>
<p>
<example>
--- New Packages
--- Upgradable Packages
--- Installed Packages
--- Not Installed Packages
--- Obsolete and Locally Created Packages
--- Virtual Packages
--- Tasks
</example>
</p>
<p>
New Packages has the packages that entered Debian since the last time
you cleared your list of new packages using the <tt>Forget new packages</tt>
option in the Actions menu, or the "<tt>f</tt>" key.
</p>
<p>
Upgradable Packages are installed packages that have new versions
available. Installed Packages are the installed packages proper, Not
Installed Packages are the ones you did not install but are available
from one of the APT sources. Obsolete and Locally Created Packages are
those packages that are no longer available from at least one APT
source or the ones you created yourself. Virtual Packages are packages
defining a service rather than a particular software and that are
"provided" by several specific packages. Finally, Tasks are the collections
of packages which serve a specific purpose, also used by the
<prgn>tasksel</prgn> program.
</p>
<p>
Pressing <tt>Enter</tt> on any of those will expand the tree to something
like this:
</p>
<p>
<example>
--\ Not Installed Packages
  --- admin - Administrative utilities (install software, manage users, etc)
  --- base - The Debian base system
[...]
</example>
</p>
<p>
Going even deeper we'll have:
</p>
<p>
<example>
  --\ games - Games, toys, and fun programs
    --- contrib - Programs which depend on software not in Debian
    --\ main - The main Debian archive
p     3dchess                                               &lt;none&gt;     0.8.1-10
</example>
</p>
<p>
This shows us one package which is a not installed one, that is a game
and that is available from the main Debian repository, which is what
the Debian distribution is officially.
</p>
<p>
On the center of the screen there's a marked line that is filled with
some text when you select a package. That is what we call the <tt>short
description</tt> of the package. Below it there's a text box containing
more detailed information on the package. That's the <tt>long 
description</tt>. Some times the long description is too big to fit
the rectangle reserved for it, so you can press the "<tt>z</tt>"
key to scroll it down and "<tt>a</tt>" to scroll it up again.
</p>
<p>
Check <ref id="install"> for more information on the data shown here.
</p>
</sect>

<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>aptitude</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>
<p>
To update this list, you would use the command <prgn>aptitude 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. You can also use the "<tt>u</tt>" key inside
the ncurses interface of aptitude to have it update the packages lists.
</p>
<p>
One of the steps that APT takes in updating your database is to verify
that the list of packages and their MD5 sums is secure.  It does this
by verifying a cryptographic signature, and checking some MD5 sums;
see <ref id="trustchain"> for more information.  If APT finds that the
signature is incorrect, or that the MD5 sums do not match, you may get
an error while updating your package database.  This is to prevent
trojaned packages from being installed on your computer.  If this
occurs, there may be a configuration problem (such as an out-of-date
key) which you can solve.  Failing this, you should contact the
administrator of the apt source that failed.
</p>
<p>
It's a good idea to update the lists of available packages regularly
to keep yourself and your system informed about possible package
updates, particularly security updates.
</p>
</sect>

<sect id="searching">Searching for packages
<p>
Aptitude provides a very flexible and powerful search feature.
You can access it by pressing the "<tt>/</tt>" (slash) key.
That will open a small dialog on the center of the screen.
</p>
<p>
You can then type the name of a package. Aptitude will search as
you type. If the package it finds is not exactly the one you want
you can press enter for the dialog to vanish and then press the
"<tt>n</tt>" key to repeat the search for the same string.
</p>
<p>
You can use regular expressions<footnote>regular expressions
are special strings to match sentences based on some conditions, 
take a look at the regex(7) manpage</footnote> on the search dialog,
just beware that aptitude has its own search language which sometimes
overlaps with the regular expressions' one. Let's move on to an
example, then: if you want to have an exact match to the string 
"gnome" type "<tt>^gnome$</tt>" on the search dialog.
</p>
<p>
Notice that when searching like this you are simply searching for
the package names. If you want to search for descriptions you need
to use "<tt>~d</tt>" right before the search term. So, if you want
to search for all packages mentioning "isolinux" on their descriptions
you'd write "<tt>~disolinux</tt>" at the search dialog.
</p>
<p>
You can also search for all packages which are currently broken
by searching for "<tt>~b</tt>", search for all the packages which
were removed but which configuration files have ben kept searching
for "<tt>~c</tt>".
</p>
<p>
For more advanced searching on <prgn>aptitude</prgn> take a look
at Aptitude's <tt>User Manual</tt>, which you can find inside
the Help menu.
</p>
<p>
You can also use the command line to search for packages like this:
</p>
<p>
<example>
$ aptitude search '~c'
c A abiword-common                  - WYSIWYG word processor based on GTK2
c A acme                            - Enables the "multimedia buttons" found on
(...)
</example>
</p>
<p>
As you can see, you can use any aptitude search string when using the
command line too, and <prgn>aptitude</prgn> provides you some information
on the state of the packages that we are going to discuss through this
manual.
</p>
</sect>

<sect id="install">Installing and reinstalling packages
<p>
Finally, the process you've all been waiting for!  With your
sources.list ready, your keys added to APT's keyring, and your list of
available packages up to date, all you have to do is run
<tt>aptitude</tt> to get your desired package installed.
</p>
<p>
When you  enter <prgn>aptitude</prgn> you  can have it install  one or
more packages  by pressing the  "<tt>+</tt>" key while the  package in
question is selected.  You can  use the "<tt>/</tt>" key to search for
the package  you want, see  <ref id="searching">. When  you request
the installation of a package it will be marked with a green color and
the line will look like in this example:
</p>
<p>
<example>
pi    celestia-gnome                                        &lt;none&gt;     1.3.0-1
</example>
</p>
<p>
This means that the package is not installed ('p') and is marked
for installation. The word <tt>&lt;none&gt;</tt> means no version
is installed and the version number after it is the one that is
being marked for installation.
</p>
<p>
Notice that when you do that other packages will be marked for
installation automatically. Those are the dependencies,
suggestions and recommendations of the selected package. They
will most probably be marked like this:
</p>
<p>
<example>
piA   gnome-bin                                             &lt;none&gt;     1.4.2-16
</example>
</p>
<p>
The uppercased 'A' means that this package is being installed
because another package depends on it. All packages installed
like that will be removed when no longer needed. You can have that
mark set manually by typing "<tt>M</tt>" with the cursor positioned
at a package.
</p>
<p>
A 'U' sign at the forth column means that package comes from an
untrusted source, which means there's no signed <tt>Release</tt> file
for the source that package comes from or its public key has not been
imported into APT's keyring. See <ref id="apt-key"> to understand what
you should do to have that source be trusted. You may have that same
package in one of the trusted sources too, though, so you may want to
take a look at the detailed information about available versions of
that package.
</p>
<p>
You can have detailed information about the package you want to
install by pressing <tt>Enter</tt> while the package is selected.
This will bring you to something like this:
</p>
<p>
<example>
i A --\ xterm                                             4.2.1-14     4.2.1-14
  Description
xterm - X terminal emulator
xterm is a terminal emulator for the X Window System.  It provides DEC VT102
and Tektronix 4014 compatible terminals for programs that cannot use the
window system directly.  This version implements ISO/ANSI colors and most of
the control sequences used by DEC VT220 terminals.
  Priority: optional
  Section: x11
  Maintainer: Branden Robinson &lt;branden@debian.org&gt;
  Compressed size: 547k
  Uncompressed size: 1130k
  Source Package: xfree86
  --\ Depends
    --- libc6 (>= 2.3.2.ds1-4)
    --- libfreetype6 (>= 2.1.5-1)
    --- libncurses5 (>= 5.3.20030510-1)
    --- libxaw7 (> 4.1.0)
    --- xlibs (> 4.1.0)
    --- xlibs (> 4.2.0)
  --\ Conflicts
    --- xbase (< 3.3.2.3a-2)
    --- suidmanager (< 0.50)
  --\ Replaces
    --- xbase (< 3.3.2.3a-2)
  --- Packages which depend on xterm
  --\ Versions
p A 4.3.0-0pre1v4
i A 4.2.1-14
</example>
</p>
<p>
Those versions which are trusted will not have the 'U' letter at the
forth column, so you just pick the one you want and tell aptitude to
install. Our example above has different versions coming from trusted
sources.
</p>
<p>
Notice that almost always, when you see three or more dashes you can
press <tt>Enter</tt> to have it expand. It will then become something
like <tt>--\</tt>. You now have plenty of information on this package,
like what packages it depends on and which it conflicts<footnote>a
package which conflicts with another one or with a specific version of
another package cannot be installed at the same time as that package
or package version</footnote>, for example.
</p>
<p>
Also notice that at the end of the screen (you can go down using the
arrow keys or page down) you'll find the different <tt>Versions</tt>
available for that package. The <package>xterm</package> package
has two available versions for me, because I have more than one
APT source providing it at different versions.
</p>
<p>
You can install the version you want by pressing "<tt>+</tt>" on
it. Remeber that you need to ask <prgn>aptitude</prgn> to proceed
with the marks you have made. You do that by pressing "<tt>g</tt>".
<prgn>Aptitude</prgn> will then show a list of actions it's going
to perform where you can see if it is doing what you want:
</p>
<p>
<example>
--\ Packages being automatically installed to satisfy dependencies
ciA calctool                                                &lt;none&gt;     4.3.16-2
--\ Packages being held back
ih  libgnomeprintui2.2-0                                   2.4.0-1     2.4.2-1
--\ Packages to be installed
pi  gwget2                                                  &lt;none&gt;     0.7-3
--\ Packages to be removed
ip  qvwm                                                1:1.1.12-1     1:1.1.12-1</example>
</p>
<p>
The entries should be easily understandable. The new thing here is a
package being held back. You can read more about that in <ref
id="holding">.  After checking the changes are the ones you wish
confirm the selections by pressing the "<tt>g</tt>" key again.
</p>
<p>
<prgn>aptitude</prgn> will now start the process of downloading and
installing the packages you have selected.  APT may also start
upgrading any packages that need to be upgraded at this time (see <ref
id="upgrade">).  If you have selected packages from untrusted sources
aptitude will show you a list of those packages and prompt you before
starting to obtain the packages whether you really want to install
them. See <ref id="trustchain"> for more information on secure
sources.
</p>
<p>
If you want to reinstall a package, say, to have files you removed
by accident recovered or something you can press the "<tt>L</tt>"
key to mark it for reinstallation. You'll then go through the same
process as if you were installing it.
</p>
<p>
You can also use <prgn>aptitude</prgn> without the interactive
UI to install or reinstall packages like this:
</p>
<p>
<example>
# aptitude install <var>package1</var> <var>package2</var> ...
# aptitude --reinstall install <var>package1</var> <var>package2</var> ...
</example>
</p>
</sect>

<sect id="manual-install">Installing manually downloaded or locally created debian packages
<p>
If you have downloaded a <tt>.deb</tt> file manually from the internet
or has got a <tt>.deb</tt> from any source other than using APT
you will not be able to use <prgn>aptitude</prgn> or any other APT-based
program to install it.
</p>
<p>
You'll then need to use the underlying package management tool,
which is the one that actually does the hard work of installing
packages -- even aptitude calls this tool for installing: <prgn>dpkg</prgn>.
</p>
<p>
You can install a package by doing:
</p>
<p>
<example>
# dpkg -i <var>file.deb</var>
</example>
</p>
<p>
If you want to use the <tt>unstable</tt> branch of Debian or wishes
to create Debian packages you better learn more about <prgn>dpkg</prgn>!
It's a very powerful tool and has many useful options.
</p>
</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>-</tt>" while having the package
selected on <prgn>aptitude</prgn>. That will mark the package for removal
with a purple-colored line, like this:
</p>
<p>
<example>
id    celestia-gnome                                       1.3.0-1     1.3.0-1
</example>
</p>
<p>
Notice that this will result in a line that looks like this, after the
package is removed:
</p>
<p>
<example>
c    ocaml-base                                             &lt;none&gt;     3.07.2a-1
</example>
</p>
<p>
There's  a  <tt>c</tt>  at  the  beginning of  the  line,  instead  of
a <tt>p</tt>.  This  means that, in my system,  the ocaml-base package
was removed but  the configuration files are still  hanging around. To
remove the  package with its configuration  files you have  to use the
"<tt>_</tt>" key<footnote>The  underscore key, usually  found together
with  the dash,  typeable by  pressing shift  while pressing  the dash
key.</footnote>, instead -- that's called purge.
</p>
<p>
One important note: if you try to remove a package which is a dependency
of an installed package you'll end up having broken packages, as the
top of the aptitude screen shows:
</p>
<p>
<example>
aptitude 0.2.13      #Broken: 1   Will free 208MB of disk space
</example>
</p>
<p>
The broken packages will be marked like this:
</p>
<p>
<example>
iBA   openoffice.org                                       1.1.0-3     1.1.0-3
</example>
</p>
<p>
You can try to solve the brokeness for yourself, by having the ofending
packages removed as well, so that no broken depends are left or ask
<prgn>aptitude</prgn> to proceed, pressing the "<tt>g</tt>" key. It
will then try to fix all the brokeness. If the solution taken by the
program does not satisfy your wishes you can manually fix it before
confirming with "<tt>g</tt>".
</p>
<p>
You can search for broken packages typing "<tt>/</tt>" and using
"<tt>~b</tt>" as search string and pressing <tt>Enter</tt>, you can
then search for the next match using the "<tt>\</tt>" key. You can
search broken packages by simply pressing the "<tt>b</tt>" key, also;
pressing it again will show you the next broken package.  See <ref
id="search"> for more information on finding packages.
</p>
<p>
As usual, you can have packages removed or purged through the
command line interface like this:
</p>
<p>
<example>
# aptitude remove <var>package1</var> <var>package2</var> ...
# aptitude purge <var>package1</var> <var>package2</var> ...
</example>
</p>
</sect>

<sect id="upgrade">Upgrading packages
<p>
Package upgrades are a great success of the APT system.  Aptitude will
automatically mark the packages that have newer versions for upgrade
so all you have to do to upgrade your system is, usually, update the
lists of packages (see <ref id="update">) and then ask
<prgn>aptitude</prgn> to proceed, by typing "<tt>g</tt>" and, after
reviewing the changes, confirming with "<tt>g</tt>", again.  If
aptitude is not marking the upgrades automaticaly you can press the
"<tt>U</tt>" (upper "u") key to ask it to. This is a configuration
option which lives on the <tt>Options-&gt;Misc</tt> menu.
</p>
<p>
You can check the list of packages that have new versions available
looking at the <tt>Upgradable Packages</tt> category:
</p>
<p>
<example>
--\ Upgradable Packages
  --\ libs - Collections of software routines
    --\ main - The main Debian archive
iu    libgnomeprintui2.2-0                                 2.4.0-1     2.4.2-1
</example>
</p>
<p>
Packages marked for upgrade have their lines cyan-colored and have the
character <tt>u</tt> as the action that is going to be performed.
If you want to upgrade to a new release, then take a look at the next
section, <ref id="dist-upgrade">.
</p>
</sect>

<sect id="dist-upgrade">Upgrading to a new release
<p>
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>
<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 <prgn>aptitude</prgn>
to proceed with the instalation, as described above.
</p>
<p>
It's important to note that APT always looks for the most recent
versions of packages, but only after considering the sources'
priorities as we've seen on <ref id="apt:policy">. Consider that and,
if your <tt>/etc/apt/sources.list</tt> lists an archive that has a
more recent version of a package than the version on the CD, APT would
download the package from there, if both sources have the same
priority or the other archive has a higher priority than the one on
CD.
</p>
<p>
If you want to update your system from the Internet you only need to
setup the <file>/etc/apt/sources.list</file> file accordingly.
Upgrading to a new stable release is usually just a matter of running
the normal upgrade process on <prgn>aptitude</prgn>. If your
<file>/etc/apt/sources.list</file> uses the release codename<footnote>For
example, Debian 3.0 was called woody, Debian 3.1 is sarge</footnote>
you'll need to update it to the new name or change it to `stable'.
</p>
<p>
So, for example, this line:
</p>
<p>
<example>
deb http://http.us.debian.org/debian sarge main
</example>
</p>
<p>
Would have to read like one of the following as soon as Etch is
released as stable for the computer to be kept up-to-date with
the current stable system:
</p>
<p>
<example>
deb http://http.us.debian.org/debian etch main
deb http://http.us.debian.org/debian stable main
</example>
</p>
<p>
The difference here is that the first one will keep you at etch
as long as you wish, even if a new stable comes out. This may be
useful if you want to decide when to upgrade to the new stable.
The second example will automatically update your box to the new
stable when it is released.
</p>
</sect>

<sect id="holding">Keeping packages on hold
<p>
As we saw on the previous section, <prgn>aptitude</prgn> will
automatically mark packages for upgrade. If you want to keep the
current version installed, though, you can ask it to put the
package <tt>on hold</tt>.
</p>
<p>
This is achieved by pressing the "<tt>=</tt>" key. Packages being
held from upgrades will look like this:
</p>
<p>
<example>
ih    alien                                                   8.41     8.41
</example>
</p>
<p>
In this example, the <package>alien</package> package will be kept
at version 8.41 even if a new version appears on an APT source --
notice the <tt>h</tt> character at the left. To have it 
upgraded/upgradable again just mark it for installation.
</p>
<p>
You can put packages on hold using the command line interface, too,
by running:
</p>
<p>
<example>
# aptitude hold <var>package1</var> <var>package2</var> ...
</example>
</p>
</sect>

<sect id="clean">Removing unused package files: 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>
<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</prgn>'s <tt>clean</tt> and <tt>autoclean</tt> methods.
</p>
<p>
The clean method is invoked through the <tt>Clean package cache</tt>
menu item in the Actions menu. It is used to delete all the <tt>.deb</tt>
files downloaded. The autoclean method is invoked through the <tt>Clean 
obsolete files</tt> option, also in the Actions menu.
</p>
<p>
The autoclean method is to be used by those who like to keep a local
copy of the packages currently installed, mostly. It only deletes those
<tt>.deb</tt> files which are no longer provided by any APT source
and are, thus, obsoleted by a newer version.
</p>
</sect>
</chapt>

<chapt id="sourcehandling">Building from source
<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. Building from source may also
be useful if you want to enable features that are disabled in the
official package, or disable some which is enabled. 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>
<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>
<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>
<p>
Aptitude, the Debian Package Manager is mainly targeted at binary
packages. To use source packages we'll need to use <prgn>apt-get</prgn>
instead. To download a source package, you would use the following command:
</p>
<p>
<example>
$ apt-get source packagename
</example>
</p>
<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 debian-native
packages, the last of these is not downloaded and the first usually 
won't have <tt>"orig"</tt> in the name.
</p>
<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>
<p>
To auto-build the package when it's been downloaded, just add
<tt>-b</tt> to the command line, like this:
</p>
<p>
<example>
$ apt-get -b source packagename
</example>
</p>
<p>
If you decide not to create the .deb at the time of the download, you
can create it later by running the following command from within
the directory that was created for the package after downloading:
</p>
<p>
<example>
$ dpkg-buildpackage -rfakeroot -uc -b
</example>
</p>
<p>
Notice that to build most packages you'll need at least the following
packages: <package>devscripts</package>, <package>dpkg-dev</package>,
<package>debhelper</package>, <package>fakeroot</package>, take a look
at <ref id="install"> and install them before proceeding.  Most
packages will also depend on compilation tools, so it may be useful to
install the <package>build-essential</package> package as well.  Other
packages may be needed, take a look at <ref id="build-dep"> for more
information.
</p>
<p>
To install the package built by the commands above one must use the
package manager directly. Take a look at <ref id="manual-install">. A
useful tool is provided by the <package>devscripts</package> package:
<prgn>debi</prgn>. If you run <prgn>debi</prgn> from
inside the source package directory it will look for the
<tt>.changes</tt> file at the parent directory to discover what are
the binary packages the package produces and will run
<prgn>dpkg</prgn> to install all of them. While this is not very
useful if your source package produces conflicting packages, it might
be in most circunstances. Of course you need root powers in order to
perform this.
</p>
<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.
</p>
</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. Some basic packages are also needed, check <ref id="source">
before continuing.
</p>
<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>
<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>
<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 download 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>
<p>
If all you want is checking what packages are needed to build a
given package, there's a <tt>showpkg</tt> method for <prgn>apt-cache</prgn>
command (see <ref id="search">, which will show, among other
informations, the <tt>Build-Depends</tt> line that lists those
packages.
</p>
<p>
<example>
# apt-cache showsrc <var>package</var>
</example>
</p>
</sect>

<sect id="source-debuging">Building a debuging package
<p>
If you want to build a package for debuging purposes to, for
example, report a bug -- or fix one, you can use simple environment
variables that are supported by most Debian packages.
</p>
<p>
To build  a package which  contains unstriped binaries<footnote>Debian
usually strips  all the  binaries and libraries  it ships.  That means
that all the debug symbols  are removed.</footnote> all you need to do
is  prefix it  with  <tt>DEB_BUILD_OPTIONS=nostrip</tt>. Optimizations
can  also make  debuging harder,  so you  can disable  them  by adding
the   <tt>noopt</tt>   string   to  the   DEB_BUILD_OPTIONS   variable
too. Example:
</p>
<p>
<example>
$ DEB_BUILD_OPTIONS="nostrip noopt" dpkg-buildpackage -rfakeroot -uc -b
</example>
</p>
</sect>

<sect id="changing-source">Customizing package build options
<p>
If what you want is to customize the way the package is built
you'll have to go about editing the <file>debian/rules</file> file.
This means: inside the main directory created when the source package
is extracted there will be a <tt>debian</tt> directory, which contains
many files. One of them is special: the <file>rules</file> file.
</p>
<p>
This file is usually a Makefile that has targets to configure, build,
install and create the package. For example, if I want to have
the <package>luola</package><footnote>A very nice ship-fighting
game that lacks network play. Any takers? =)</footnote> built without
sound I can, after downloading and extracting its source edit
the <file>debian/rules</file> file that looks like this:
</p>
<p>
<example>
[...]
configure: configure-stamp
configure-stamp:
	dh_testdir
	# Add here commands to configure the package.
	./configure $(confflags) \
		--prefix=/usr \
		--mandir=share/man \
		--infodir=share/info \
		--datadir=share/games \
		--bindir=games \
		--enable-sound
#		 --enable-sdl-gfx	

	touch configure-stamp
[...]
</example>
</p>
<p>
See the <tt>--enable-sound</tt> switch? If I remove it or replace
it with <tt>--disable-sound</tt> and then rebuild the package using
the technique described on <ref id="source"> I'll have a luola package
that is built with no sound.
</p>
<p>
If you  really want to  work with source  packages on a daily  basis I
would           suggest           reading           the           <url
id="http://www.debian.org/doc/maint-guide/"      name="Debian      New
Maintainers           Guide">          and           the          <url
id="http://www.debian.org/doc/debian-policy/"  name="Debian  Policy">,
mainly.    Other    documentation     available    from    the    <url
id="http://www.debian.org/devel/" name="Debian Developers Corner"> may
be useful too.
</p>
</sect>

<sect id="equivs">But hey, I do not want to use the Debian stuff!
<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 
Transfer Agent). Since you installed something you compiled 
by yourself, the packaging system doesn't know about it.
</p>
<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>
<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 she doesn't know what she is doing.
See <ref id="source"> for more information.
</p>
<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>
<p>
Go to some directory (<file>/tmp</file>, for example) and run:
</p>

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

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

<p>
<example>
Section: misc
Priority: optional
Standards-Version: 3.5.10
 
Package: &lt;enter package name; defaults to equivs-dummy&gt;
Version: &lt;enter version here; defaults to 1.0&gt;
Maintainer: Your Name &lt;yourname@foo.com&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, commaseperated&gt;
Description: &lt;short description; defaults to some wise words&gt;
 long description and info
 .
 second paragraph
</example>
</p>

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

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

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

<p>
Yes, that's all. <package>mutt</package> depends on
<package>mail-transport-agent</package>, that is a virtual
package provided by all MTAs, mta-local "registers" itself
as an mail-transport-agent using the Provides field.
</p>
<p>
The <tt>Conflicts</tt> and <tt>Replaces</tt> fields are needed, too,
so that <prgn>APT</prgn> and <prgn>dpkg</prgn> will understand they
should remove the currently installed MTA package in favour of the new
one you're installing.
</p>
<p>
Now you only need to build the package:
</p>

<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>
<p>
And install the resulting <tt>.deb</tt>. See <ref id="manual-install">.
</p>
<p>
As one can see, there are several uses for <prgn>equivs</prgn>. One
can even create a <tt>my-favorites</tt> package, which depends on
the programs you usually installs, for example. Just free your imagination,
although being carefull.
</p>
<p>
It is important to note that there are example control files in
<file>/usr/share/doc/equivs/examples</file>. Check them out.
</p>
</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>
<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>
<p>
That's what this chapter intends to answer. Let's check out our options.
</p>

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

<p>
<example>
$ aptitude search atari
p   atari-fdisk-cross               - Partition editor for Atari (running on no
p   atari800                        - Atari emulator for X/curses/SDL
p   console-keymaps-atari           - Keymaps for Atari keyboards.
</example>
</p>

<p>
We find several packages related to what we're looking for, together
with brief descriptions. The <tt>p</tt> letter at the begining of the
line is similar to the notation used inside the curses UI aptitude
uses. It means, thus, that the package is not installed. Important to
notice that aptitude only searches package names by default. You can
use all the search options provided by aptitude, which you can
discover by reading the aptitude's User Manual. To search the
descriptions, for example, you could use:
</p>

<p>
<example>
$ aptitude search ~datari 
p   aranym                          - Atari Running on Any Machine
p   atari-fdisk-cross               - Partition editor for Atari (running on no
p   atari800                        - Atari emulator for X/curses/SDL
p   circuslinux                     - The clowns are trying to pop balloons to
p   circuslinux-data                - Data files for circuslinux
p   console-keymaps-atari           - Keymaps for Atari keyboards.
[...]
p   stella                          - Atari 2600 Emulator for SDL & X windows
[...]
</example>
</p>

<p>
Now, that returned many more packages, as we can see. Now that we
found a list of possible solutions to our problem, let's go deeper
into them:
</p>

<p>
<example>
$ aptitude show stella
Package: atari-fdisk-cross
Version: 0.7.1-5
Priority: extra
Section: otherosfs
Maintainer: Roman Hodek &lt;roman@hodek.net$gt;
Uncompressed Size: 106k
Description: Partition editor for Atari (running on non-Atari)
 Atari-fdisk allows you to create and edit the partition table of a disk
 partitioned in Atari format. It supports both the AHDI 5.0 and ICD variations
 of the Atari format. It is an interactive tool with a menu similar to PC
 fdisk, and also supports most options of PC fdisk.
</example>
</p>

<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.  You can also use the <prgn>apt-cache</prgn> program to get
informations like those. If you choose this tool, it will be able to
show multiple versions of a package that are available, for example:
</p>

<p>
<example>
$ apt-cache show muine
Package: muine
Version: 0.5.0-1
Priority: optional
Section: gnome
Maintainer: Link Dupont &lt;link@subpop.net&gt;
Depends: gstreamer-gconf (>= 0.6.4), libatk1.0-0 (>= 1.4.1), libbonobo2-0 (>= 2.4.3), libc6 (>= 2.3.2.ds1-4), libflac4, libgconf2-4 (>= 2.4.0.1), libgdbm3, libglib2.0-0 (>= 2.2.3), libgnomevfs2-0 (>= 2.4.1), libgnomevfs2-common (>= 2.4.1), libgstreamer0.6-0 (>= 0.6.1-2), libgtk2.0-0 (>= 2.2.1), libid3tag0 (>= 0.15.0b), libogg0 (>= 1.1.0), liborbit2 (>= 1:2.8.0), libpango1.0-0 (>= 1.2.1), libvorbis0a (>= 1.0.1), libvorbisfile3 (>= 1.0.1), libxml2 (>= 2.6.7), zlib1g (>= 1:1.2.1), gconf2 (>= 2.4.0), mono-jit (>= 0.30) | cli-virtual-machine, gtk-sharp (>= 0.17), gconf-sharp (>= 0.17), gnome-sharp (>= 0.17)
Architecture: i386
Filename: ./pool/main/m/muine/muine_0.5.0-1_i386.deb
Size: 164314
Installed-Size: 692
MD5sum: 9885f13e5ef4f76b3bf6fe7bb3ea8634
Description: Simple music player
 Muine is an innovative music player. It has a simple interface designed to
 allow the user to easily construct playlists from albums and/or single songs.
 Its goal is to be simply a music player, not to become a robust music
 management application.
 
Package: muine
Priority: optional
Section: gnome
Installed-Size: 492
Maintainer: Link Dupont &lt;link@subpop.net&gt;
Architecture: i386
Version: 0.4.0-8
Depends: gstreamer-gconf (>= 0.6.4), libatk1.0-0 (>= 1.4.1), libbonobo2-0 (>= 2.4.3), libc6 (>= 2.3.2.ds1-4), libflac4, libgconf2-4 (>= 2.4.0.1), libgdbm3, libglib2.0-0 (>= 2.2.3), libgnomevfs2-0 (>= 2.4.1), libgnomevfs2-common (>= 2.4.1), libgstreamer0.6-0 (>= 0.6.1-2), libgtk2.0-0 (>= 2.2.1), libid3tag0 (>= 0.15.0b), libogg0 (>= 1.1.0), liborbit2 (>= 1:2.8.0), libpango1.0-0 (>= 1.2.1), libvorbis0a (>= 1.0.1), libvorbisfile3 (>= 1.0.1), libxml2 (>= 2.6.6), zlib1g (>= 1:1.2.1), gconf2 (>= 2.4.0), mono-jit (>= 0.30) | cli-virtual-machine, gtk-sharp (>= 0.16), gconf-sharp (>= 0.16), gnome-sharp (>= 0.16)
Filename: pool/main/m/muine/muine_0.4.0-8_i386.deb
Size: 139864
MD5sum: e746709ad6a6fcc1e9c46b46b3d6e5b2
Description: Simple music player
 Muine is an innovative music player. It has a simple interface designed to
 allow the user to easily construct playlists from albums and/or single songs.
 Its goal is to be simply a music player, not to become a robust music
 management application.
</example>
</p>

<p>
For more general information about a package, you can use:
</p>

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

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

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

<p>
In summary, we have a range of weapons we can use to find out the name of
a package we want.
</p>
</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>

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

<p>
or:
</p>

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

<p>
Notice that this method only works to find package names of packages
that are installed in your system. You'll have to use
<prgn>auto-apt</prgn> (see <ref id="auto-apt">) or
<prgn>apt-file</prgn> (see <ref id="apt-file">) to search for files on
packages which are not installed. You can also take a look at the <url
id="http://packages.debian.org/" name="http://packages.debian.org/">
website. To list 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>

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

<p>
<example>
$ COLUMNS=132 dpkg -l | grep mozilla
ii  mozilla-browser             0.9.6-7                     Mozilla Web Browser - core and browser
</example>
</p>
</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>, which is included in the package
of same name to find the package name. This is done like this:
</p>

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

<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>
<p>
You can also list the contents of a package, by running:
</p>

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

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

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

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

<sect id="info-web">Information about packages on the Web
<p>
There are lots of web resources with informations about the packages
available in the Debian distribution, most of them directed mainly
towards Debian Developers, but many of them may be useful for users,
too.
</p>
<p>
The <url id="http://packages.debian.org/" name="Debian Packages
Pages"> lets you search for packages that are available on the various
architectures Debian supports and, also, search for the contents of
all the Debian packages. There are information regarding dependencies
and other relationships with packages. There are also links to
download the source package and the binary package for all
architectures. You can use a shortcut like
<tt>http://packages.debian.org/<var>packagename</var></tt> to have quick
access links to a package.  
</p>
<p>
The <url id="http://packages.qa.debian.org/" name="Package Tracking
System"> provides information about what happened to the package
recently, what are the TODO itens, from a Debian maintainers point of
view, provides a summary of bugs reported and some more very useful
information. One of the nice things about the Package Tracking System
is that it lets you "subscribe" to a package to follow all the emails
that the maintainer usually receives about the package. This way you
can follow the development of packages that are crucial for your work
or play. The <tt>http://packages.qa.debian.org/<var>packagename</var></tt>
shortcut works here, as well.
</p>
<p>
Finally, the <url id="http://bugs.debian.org/" name="Bug Tracking
System"> provides information about known bugs in the packages
distributed by Debian. This may be useful for you to find out why
something does not work the way you expected and even find solutions
or work-arounds through the bug logs. Also, read these pages and its
documentation to be able to fill good bug reports for Debian. The
<tt>http://bugs.debian.org/<var>packagename</var></tt> shortcut also works
here, as expected, but the BTS (Bug Tracking System) also accepts
other very useful shortcuts like, for example,
<tt>http://bugs.debian.org/src:<var>packagename</var></tt> to show all bug
reports on all binary packages provided by a given source package.
</p>

</sect>
</chapt>

<chapt id="tricks">Tricks and Techniques
<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 is
available in the package of the same name.  It asks you to install
packages if they're needed, stopping the relevant process and
continuing once the package is installed.
</p>
<p>
What you do, basically, is run:
</p>

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

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

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

<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>
<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>.
</p>
</sect>

<sect id="apt-proxy">Caching packages
<p>
If you are dealing with several machines in a network it might
be useful to have a package caching system, so that you will not
have to download the packages for each machine. This manual will
focus on the <package>apt-proxy</package> package, which does
exactly that. Other solutions exist, like <package>apt-cacher</package>,
though. You may want to try each one to choose the one that best
fits your needs.
</p>
<p>
First of all, install the <package>apt-proxy</package> package. 
It will register itself on <prgn>inetd</prgn> to listen for requests 
on port 9999, you may need to restart the <prgn>inetd</prgn> service.
</p>
<p>
Next you'll want to edit the <file>/etc/apt-proxy/apt-proxy.conf</file>
file. It lists the real servers apt-proxy will use to download the
package lists and packages from. You can use http, ftp and rsync
as transfer methods. The file comes with a default "backend" that
looks like this:
</p>
<p>
<example>
add_backend /debian/                                    \
        $APT_PROXY_CACHE/debian/                        \
        http://ftp.us.debian.org/debian/                \
        http://ftp.de.debian.org/debian/                \
        http://ftp.uk.debian.org/debian/                \
        +ftp.us.debian.org::debian/
</example>
</p>
<p>
This means that whenever a client tries to get something
from /debian/ <prgn>apt-proxy</prgn> will use its cache,
the listed Debian http mirrors and one rsync server, which
is preferred for downloading the package lists (the "+" sign 
means prefered for control files).
</p>
<p>
How, then, a client will use this backend? By adding the
following line at the <file>/etc/apt/sources.list</file>
file at the clients (including the box in which apt-proxy
is installed):
</p>
<p>
<example>
deb http://<var>server</var>:9999/debian/ stable main
</example>
</p>
<p>
The line looks much like a normal line. The difference here is you put
your apt-proxy server where you would normally put an http or ftp
mirror, uses a port value (9999) and then select the backend
(/debian/). After having done all this initial setup update the list
of packages at one of the machines and upgrade it first, so that it
will only download a package one time. After the first machine is
up-to-date update the others.
</p>
<p>
You can use the <prgn>apt-proxy-import</prgn> command to import the
packages that are inside your current APT cache
(<file>/var/cache/apt/archives/</file>) by running
<tt>apt-proxy-import /var/cache/apt/archives</tt>. Notice that you
must have run the update process in at least one client to initiate
the <prgn>apt-proxy</prgn>'s cache before using
<prgn>apt-proxy-import</prgn>.
</p>
<p>
You can learn more about <prgn>apt-proxy</prgn> by reading the
comments that populate the <file>/etc/apt-proxy/apt-proxy.conf</file>
file. To setup http and ftp proxies for <prgn>apt-proxy</prgn> to
use, for example, you will find example configurations at the end
of the file.
</p>
</sect>

<sect id="netselect">Deciding which mirror is the best to include in the sources.list file: netselect, netselect-apt
<p>
A very frequent question, 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>
<p>
To install netselect, as usual:
</p>
<p>
<example>
# aptitude install netselect
</example>
</p>
<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>
<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>
<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>
<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>
<p>
Beginning with the 0.3 version, netselect package includes the
<strong>netselect-apt</strong> script, 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 mirror and will be saved under the current
directory. The following example generates a sources.list of the
stable distribution:
</p>
<p>
<example>
# ls sources.list
ls: sources.list: File or directory not found
# netselect-apt stable
(...)
# ls -l sources.list
sources.list
#
</example>
</p>
<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>
</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>
<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>
<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.
</p>
</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>
<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. Answer to the questions
as you want.
</p>
<p>
The option "Should apt-listchanges be automatically run by apt?" is very
useful cause it shows a list of changes made to each package that's being
installed by apt during an upgrade and lets you analyze them before
continuing. The option "Should apt-listchanges prompt for confirmation after 
displaying changes?" is useful because it asks you wether you want to continue
installation after reading the list of changes. If you say that you don't
want to continue apt-listchanges will return an error and apt will abort
installation.
</p>
<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.
</p>
</sect>
</chapt>

<chapt id="repositories">Being at the other side: creating a repository

<p>
To create a repository you mainly need a set of packages (source
and/or binary) to generate <tt>Packages.gz</tt> and
<tt>Sources.gz</tt> files from them. You may have binary-only packages
in some cases, but be careful not to violate licenses. A GPL'ed
software, for example, needs to have its source distributed along with
the binaries.
</p>

<p>
To do that you need to use the <prgn>apt-ftparchive</prgn> program
which is installed by the <package>apt-utils</package> package. First
of all you collect all your packages in a directory. Let's say, for
example, <file>~/public_html/debian</file>; using that we're going to
be exposing the repository through our http server, already!
</p>

<p>
I can go to that directory and do the following:
</p>

<p>
<example>
$ apt-ftparchive sources . &gt; Sources
$ apt-ftparchive packages . &gt; Packages
$ gzip -c Packages &gt; Packages.gz
$ gzip -c Sources &gt; Sources.gz
</example>
</p>

<p>
The first two commands scan the directory and its subdirectories of
the directory you specified (<tt>.</tt>, in this case) and prints the
resulting packages list to the standard output, which we're
redirecting to the <tt>Sources</tt> and <tt>Packages</tt> files.
</p>

<p>
If you're using the <tt>file</tt> method to access this repository
the first two lines are enough. If you're using a remote method like
<tt>ftp</tt> or <tt>http</tt>, then you need the compressed versions,
as they're what APT will look for when updating the packages lists.
</p>

<p>
Here are the source lines you could add to your
<file>/etc/apt/sources.list</file> to make APT aware of your
repository now:
</p>

<p>
<example>
# This will only work with local access to the filesystem
deb file:/home/<var>user</var>/public_html/debian/ ./

# This will be useable by people that can access your machine
# with a network connection if you have your http server properly
# configured
deb http://<var>host</var>/~<var>user</var>/debian/ ./
</example>
</p>

<p>
You get the idea. As we called apt-ftparchive at the same directory
the packages were on we can simply provide the full path to where the
packages are and add a <tt>./</tt> at the end.  You can do things
differently, by calling apt-ftparchive with different relative paths
instead of calling it on the same directory in which the packages
are. You can also separate groups of packages as sections like Debian
does. Read the <tt>apt-ftparchive(1)</tt> manpage for more information
and play with the possibilities.
</p>

</chapt>

<chapt id="otheruis">Alternative User Interfaces for managing packages
<p>
Aptitude is what this howto recommends as the main user interface for
managing packages for your Debian system. This is because, as we
stated through the document, aptitude has a set of features that makes
the administrator's life easier.
</p>
<p>
There are, though, other user interfaces, even graphical ones, like
Synaptic or GNOME-APT. In this chapter we're going to go through them.
</p>

<sect id="synaptic">Synaptic
<p>
Synaptic was originaly written by Alfredo Kojima for Conectiva. Today
it's maintained by people from both Conectiva and Debian. It was
originaly written in wing, Window Maker's graphical toolkit, but was
rewritten in GTK+.
</p>
<p>
To use Synaptic you have to install the <package>synaptic</package>
package.
</p>
<p>
Synaptic is probably the most usable of all the graphical user
interfaces for APT, the one the end users will most likely have less
problems with.
</p>
</sect>

<sect id="gnome-apt">GNOME-APT
<p>
GNOME-APT was first written by Havoc Pennington and Diego Lages for
the Debian system. It was unmaintained for some time but people
managed to keep it alive for Woody. For Sarge the package gained a new
maintainer that took it forward. As oposed to Synaptic, GNOME-APT
is for those people who, while enjoying a nice Gtk+ interface, like
flexibility over usability.
</p>
<p>
You can use GNOME-APT by installing the <package>gnome-apt</package>
package.
</p>
</sect>


</chapt>

<chapt id="errors">How to deal with errors
<sect id="common-errors">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>
<p>
If you receive a message that looks like the one below when trying to
run <tt>apt-get install package</tt>...
</p>

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

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

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

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

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

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

<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>:
</p>

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

</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>
<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>
<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.
</p>
</sect>
</chapt>

<chapt id="distros">What distributions support APT?
<p>
Here are the names of some of the distributions that use APT:
</p>
<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>
<p>
Mandriva 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>
<p>
Libranet (<url id="http://www.libranet.com" name="http://www.libranet.com">)
</p>
<p>
Mandriva (<url id="http://www.mandriva.com/" name="http://www.mandriva.com/">)
</p>
<p>
PLD (<url id="http://www.pld.org.pl" name="http://www.pld.org.pl">)
</p>
<p>
Vine (<url id="http://www.vinelinux.org" name="http://www.vinelinux.org">)
</p>
<p>
APT4RPM (<url id="http://apt4rpm.sf.net" name="http://apt4rpm.sf.net">)
</p>
<p>
Alt Linux (<url id="http://www.altlinux.ru/" name="http://www.altlinux.ru/">)
</p>
<p>
Red Hat (<url id="http://www.redhat.com/" name="http://www.redhat.com/">)
</p>
<p>
Sun Solaris (<url id="http://www.sun.com/" name="http://www.sun.com/">)
</p>
<p>
SuSE (<url id="http://www.suse.de/" name="http://www.suse.de/">)
</p>
<p>
Ubuntu (<url id="http://www.ubuntulinux.com/" name="http://www.ubuntulinux.com/">)
</p>
<p>
Yellow Dog Linux (<url id="http://www.yellowdoglinux.com/"
name="http://www.yellowdoglinux.com/">)
</p>
</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>
<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>
<p>
And special thanks to:
</p>
<p>
Yooseong Yang &lt;yooseong@debian.org&gt;
</p>
<p>
Michael Bramer &lt;grisu@debian.org&gt;
</p>
<p>
Bryan Stillwell &lt;bryan@bokeoa.com&gt;
</p>
<p>
Pawel Tecza  &lt;pawel.tecza@poczta.fm&gt;
</p>
<p>
Hugo Mora &lt;h.mora@melix.com.mx&gt;
</p>
<p>
Luca Monducci &lt;luca.mo@tiscali.it&gt;
</p>
<p>
Tomohiro KUBOTA &lt;kubota@debian.org&gt;
</p>
<p>
Pablo Lorenzzoni &lt;spectra@debian.org&gt;
</p>
<p>
Steve Langasek &lt;vorlon@netexpress.net&gt;
</p>
<p>
Arnaldo Carvalho de Melo &lt;acme@conectiva.com.br&gt;
</p>
<p>
Erik Rossen &lt;rossen@freesurf.ch&gt;
</p>
<p>
Ross Boylan &lt;RossBoylan@stanfordalumni.org&gt;
</p>
<p>
Matt Kraai &lt;kraai@debian.org&gt;
</p>
<p>
Aaron M. Ucko &lt;ucko@debian.org&gt;
</p>
<p>
Jon &Aring;slund &lt;d98-jas@nada.kth.se&gt;
</p>
<p>
Isaac Jones &lt;ijones@syntaxpolice.org&gt;
</p>
</chapt>

<chapt id="novas">New versions of this tutorial
<p>
This manual was created by the <url id="http://www.debianbrasil.org"
name="Debian Brasil"> project, with the goal of aiding everyday use of
Debian.
</p>
<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>
<p>
Comments and criticisms can be sent to me directly be email at
<email>kov@debian.org</email> or filed as a bug on the Debian
BTS on package <package>apt-howto</package>.
</p>
</chapt>

</book>

</debiandoc>