This manual is licensed under the terms of the GNU FDL (Free Documentation License). It has been written in the hope that it will be useful to the community but it comes with no warranty; use it at your own risk. Introduction

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

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.

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. Basic Configuration The /etc/apt/sources.list file

As part of its operation, APT uses a file that lists the 'sources' from which packages can be obtained. This file is /etc/apt/sources.list.

The entries in this file normally follow this format: deb http://site.http.org/debian distribution section1 section2 section3 deb-src http://site.http.org/debian distribution section1 section2 section3 Of course, the above entries are fictitious and should not be used. The first word on each line, deb or deb-src, indicates the type of archive: whether it contains binary packages (deb), that is, the pre-compiled packages that we normally use, or source packages (deb-src), which are the original program sources plus the Debian control file (.dsc) and the diff.gz containing the changes needed for `debianizing' the program.

We usually find the following in the default Debian sources.list: # See sources.list(5) for more information, especialy # 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 These are the lines needed by a basic Debian install. The first deb line points to the official archive, the second to the non-US archive and the third to the archive of Debian security updates.

The two last lines are commented out (with a `#' in front), so apt-get will ignore them. These are deb-src lines, that is, they point to Debian source packages. If you often download program sources for testing or recompiling, uncomment them.

The /etc/apt/sources.list file can contain several types of lines. APT knows how to deal with archives of types http, ftp, file (local files, e.g., a directory containing a mounted ISO9660 filesystem) and ssh, that I know of. How to use APT locally

Sometimes you have lots of packages .deb that you would like to use APT to install so that the dependencies would be automaticaly solved.

To do that create a directory and put the .debs you want to index in it . For example: mkdir /root/debs So, inside the directory /root, create an empty file, with any name. That is because an APT repository needs a file known as "override", it may be empty, but it has to exist. One may use the following command to create this file: touch file Inside this file you may want to define some options to override the ones the ones that come with the package. It looks like follows: package priority section package is the name of the package, priority is low, medium or high and section is the section to which it belongs. It is enough to leave the file empty.

Still in the /root directory do: dpkg-scanpackages debs file | gzip > debs/Packages.gz In the above line, file is the "override" file, the command generates a file debs/Packages.gz that contains various informations about the packages, which are used by APT. To use the packages, finally, add: deb file:/root debs/ 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 .orig.tar.gz, .dsc and .diff.gz in the directory and you have to use Sources.gz instead of Packages.gz. The program used is also different. It is dpkg-scansources. The command line will look like this: dpkg-scansources debs | gzip > debs/Sources.gz Notice that dpkg-scansources doesn't need an "override" file. The sources.list's line is: deb-src file:/root debs/ Deciding which mirror is the best to include in the sources.list file: netselect, netselect-apt

A very frequent doubt, mainly among the newest users is: "which Debian mirror to include in sources.list?". 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: netselect.

To install netselect, as usual: apt-get install netselect 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: bash$ netselect ftp.debian.org http.us.debian.org ftp.at.debian.org download.unesp.br ftp.debian.org.br 365 ftp.debian.org.br bash$ This means that, from the mirrors included as parameters to netselect, ftp.debian.org.br 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).

Now, just put the fastest mirror found by netselect in the /etc/apt/sources.list file (see ) and follow the tips in .

Note: the list of mirrors may always be found in the file .

Beginning with the 0.3 version, netselect package includes the netselect-apt script, which makes the process above automatic. Just enter the distribution tree as parameter (the default is stable) and the sources.list 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: bash$ ls sources.list ls: sources.list: File or directory not found bash$ netselect-apt stable (...) bash$ ls -l sources.list sources.list bash$ Remember: the sources.list file is generated under the current directory, and must be moved to the /etc/apt directory.

Then, follow the tips in . Adding a CD-ROM to the sources.list file

If you'd rather use your CD-ROM for installing packages or updating your system automatically with APT, you can put it in your sources.list. To do so, you can use the apt-cdrom program like this: apt-cdrom add 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: -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 For example: apt-cdrom -d /home/kov/mycdrom add You can also identify a CD-ROM, without adding it to your list: apt-cdrom ident Note that this program only works if your CD-ROM is properly configured in your system's /etc/fstab. Managing packages Updating the list of available packages

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

To update this list, you would use the command apt-get update. This command looks for the package lists in the archives found in /etc/apt/sources.list; see for more information about this file.

It's a good idea to run this command regularly to keep yourself and your system informed about possible package updates, particularly security updates. Installing packages

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 apt-get to get your desired package installed. For example, you can run: apt-get install xchat 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 sources.list. 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: [root]@[/] # 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] The package nautilus 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 apt-get 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.

This means that APT only asks for confirmation when it needs to install packages which weren't specified on the command line.

The following options to apt-get may be useful: -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 Multiple packages may be selected for installation in one line. Files downloaded from the network are placed in the directory /var/cache/apt/archives for later installation.

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: [root]@[/] # 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] See section for more details on package removal.

If you somehow damage an installed package, or simply want the files of a package to be reinstalled with the same version, you can use the --reinstall option like so: [root]@[/] # 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] The version of APT used in the creation of this manual is version 0.5.3, which was the current version in Debian `unstable' (sid) at the time of writing. If you have this version installed, you have additional functionality at your disposal: you can use a command of the form apt-get install package/distribution to install a package from a specific distribution, or apt-get install package=version. For example: apt-get install nautilus/unstable will install nautilus from the `unstable' distribution even if you are running `stable'. The accepted values for 'distribution' are stable, testing, and unstable.

You may prefer to use the -t switch to select a target distribution, leading apt-get to favor that distribution when resolving dependencies.

IMPORTANT: 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 not be used by inexperienced users or by those who need proven stability.

The `testing' distribution is a little better than `unstable' with regards to stability, but for production systems one should use the stable distribution. Removing packages

If you no longer want to use a package, you can remove it from your system using APT. To do this just type: apt-get remove package. For example: [root]@[/] # 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] 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.

Running apt-get 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: [root]@[/] # 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] Note the '*' after the names. This indicates that the configuration files for each of these packages will also be removed.

Just as in the case of the install method, you can use a symbol with remove to invert the meaning for a particular package. In the case of removing, if you add a '+' right after the package name, the package will be installed instead of being removed. [root]@[/] # 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] Note that apt-get 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). Upgrading packages

Package upgrades are a great success of the APT system. They can be achieved with a single command: apt-get upgrade. 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 apt-get dist-upgrade is preferred; see section for more details.

It's useful to run this command with the -u 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 apt-get update before you try this. See section . Look at this example: [root]@[/] # 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] The process is very simple. Note that in the first few lines, apt-get says that some packages were kept back. 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).

There's no clean solution for this first case. For the second case, it's sufficient to run apt-get install for the specific package in question, as this will download the dependencies. An even cleaner solution is to use dist-upgrade. See section . Upgrading to a new release

This feature of APT allows you to upgrade an entire Debian system at once, either through the the Internet or from a new CD (purchased or downloaded as an ISO image).

It is also used when changes are made to the relationships between installed packages. With apt-get upgrade, these packages would be kept untouched (kept back).

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 apt-cdrom (see section ) to add the CD to your /etc/apt/sources.list and run apt-get dist-upgrade.

It's important to note that APT always looks for the most recent versions of packages. Therefore, if your /etc/apt/sources.list 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.

In the example shown in section , we saw that some packages were kept back. We'll solve this problem now with the dist-upgrade method: [root]@[/] # 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] 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 kept back. It probably has a more serious problem than a new dependency. We can find out by running: [root]@[/] # 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] As noted in the above, lilo has a new conflict with the package debconf-tiny, which means it couldn't be installed (or upgraded) without removing debconf-tiny. Using APT with dselect

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

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 `dselect' 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.

To gain a better understanding of dselect's usage, read the dselect documentation found on the Debian page .

After making your selections with dselect, use: apt-get -u dselect-upgrade as in the example below: [root]@[/] # 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] Compare with what we see when running apt-get dist-upgrade on the same system: [root]@[/] # 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] 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. How to keep a mixed system

People often use the testing distribution because it is more stable than unstable and more up-to-date than stable. However, users who would like to run the latest versions of some packages but still rather not trust their entire systems to unstable also have the option of running mixed testing/unstable systems. On the flip side, more conservative users may wish to run mixed stable/testing systems.

To do that, put the following line on /etc/apt/apt.conf: APT::Default-Release "testing";

Then, when going to install packages from unstable, just use the -t switch: # apt-get -t unstable install packagename How to upgrade packages from specific versions of Debian

apt-show-versions 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: # apt-get install `apt-show-versions -u -b | grep unstable` How to keep specific versions of packages installed (complex)

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.

Using this resource is simple. You just need to edit the file /etc/apt/preferences.

The format is simple: Package: <package> Pin: <pin definition> Pin-Priority: <pin's priority>

For example, to keep package sylpheed that I have modified to use "reply-to-list" at version 0.4.99, I add: Package: sylpheed Pin: version 0.4.99* Note that I used an * (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.

The Pin-Priority field is optional; if not specified, it defaults to 989.

Let's take a look at how pin priorities work. A priority lower than 0 indicates that the package should never be installed. Priorities 0 to 100 denote packages that are not installed and that have no available versions. These won't come into the version-choosing process. Priority 100 is the priority assigned to an installed package - for the installed version of a package to be replaced by a different version, the replacement must have a priority greater than 100.

Priorities above 100 indicate that a package should be installed. Typically, the installed version of a package is changed only to upgrade it to a newer version. Any priority between 100 and 1000 (inclusive) indicates this typical behavior. A package with such a priority will not downgrade to an available version with a lower version number. For instance, if I have sylpheed 0.5.3 installed and define a pin on sylpheed 0.4.99 with priority 999, package 0.4.99 will not be installed to satisfy the pin. To make a package "downgradable", to satisfy the pin, it needs possess a priority greater than 1000.

This concept of downgrading can have powerful applications; suppose that you just upgraded your stable version of Debian to the testing one but wanted to retract that decision - perhaps testing just wasn't "tested" enough to suit you. You can define a default pin, using a wildcard for the package name, to come back to stable. For example: Package: * Pin: release a=stable Pin-Priority: 1001

After that, a apt-get -u dist-upgrade will downgrade your system to the stable version.

A pin can be specified on a package's version, release or origin.

Pinning on a version, as we have seen, supports literal version numbers as well as wildcards to specify several versions at one time.

Option release 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 /var/lib/apt/lists/. The paramters for a release are: a (archive), c (components), v (version), o (origin) and l (label).

An example: Package: * Pin: release v=2.2*,a=stable,c=main,o=Debian,l=Debian Priority: 1001 In this example, we chose version 2.2* of Debian (which can be 2.2r2, 2.2r3 -- this accomodates "point releases" that typically include security fixes and other very important updates), the stable repository, section main (as opposed to contrib or non-free) 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: $ 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 Very useful helpers How to install locally compiled packages: equivs

Sometimes, people want to use an 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. Since you installed something you compiled by yourself, the packaging system doesn't know about it.

That's where equivs enters the scene. To use it, install the package with that name. What it does is creating and empty package that is able to fullfill dependencies, making the packaging system believe that the dependencies are satisfied.

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 for more information.

Let's continue with the MTA example, you just installed your new compiled postfix and goes on for installing mutt. Suddenly you discover that mutt wants to install another MTA. But you already have yours.

Go to some directory (/tmp, for example) and run: # equivs-control name Replace name for the name of the control file you want to create. The file will be created as follows: Section: misc Priority: optional Standards-Version: 3.0.1 Package: <enter package name; defaults to equivs-dummy> Version: <enter version here; defaults to 1.0> Maintainer: <your name and email address; defaults to username> Pre-Depends: <packages> Depends: <packages> Recommends: <packages> Suggests: <package> Provides: <(virtual)package> Architecture: all Copyright: <copyright file; defaults to GPL2> Changelog: <changelog file; defaults to a generic changelog> Readme: <README.Debian file; defaults to a generic one> Extra-Files: <additional files for the doc directory, commaseperated> Description: <short description; defaults to some wise words> long description and info . second paragraph 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: Section: misc Priority: optional Standards-Version: 3.0.1 Package: mta-local Provides: mail-transport-agent Yes, that's all. mutt depends on mail-transport-agent, that is a virtual package provided by all MTAs, I could simply name the package mail-transport-agent, but I prefered to use the virtual package's schema, using Provides.

Now you only need to build the package: # equivs-build name 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 `name' in `../name_1.0_all.deb'. The package has been created. Attention, the package has been created in the current directory, And install the resulting .deb.

As one can see, there are several uses for equivs. One can even crate a my-favorites package, which depends on the programs you usually installs, for example. Just free your imagination, but be carefull.

It is important to note that there are example control files in /usr/share/doc/equivs/examples. Check them out. Removing unused locale files: localepurge

Many Debian users use only one locale. A Brazilian Debian user, for example, usually uses the pt_BR locale all the time and doesn't care about the es one.

localepurge is a very useful tool for these users. You can free lots of space by having only the locales that you really use. Just apt-get install localepurge.

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. How to know what packages may be upgraded

apt-show-versions is a program that shows what packages in the system may be updated and several useful informations. The -u option displays a list of upgradeable packages: $ 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 Getting information about packages.

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.

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?

We have a number of resources for such a task. We'll begin with apt-cache. 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. Discovering package names

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: [root]@[/] # 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 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: [root]@[/] # apt-cache show stella Package: stella Priority: extra Section: non-free/otherosfs Installed-Size: 830 Maintainer: Tom Lear <tom@trap.mtview.ca.us> Architecture: i386 Version: 1.1-2 Depends: libc6 (>= 2.1), libstdc++2.10, xlib6g (>= 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 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: [root]@[/] # apt-cache show lilo Package: lilo Priority: important Section: base Installed-Size: 271 Maintainer: Russell Coker <russell@coker.com.au> Architecture: i386 Version: 1:21.7-3 Depends: libc6 (>= 2.2.1-2), debconf (>=0.2.26), logrotate Suggests: lilo-doc Conflicts: manpages (<<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 <vincent@debian.org> Version: 1:21.4.3-2 Depends: libc6 (>= 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. 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: [root]@[/] # 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: And to just find out what packages it depends on: [root]@[/] # apt-cache depends penguin-command penguin-command Depends: libc6 Depends: libpng2 Depends: libsdl-mixer1.1 Depends: libsdl1.1 Depends: zlib1g In summary, we have a range of weapons we can use to find out the name of a package we want. Using dpkg to find package names

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 ".h" file you need for compilation you can run: [root]@[/] # 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 or: [root]@[/] # dpkg -S /usr/include/stdio.h libc6-dev: /usr/include/stdio.h 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: [root]@[/] # dpkg -l | grep mozilla ii mozilla-browse 0.9.6-7 Mozilla Web Browser The problem with this command is that it can "break" the package name. In the example above, the full name of the package is mozilla-browser. To fix this, you can use the COLUMNS environment variable this way: [kov]@[couve] $ COLUMNS=132 dpkg -l | grep mozilla ii mozilla-browser 0.9.6-7 Mozilla Web Browser - core and browser or the description or part of it this way: [root]@[/] # apt-cache search "Mozilla Web Browser" mozilla-browser - Mozilla Web Browser How to install packages "on demand"

You're compiling a program and, all of a sudden, boom! There's an error because it needs a .h file you don't have. The program auto-apt 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.

What you do, basically, is run: auto-apt run command Where `command' is the command to be executed that may need some unavailable file. For example: auto-apt run ./configure 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.

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 auto-apt update, auto-apt updatedb and auto-apt update-local. How to keep informed about the changes in the packages.

Every package installs in its documentation directory (/usr/share/doc/packagename) a file called changelog.Debian.gz which contains the list of changes made to the package since the last version. You can read these files with zless' help, for example, but it is something not so easy, after an complete system upgrade, to start searching changelogs for every upgraded package.

There's a way to automatize this task by means of a tool called apt-listchanges. To begin with one needs to install the apt-listchanges package. During the package installation, Debconf will configure it. Answer to the questions as you want.

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.

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. Working with source packages Downloading source packages

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.

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.

To accomplish this, the deb-src entry in your /etc/apt/sources.list should be pointed at unstable. It should also be enabled (uncommented). See section .

To download a source package, you would use the following command: apt-get source packagename This will download three files: a .orig.tar.gz, a .dsc and a .diff.gz. In the case of packages made specifically for Debian, the last of these is not downloaded and the first usually won't have "orig" in the name.

The .dsc file is used by dpkg-source for unpacking the source package into the directory packagename-version. Within each downloaded source package there is a debian/ directory that contains the files needed for creating the .deb package.

To auto-build the package when it's been downloaded, just add -b to the command line, like this: apt-get -b source packagename If you decide not to create the .deb at the time of the download, you can create it later by running: dpkg-buildpackage -rfakeroot -uc -b from within the directory that was created for the package after downloading.

There's a difference between apt-get's source method and its other methods. The source method can be used by normal users, without needing special root powers. The files are downloaded to the directory from which the apt-get source package command was called. Packages needed for compiling a source package

Normally, specific headers and shared libraries need to be present in order for a source package to be compiled. All .deb 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.

APT has a simple way of downloading these packages. Just run apt-get build-dep package, where `package' is the name of the package you're going to build. For example: [root]@[/] # 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] The packages that will be installed are the packages needed in order for gmc 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 apt-get source separately to get it. How to deal with errors Common errors

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.

If you receive a message that looks like the one below when trying to run apt-get install package... 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 you forgot to run apt-get update after your last change to the /etc/apt/sources.list file.

If the error looked like: 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? when trying any apt-get method other than source, you don't have root permission, that is, you're running as a normal user.

There's an error similar to the above which happens when you run two copies of apt-get at the same time, or even if you try to run apt-get while a dpkg process is active. The only method that can be used simultaneously with others is the source method.

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: # apt-get -f install # dpkg --configure -a 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'. Where can I find help?

If you find yourself plagued by doubts, consult the extensive documentation available for the Debian packaging system. --help's and manpages can be an enormous help to you, as can the documentation contained in the /usr/share/doc directories such as /usr/share/doc/apt.

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

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. What distributions support APT?

Here are the names of some of the distributions that use APT:

Debian GNU/Linux () - it was for this distribution that APT was developed

Conectiva () - this was the first distribution to port APT for use with rpm

Mandrake ()

PLD ()

Vine ()

APT4RPM () Credits

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

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.

And special thanks to:

Yooseong Yang <yooseong@debian.org> - for translating the manual to Korean.

Michael Bramer <grisu@debian.org> - for the suggesting the inclusion of the section about keeping specific versions.

Bryan Stillwell <bryan@bokeoa.com> - for the various patches and corrections he sent to me.

Pawel Tecza <pawel.tecza@poczta.fm> - for the various corrections he sent and for the Polish translation.

Pablo Lorenzzoni <spectra@debian.org> - for writing the section about netselect.

Steve Langasek <vorlon@netexpress.net> - for translating the manual to English.

Arnaldo Carvalho de Melo <acme@conectiva.com.br> - for contributing the list of additional distributions that now include APT: Mandrake, PLD and Vine.

Erik Rossen <rossen@freesurf.ch> - for the tip on the COLUMNS variable for dpkg -l.

Ross Boylan <RossBoylan@stanfordalumni.org> - for the tip on using -o Debug::pkgProblemResolver=yes.

Matt Kraai <kraai@debian.org> - for the various patches and corrections he sent to me.

Aaron M. Ucko <ucko@debian.org> - for the proof reading and corrections. New versions of this tutorial

This manual was created for the project, with the goal of aiding everyday use of Debian.

New versions of this document will be made available in the project's page, at .

Comments and criticisms can be sent to me directly be email at kov@debian.org.