Debianization with git-buildpackage
Updated 2018-04-03: git-buildpackage's commands have changed, so this article had to be fixed; I took the opportunity to improve a few things as well.
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:
${PACKAGE}.1
or similar. - A
COPYING
file with GPL information or some other license. - An appropriate build file for the package. For C/C++ programs, I recommend
using
cmake
; for python,setup.py
, etc.
These items are not debian-specific and are useful for everyone.
Initial packaging setup
The first step is creating the ${PACKAGE}_${VERSION}.orig.tar.gz
file. You
can use git itself for that, by running the following commands in the
repository:
PREFIX=${PACKAGE}_${VERSION} git archive --format=tar --prefix=$PREFIX/ $VERSION | gzip -c > ../$PREFIX.orig.tar.gz
You can check the contents of the archive with tar. If there are extraneous
files in the archive, you can configure git-archove to exclude them by creating
a .gitattributes
file; for example:
.gitignore export-ignore .gitattributes export-ignore .travis.yml export-ignore
The next step is to create the debian branches in the git repository: on the debian-upstream branch, we store the upstream source, while the debian-debian branch holds 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 checkout --orphan debian-upstream git rm --cached -r . git clean -xfd git commit --allow-empty -m 'Start of debian branches.' git checkout -b debian-debian
That creates both branches as orphans, pointing to an empty root commit.
We 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. You must edit
the following files: changelog
, control
, copyright
and rules
.
Besides those, the compat
file must be present; the other files can be
safely removed.
After changing the files that dh_make
created, you should 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:
gbp import-orig --no-interactive ../${PACKAGE}_${VERSION}.orig.tar.gz
That imports the original sources to the debian-upstream branch, and merge it into the debian-debian branch.
Creating the package
To create the debian package:
gbp buildpackage -us -uc --git-tag
Importing further versions
Create the new ../${PACKAGE}_${VERSION}/.orig.tar.gz
and then:
gbp import-orig --no-interactive ../${PACKAGE}_${VERSION}.orig.tar.gz
Edit the debian/changelog
file (we can use dch -i -v $VERSION
for
that), and create a new package:
gbp buildpackage -us -uc --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: