This tutorial intends to teach you how to download, patch, build and install a modified Debian Package. You need very little previous knowledge, but you do need a working Debian distribution and no fear of the command line.

First step: using deb-src

To be able to build a debian package, you will need to have at least one deb-src line in your /etc/apt/sources.list file. This is usually achieved by copying one of the existing deb lines and changing it to deb-src. Here is an example:

   deb-src http://http.us.debian.org/debian unstable main contrib

(usually, it's a good idea to use unstable as the repository, since you'll be working with the latest version of the package, but if you intend to modify a package as it is in stable or testing you could use those distributions as well).

Once you've edited the file, you have to do apt-get update to get the list of sources into apt's cache.

Choosing the package

We are going to download the source of a package and make a little modification to it, so that it works better. You can choose any package of your liking. As an example to go on with the tutorial, I'm going to use the capplets package.

You should install the package (or check if you have it installed and up to the latest version) before proceeding, since you'll need to have the dependencies sorted up when you want to install the modified one. You can do this by doing:

  apt-get install capplets

(or whatever your chosen package is).

Getting the source package

So, the next thing you have to do is go to wherever you want to download this package, I usually download them on ~/sources/debian/ but you can do it wherever you like. Go to your chosen directory and do:

   apt-get source capplets

(or the name of the package you want to modify).

You'll notice that this will download some files and that after it finishes, it tells you the name of the directory created. If you do ls you'll see the new directory and three new files there. The three files are used by dpkg to extract the directory. You'll be interested only in what's inside the directory.

In the case of capplets it's called control-center-2.8.1 (or a different version, if you are doing this at a future date). Why is this? Because capplets is a binary package, generated from the control-center source package (and it's not the only one).

Getting the build dependencies

To build a package, you'll need a lot of build dependencies, usually it's a bunch of packages that end in -dev, but it might also be other things like automake or gcc, depending on how many development tools you've ever installed in that machine.

In any case, it might take a long while to install all the build dependencies, so it's a good idea to do this on a separate window that you might leave there while doing the modifications in the package.

To get the build dependencies you use:

   apt-get build-dep capplets

It will tell you how many MB it needs to download (sorry if it's a lot, this is a GNOME package, and thus has a lot of build dependencies), and you'll have to say Y to it.

Editing the source code

While the build-dep download, you have time to explore the source code you've got from the source package. cd to the package directory and explore a little bit.

Debian packages usually have a debian directory. This is the directory that the package maintainer has added to the source code to build the package, in this directory you'll usually find lots of files related to Debian's version of the program, Debian specific patches, manpages, documentation, and so on.

The rest of the contents are usually part of the upstream source, this is to say, the source that you would have downloaded from the program's webpage, if you didn't have Debian.

When you are trying to fix a package bug, sometimes it will be located in the upstream source, sometimes it will be related to how the program was packaged for Debian. So you'll be editing different files depending on where the problem is.

In the case of capplets the bug is in upstream source. We won't be really fixing it, since the fix is yet (as of Jan 5 2005) unknown, but we'll be preventing it from happening.

You'll have to edit gnome-settings-daemon/gnome-settings-daemon.c and go to the line 279. You have to comment out the lines 279 and 280. In C this is done by putting the commented code between /* and */. As in:

  /* gnome_settings_keyboard_init (client);
     gnome_settings_multimedia_keys_init (client); */

Save the file and that's it, we've modified the source code.

Getting fakeroot

If the build dependencies have finished downloading, you are almost ready to build your modified package. If not, please go and grab some coffee while it finishes.

You'll need to install one extra package, that's not absolutely necessary, but it's cool to have it:

  apt-get install fakeroot

This program lies to the command you invoke and says that you are executing it as root, even if you are executing it as a normal user. You could skip it and actually build the package as root. But why be root when you don't need to?

Building the modified package

Once you have everything in place, you should go and change to the main package directory (in our example control-center-2.8.1) and do:

  fakeroot debian/rules binary

This is a command, almost like make, that builds the package. This command will probably take a while to run, since usually it first has to run ./configure, then it has to compile the source code and then build the packages.

You'll see a lot of gcc output on screen. This is usually not very interesting, unless you are looking for a bug that is related to the compilation of the package itself. Normally, I just let this go while I do something else (grab some cookies for your coffee, for example).

When the build is finished, you'll see the output on screen telling you that certain package (or packages in this case) has been built.

Installing the modified package

Change to the parent directory and you'll find one or more files ending in .deb (in the case of capplets, you would see three .deb packages). Those are the packages that were built. To install these packages you won't use apt, because nothing needs to be downloaded, just installed. So, as root do:

  dpkg -i capplets_2.8.1-3_i386.deb

Or whatever your binary package is called.

Test it

The package is now installed into your system, you should now test it and see if the bug has been fixed by the modifications you've done. If in any case what you've done has made things worst, you can always revert to Debian's version by doing:

  apt-get install capplets --reinstall

If what you've done has improved the way the package behaves, then you should email your results to the BTS (and include a patch if you know how to do it -- this should be the subject of another tutorial).

That's it, get ready for the next package

You've done with modifying the package, you can now keep fixing bugs in other Debian packages! These are the important commands you'll need to remember:

   apt-get source the-package
   apt-get build-dep the-package
   (...)
   fakeroot debian/rules binary
   dpkg -i the-package-blabla.deb

If you want to go on a little bit further in your package making, you can read some of the AdvancedBuildingTips.

Feedback

I hope you enjoyed the tutorial, please send me your feedback if you feel like it, or modify this wiki if you want to add some useful information I might have left out.