Skip navigation

The Debian Project

previous | Contents | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | | next

The Debian Maintenance HOWTO
Chapter 9 - Building Packages

This section covers binary packages and the process to build or rebuild them from proper source packages.

9.1 Source Packages

The Debian distribution comes in form of binary and source packages. While you would only install binary packages, source packages can be of more interest to you. You can learn a lot by reading other peoples code or patches. This can also be important if you want to use the same software on different OSes or want to use a specific Debian patch somewhere else.

A Debian source package usually consists of three files:

A couple of packages are Debian native packages that have no different upstream source. In that case, no .diff.gz but only a .tar.gz will be provided.

9.2 Unpacking the Source on Debian

On a Debian system you will use the command dpkg-source -x file.dsc This will automatically unpack the original source and apply all Debian patches regardless of the source format used. You will find the new source files in a directory named like package-version without the Debian revision in the version string ready for build binary packages.

To create a new source package from an existing source tree (i.e. build new .diff.gz or .debian.tar.gz respectively and .dsc files> the command dpkg-source -b package-version is used.

9.3 Unpacking the Source somewhere

Debian source packages are designed to be extractable by standard utilities that are available on any GNU/Linux (or Unix/POSIX) system. Thus you'd only need gunzip, tar and patch to build a proper Debian source tree. The following steps have to be taken:

  1. Unpack the original tar file (i.e. tar xfz file.orig.tar.gz)

  1. rename the resulting directory to package-version (e.g. hello-1.0). Patch will only work with properly named directories.

  1. Create the directory debian within the new directory

  1. Apply the Debian patch with zcat file.diff.gz| patch -p0. OR change into the package directory and untar the .debian.tar.gz with tar xfz file.debian.gz

  1. Make the file debian/rules executable (i.e. chmod +x)

9.4 Rebuilding

From time to time it makes sense to rebuild a Debian package. If it was uploaded for unstable and you need it on a stable system or if it was uploaded for an architecture you don't have or if you want to modify its source it is useful to rebuild the source.

The most automated way to rebuild a Debian package is achieved by letting the Debian tools work. To do so, move into the new source directory and issue the command dpkg-buildpackage -b.

You can also perform the steps manually by calling debian/rules with proper arguments: 

       make -f debian/rules build
       make -f debian/rules binary

At the end of both commands you'll find a freshly built .deb-file in the upper directory, ready for installation.

9.5 Packaging recent source

Packaging upstream source for Debian that is more recent than the most recent Debian package is one of the easiest tasks. However this will only work if there were no structural changes made in the upstream source. When this applies, you only have to fetch the most recent Debian source tree that build properly on your system and copy the entire debian/-directory into the new upstream source directory.

Once this is done, you have to edit the file debian/changelog which provides the version number and the address of the person who builds the package. It has a very simple structure so you should be able to duplicate it with any text editor. Once duplicated, please edit the first line (version number) and correct the version string. Please use -0.1 as addition so that new Debian packages (which would have -1) will superseed this one. Then edit the mail-address at the end of that item. Now please edit the lines between version and address that contains changelog information. You sould write something like unofficial packages to make sure you'll remember how that package was built.

After that, sipmly continue as if you were rebuilding a package. If you have renamed the upstream tarfile into <package>_<upstream-version>.orig.tar.gz and named the directory like <package>-<upstream-version> after a make -f debian/rules clean even dpkg-source -b should be able to build proper source packages.

9.6 Backporting

When new packages can't be installed on older systems (e.g. the Apache from unstable can't be installed on stable) it is time to backport the package. This may not be as easy as you expect.

For the first trial you can simply unpack the source and try to compile it. If that works, dance and be happy. If not, try to analyse the problem. If it is just due to unsupported programs like dh_*, then install the new debhelper package from unstable. Since it is binary-all (i.e. contains only perl scripts and documentation) this should work. Then try to recompile the package.

If the error message looks like the build system lacks some library routines or requests newer version of a library, try to locate the referring package and the referring -dev package. When trying to find the required library read the section above covering locating packages.

Before installing a -dev package please keep in mind that you can only install one similar -dev package of a certain library (i.e. only one gtk1.1.x-dev package).

When that new library is not installable on your system, you will have to enter a new level of recursion and backport that library first. It is possible that you'll end up in level 10 or so. If so, you may want to re-evaluate your decision not to upgrade the whole system.

9.7 Finding new upstream source

When a Debian package is outdated and you want to try out the new version of if you know that the new version of a certain program provides some functionality that you would like to use and the old package doesn't provide it, you'll need to check for new upstream source packages.

For finding out where to find new upstream source packges, please read /usr/share/doc/<package>/copyright. This file does not only contain copyright information for that particular package but contains an URL from which source packages were fetched as well.

If the file does not contain an upstream source URL or that url is out-dated there are two other common places where software for Linux is likely to be found:

  1. For historical reasons the main archive for Linux Software is ibiblio.org (formerly known as metalab, formerly known as sunsite.unc.edu).

  1. Newardays many new packages are not uploaded to ibiblio anymore but announced on freshmeat instead. They collect URLs and descriptions of packages. If you want to download the files you'll be redirected to the authors archive

9.8 New upstream source

If you want to package a new upstream version of an existing Debian package, you will find that packaging can be quite easy. Nevertheless, you should take a look at the next section (Packaging). Please read carefully what is written about the changelog file since it contains the version number the package will have later.

For packaging a new upstream version of an existing Debian package you'll need to copy the debian/ directory from the most recent Debian source package into the new upstream source tree basically. Using only this you would end up with the same version number, thus you should increase it by editing debian/changelog.

This is done manually by copying the most recent entry in that file and modifying it, by using debian-changelog-mode or by using the dch program from the devscripts package. If you want to let your version be overwritten by a new Debian package you should add -0.1 to the upstream version number. Since Debian packages normally use -1 as revision appendix the Debian version would be considered newer than yours.

If you need to package a source archive that does not yet exist in Debian, the most easiest way would be to use the debian/ directory from an existing package. In this case you should have read the following paragraph and should have some basic knowledge about Debian Packaging.

9.9 Packaging

This section could be larger than the entire document since Debian Packaging can be complex and complicated. However, I don't want to overstress the reader so I will try to keep it short. However#2, if you plan to maintain packages officially (by becoming an official maintainer) please read the documents listed in the Resources section.

9.9.1 Basics

A Debian package consists of source packages and binary packages. All binary packages are automatically built out of the source packages. Please refer to sections above covering unpacking the source and building the package.

All Debian related information and files are placed in the debian/-directory inside of the source directory. Basic files in there are:

These files are the most important ones among others. Please take into account that the version and name of a package are actually extracted from the changelog file. You'll have to increase the version of the top most entry in that file in order to produce a package with a higher version number as before. If you want to build a new package out of pristine source you should at least use the following steps.

If you use debhelper some work will be done by that tool. However, if you use it and it doesn't do what you have expected, don't complain, it was your choice to use it instead of building it manually.

For learning purpose it is always a good idea to look how other packages have managed their build process. Please check out the hello and hello-debhelper packages as well as some random packages like cfingerd or miscfiles.

9.9.2 Developers Resources

If you plan to become an official maintainer for a Debian package you should read all the documents that describe the development process and philosophical background.

Please read these documents carefully. You don't have to bear in mind everything which is written in them. However, you will have to remember where to find what information if you actually need them.

I advise you really to read all those documents before attempting to join the Debian project, it will cause a lot of reading but will help you not to get frustrated during packaging.

The Debian Maintenance HOWTO

November 23rd, 2014

Joey Schulze, joey@infodrom.org

© Infodrom Oldenburg  Datenschutz
Last modified: November 23, 2014