Debianization with git-buildpackage

After building some useful piece of software, one has to decide how to best deploy it. In UNIX, the standard way to do that is by publishing the source code in .tar.gz format and requiring users to compile it.

In Debian there is an alternative: using a .deb package. With a .deb package, a single dpkg -i <package>.deb installs the software.

This article explains how to create and support a .deb package for a simple software maintained in git, by tracking the packaging scheme in a specific branch on the same repository.

Prerequisites

In order to ease the packaging and keep our package warning-free, it should have in its main repository:

An AUTHORS file with copyright information.
A manual.
A COPYING file with GPL information or some other license.
A Makefile with the targets "all", "clean" and "install". The "install" target should install the binary in $(PREFIX)/bin and the manual to $(PREFIX)/share/man/man#. PREFIX should be, by default, /usr/local, so that non-debian users can still user our package.
A way to create <package>_<version>.tar.gz (make dist ?). We will use it to import the original source files into the debian package build structure.

These items are not debian-specific and are useful for everyone.

Initial packaging setup

The first step is putting the <package>_<version>.tar.gz in the directory above the current one renamed to <package>_<version>.orig.tar.gz. We will use it in a moment.

The next step is to create the debian branches in the git repository: on the debian-upstream branch, we will store the upstream source, while the debian-debian branch will hold the debian package data. This separation provides a cleaner revision history by separating the changes that affect the software from the changes in the packaging.

In order to create these branches, we issue the following commands in the git repository:

  git symbolic-ref HEAD refs/heads/debian-upstream
  git rm --cached -r .
  git clean -xfd
  git commit --allow-empty -m 'Start of debian branches.'
  git checkout -b debian-debian

That will make both branches point to a root-commit with no files.

We will now use the ../<package>_<version>.orig.tar.gz file to create the initial debian directory in the debian-debian branch:

  dh_make -s -p <package>_<version>

We can now customize the standard debian directory created. The only required files that must be fixed are: changelog, compat, control, copyright and rules. Besides filling package-specific information, we should also:

Put, in debian/rules file:

  override_dh_auto_install: $(MAKE) PREFIX=$(CURDIR)/debian/<package>/usr install

Create a debian/<package>.manpages file with the name of the manpage file of the package.

Create a debian/gbp.conf with the following contents:

  [DEFAULT]
  upstream-branch=debian-upstream
  debian-branch=debian-debian

We can now commit the debian directory in the debian-debian branch.

Importing the sources

In the debian-debian branch:

  git-import-orig ../<package>_<version>.orig.tar.gz

That will import the original sources to the debian-upstream branch, and merge it with the debian-debian branch.

Creating the package

To create the debian package:

  git-buildpackage --git-tag

Importing further versions

Create the new ../<package>_<version>/.orig.tar.gz and then:

  git-import-orig ../<package>_<version>.orig.tar.gz

Edit the debian/changelog file (we can use dch for that), and create a new package:

  git-buildpackage --git-tag

Yes, it's that easy.

Final remarks

After an initial expensive setup, package creation of further versions is mostly painless, which is the whole point of git-buildpackage and friends.

Besides this article, we should check the debian dir of some already packaged software for reference. We can look at the execpermfix repository at github when first trying to package something.

Further information: