D.1. The apt system

D.1. The apt system
	Appendix D. Alan's quickstart guide to Debian for programmers.

[ fromfile: debian-tips.xml id: aptsystem ]

The apt system is a way of managing packages and their dependencies. The following programs can be used to manage your apt-based package library.

apt-get - a convenience program that makes it easy to get and update your packages.
dpkg - a lower layer of software - many simple apt commands are translated into more complex commands and executed by dpkg.
apt-cache - a tool to help you search through the local “apt” package info database.
aptitude - apt-get with a little more intelligence - it can be used to get and remove packages when apt fails. It is another convenience layer on top of dpkg.

This section contains some handy tips for developers who want to take the most advantage possible out of the apt system.

	/etc/apt/sources.list
	This file contains a list of sources that apt checks for packages. There are two things you should do with this sources list after a new install.

Fix your main mirrors so they point to a local mirror instead of a remote one. There are many ways to do this, but the most user-friendly way is to run apt-setup.
Optional: set the sources to “unstable” (debian) or “edgy” (kubuntu) if you want the latest and greatest versions of everything. ^[83]

apt-get update

This downloads the package lists from your package sources, so that you have a local copy of the lists, dependency relationships, and descriptions in your own dpkg database.

What's out there? apt-cache search qt4

	What's out there? apt-cache search qt4
Sometimes you know you want a package but the exact name escapes you. This command searches through the locally downloaded package list for occurances of a string in the name or description and tells you what software is available for easy network installation via your current sources. To read the description of one package fully, `apt-cache show libqt4-dev`.

Sometimes you know you want a package but the exact name escapes you. This command searches through the locally downloaded package list for occurances of a string in the name or description and tells you what software is available for easy network installation via your current sources.

To read the description of one package fully, apt-cache show libqt4-dev.

Installing packages

apt-get install packageName. This is one of the most powerful commands you have, and it's only available if you have root on a debian system. To save you time, I've listed a few of my favorite packages, ones which I always install on any new Debian desktop that I plan to do development on.

To save you time, I've listed a few of my favorite packages, ones which I always install on any new Debian system I plan to use for development.

apt-get install aptitude # an improved apt
apt-get install bzip2
apt-get install cvs subversion kdesvn subversion-tools tailor # source control tools
apt-get install openssh-server  # sshd
apt-get install doxygen doxygen-doc doxygen-gui # api docs generator
apt-get install graphviz # used by doxygen for diagrams
apt-get install xsltproc docbook-xml docbook-xsl
apt-get install amarok # jukebox similar to iTunes

# Database Stuff
apt-get install mysql-server mysql-client libmysqlclient15-dev
apt-get install sqlite3 libsqlite3-dev
apt-get install unixodbc unixodbc-dev

# For development
apt-get install build-essential manpages-dev # manual pages for stdlib
apt-get install libstdc++6-dev
apt-get install c++-annotations  libstdc++6-doc # documentation for C++ and standard library
apt-get build-dep libqt4-dev # all dependencies required to build qt4 from source
apt-get install libqt4-dev libqt4-sql qt4-dev-tools qt4-doc libqt4-core libqt4-gui
apt-get install libid3-3.8.3-dev # Fast library for manipulating id3 tags
apt-get install eric  # Python IDE
apt-get install gdb # gnu debugger
apt-get install global cscope exuberant-ctags   # For C++ development - navigation (used by jEdit)
apt-get install umbrello # UML Diagramming tool that reads/writes XMI and imports C++ source
apt-get install ncurses-base ncurses # need this for kernel make menuconfig
apt-get install sun-java6-jre # For installing jedit

apt-get (dist-|dselect-)upgrade

As time goes on, new packages are made available in your repository. When you want to upgrade your system, it is appropriate to do a dist-upgrade. When you want to give apt permission to remove what are probably obsolete packages in favor of newer ones, use dselect-upgrade (which is similar but not exactly the same as what aptitude upgrade does).

	apt-get source packageName
	Unless you need a very specific version that is not served by your package source, you can grab a copy of the sourcecode in a convenient tarball for any available package by simply asking for it from apt.

	I just installed something - where did it go?
	For this command, we drop down a level into `dpkg` land. `dpkg` is a quite powerful tool in its own right, but most of the time, we use it indirectly via `apt-get`. One useful option is `dpkg -L packageName`. This command will list all the files that were extracted from this package, and show you the locations they are now residing on your system.

apt-get build-dep packageName

	apt-get build-dep packageName
Very often, when compiling large packages of software (such as Qt), you will run into the situation where the build fails due to missing libraries, (or their -dev packages). When I was still learning my way around my first Knoppix system, I was building apps and libraries by following a brute-force iterative process: configure, encounter and examine each error message, try to figure out what library is missing, install it, and repeat until no more errors. Once I learned about `apt-get build-dep`, I realized immediately how much time I could have saved myself, and it was not insignificant! We already know that the apt system is aware of which packages depend on which other packages, but with the `apt-get build-dep packageName` command, apt will automatically download all the dependent libraries and their `-dev` packages, so that you have everything you need to build packageName. In other words, no more tracking down missing header files! To see a list of all dependency relationships between packages, try `apt-cache showpkg packageName`. apt-get build-dep libqt4-dev # grabs what you need to build qt4 from source apt-get build-dep amarok # grabs headers and libs you need to build amarok apt-get source amarok # grabs the source tarball

Very often, when compiling large packages of software (such as Qt), you will run into the situation where the build fails due to missing libraries, (or their -dev packages). When I was still learning my way around my first Knoppix system, I was building apps and libraries by following a brute-force iterative process: configure, encounter and examine each error message, try to figure out what library is missing, install it, and repeat until no more errors. Once I learned about apt-get build-dep, I realized immediately how much time I could have saved myself, and it was not insignificant!

We already know that the apt system is aware of which packages depend on which other packages, but with the apt-get build-dep packageName command, apt will automatically download all the dependent libraries and their -dev packages, so that you have everything you need to build packageName. In other words, no more tracking down missing header files!

To see a list of all dependency relationships between packages, try apt-cache showpkg packageName.

apt-get build-dep libqt4-dev # grabs what you need to build qt4 from source
apt-get build-dep amarok # grabs headers and libs you need to build amarok
apt-get source amarok    # grabs the source tarball

aptitude: when your apt system is broken

	aptitude: when your apt system is broken
Sometimes, you try to install something and not only do you get an error, but apt is left in a state which is invalid. This is quite common when running unstable, less so when using testing. You might be instructed to try `apt-get -f install`, but after trying that, and also trying to remove the offending package, you still are stuck. It is important to read the error message carefully: almost always you will see references to specific package names which are causing the problems. By removing all of them, using `apt-get remove pkg1 pkg2 pkg3` in one line, you can sometimes bring your system back into a valid state. Another way to fix this is by using `aptitude remove pkgN` for each package. Aptitude will help you by finding and removing sets of related packages that are also causing problems.

Sometimes, you try to install something and not only do you get an error, but apt is left in a state which is invalid. This is quite common when running unstable, less so when using testing. You might be instructed to try apt-get -f install, but after trying that, and also trying to remove the offending package, you still are stuck.

It is important to read the error message carefully: almost always you will see references to specific package names which are causing the problems. By removing all of them, using apt-get remove pkg1 pkg2 pkg3 in one line, you can sometimes bring your system back into a valid state.

Another way to fix this is by using aptitude remove pkgN for each package. Aptitude will help you by finding and removing sets of related packages that are also causing problems.

^[83] Ubuntu only: be sure to add a “universe” after main, so that you get the full packages offered by Ubuntu.


Appendix D. Alan's quickstart guide to Debian for programmers.		D.2. update-alternatives