A brief guide to Debian packaging

Note that this is very much a work in progress at the moment and needs a lot of revision.

Whilst building single-binary small programs into Debian packages is normally a simple process of doing

$ dh_make -e j.r.hacker@example.org -s -r
$ dpkg-buildpackage -r

Packaging multiple binaries and libraries requires a little bit more work.

Since I've been mainly packaging libraries lately that is what this guide will describe but it's obvious to see how it can be extended to multiple binary packages and the like. I'll assume the necessary packages are installed (i.e. you have "build-essential" and the deb-helper scripts etc. installed).

Preparing the source

The first step is (obviously) to grab the source via SVN or from a tarball etc. and put it in a folder named according to the format

<package_name>-<version>

So if you were packaging a library called "foo" at version 1.3, and grabbing the source via SVN, you'd likely do

$ svn co http://svn.example.org/foo/tags/1.3 foo-1.3

If you need to run

$ autoreconf -i

to generate the necessary Makefiles, do that now.

Creating the Debian package related files

Now you'll want to create the files related to building the package. Go into the directory that holds your source and do

$ dh_make -e j.r.hacker@example.org -l -r -c gpl

Obviously with your email address, and whichever license the code is under, instead.

You'll now have generated a copy of the original source code (which will be used to create a diff of any changes you make against) in the directory above your source, and a "debian" directory in your source directory. The debian directory is where all the juicy packaging goodness lies, so move to that directory now.

The "debian" directory

This is where we actually tell dpkg everything about what the package will contain and how it should go about building it. The first, and simplest, files to edit are the copyright and changelog files which are self explanatory.

The control file lists the packages that will be created, and gives information on them and their dependencies. You'll want to edit the control file, adding a description for the packages that will be created, and changing the names of the packages to something sensible, in our case we'll want to name them "libfoo" and "libfoo-dev".

Note: Remember to also add any dependencies of the libraries and to change the dependency of libfoo-dev to libfoo rather than fooBROKEN which is the default.

The rules file

Now you'll need to edit the rules file. This is, possibly, the most important file there is when it comes to building a package. The rules file is essentially a makefile that tells dpkg how to configure and build the package.

First change the config.status section to include any flags you would pass to the configure script if you were building it normally, for example

./configure --prefix=/usr --enable-shared --with-bar=/usr/bar

Unless you know exactly what files are going to be built and go where, it's helpful to move back to your sources directory and run

$ dpkg-buildpackage -r

This will actually build an empty package, but you'll see why it's useful if you go back into the debian folder and check the "tmp" directory. You'll see that every file that will eventually be in a package has been built in tmp, as if tmp was the root of the filesystem.

Now you just need to work out which bits will go in each package. As a rule put stuff that would go in /usr/include and files matching /usr/lib/*.la or /usr/lib/*.a in the libfoo-dev package.

Now we know what needs to be in each package, edit the libfoo.dirs, libfoo.install, libfoo-dev.dirs, and libfoo-dev.install files to list the directories that should be created in each package.

Now edit the install section of the rules file. Basically you want to use the mv or cp commands to put the relevant files in the relevant package directory, so to get the files mentioned above into libfoo-dev and everything else in /usr/lib into libfoo you'll want to do something like

# Add here commands to install the package into debian/tmp
   $(MAKE) DESTDIR=$(CURDIR)/debian/tmp install
   mv $(CURDIR)/debian/tmp/usr/include/* \
      $(CURDIR)/debian/libfoo-dev/usr/include/
   mv $(CURDIR)/debian/tmp/usr/lib/*.la \
      $(CURDIR)/debian/libfoo-dev/usr/lib/
   mv $(CURDIR)/debian/tmp/usr/lib/*.a \
      $(CURDIR)/debian/libfoo-dev/usr/lib/
   mv $(CURDIR)/debian/tmp/usr/lib/* \
      $(CURDIR)/debian/libfoo/usr/lib/

Now you're ready to build the package. Move back into the sources directory and do

$ dpkg-buildpackage -r

You'll now have your libfoo and libfoo-dev Debian packages in the directory above your sources directory, along with a tarball of the original source, a diff file with the changes you've made to the source, a .dsc file and the .changes file (which is what you'll want to pass to dupload to upload your packages to whatever repository server).

Updating the package

Say you've noticed a problem with your packaging such that it needs re-packaging, like you missed a certain configure flag before, you'll need to make sure you change the packaging version number of the rebuilt package. To do this simply make the changes to the source or rules file etc. and then make a new entry in the debian/changelog file changing the version number appropriately. So, for example

foo (1.3-2) unstable; urgency=low

  * Fixing a boo-boo.

 -- J. Random Hacker <j.r.hacker@example.org>  \
      Fri, 05 Dec 2008 00:21:36 +0000


foo (1.3-1) unstable; urgency=low

  * Initial release.

 -- J. Random Hacker <j.r.hacker@example.org>  \
      Fri, 05 Dec 2008 00:20:33 +0000

Note: The date should be in the format given by the date -R command.

Then just rebuild the package with

$ dpkg-buildpackage -r

Extending this

It should be fairly easy to see how this can be extended to packaging many different pieces of software just by changing the rules, control, and other files in the debian directory. For instance you may want to create an extra docs package or maybe a utilities package for binaries related to the library by adding the relevant entries in the control file and modifying the install section of the rules file.