Using dh-make to prepare debian packages

Jul 13, 2015 · 4 min read

debian-how-to

TL;DR

This blog post will cover some basics about debian package names and version strings, and how to build debian packaging boilerplate using dh_make to streamline the creation of packages.

Install the packaging essentials

$ sudo apt-get install build-essential dh-make

Understanding the package name and version

Let’s assume we have an upstream source with the archive name of newprogram-0.12.7.tar.gz. We’ll use newprogram as the package name and 0.12.7 as the upstream version.

It’s important to remember the following about package names:

Consists of only lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.)
Must be at least two (2) characters long
Must start with an alphanumeric character
Recommended to be less than 30 characters, if possible.

and upstream versions:

Must start with a digit (0-9)
Must consist only of alphanumeric characters (0-9A-Za-z), plus signs (+), tildes (~) and periods (.)
Recommended to be less than 8 characters, if possible.

If an upstream version does not use a versioning scheme recognized by the deb toolchain (i.e 0.12.7), remove the invalid values from the upstream version. These removed values can be recorded in the debian/changelog file. If you need to create a version string, use the YYYYMMDD format (i.e 20150713).

Setting up dh_make

Create the $DEBEMAIL and $DEBFULLNAME shell environment variables. These will be used to generate values in control and changelog entries.

$ cat >>~/.bashrc <<EOF
DEBEMAIL="person@company.tld"
DEBFULLNAME="Testy McTester"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc

Setting up the directory structure

1) Create the top-level directory and then change directory into the new folder:

$ mkdir newprogram; cd newprogram/

2) Retreive and unpack upstream source:

$ wget https://example.org/newprogram-0.12.7.tar.gz

$ tar -xvzf newprogram-0.12.7.tar.gz

3) Change into the unpacked directory:

$ cd newprogram-0.12.7/

Create the initial package using the original source archive

From inside the unpacked source directory (i.e. ./newprogram-0.12.7), run the following:

$ dh_make -f ../newprogram-0.12.7.tar.gz

The -f flag sets the filepath as the original (newprogram_0.12.7.orig.tar.gz) source archive, which skips the copying of the current program tree.

Some `dh-make` action

After calling dh_make -f <filepath>, you will be prompted to select the type of package you are creating.

Type of package: single binary, indep binary, multiple binary, library, kernel module, kernel patch?
[s/i/m/l/k/n] s

For this example, we can assume that newprogram-0.12.7 is a single binary.

Next, if you set your shell environment variables $DEBEMAIL and $DEBFULLNAME, you should see the output of a control file with the relevant fields already completed. If not, you will have to edit the control file manually. (See this post)

Maintainer name  : Testy McTester
Email-Address    : person@company.tld
Date             : Mon, 13 Jul 2015 10:44:12 -0700
Package Name     : newprogram
Version          : 0.12.7
License          : blank
Type of Package  : Single
Hit <enter> to confirm:

Piecing it all together

After running dh_make -f , a copy of the upstream tarball will be created in the parent directory.

$ pwd
/newprogram

$ ls
newprogram-0.12.7/
newprogram-0.12.7.tar.gz
newprogram_0.12.7.orig.tar.gz # <- this guy right here

There are a couple of things to note about the newprogram_0.12.7.orig.tar.gz filename:

The package name and version are separated by the underscore (_) character
The string .orig is placed before .tar.gz

Also, newly created debian template files will be placed in the source folder under the debian directory.

$ cd newprogram-0.12.7/debian/

$ ls
changelog  compat  control  copyright  docs  rules  source ...

this example does not show all template files created by dh_make

Next steps

After the debian boilerpate files have been created, the real fun can begin. This includes understanding and modifying the required files under the debian directory, modifying the upstream source, and building the actual package.

We’ve also put out a couple of blog posts that can likely help you along the way:

#packaging_love

Conclusion

Use dh_make to automate some of the boilerplate around creating a debian package from an upstream source. Hopefully, it’ll get you a few steps ahead when building your next deb package. If you’re not experienced in making software packages, chances are there will be some pain and suffering in your immediate future - but fear not! We have released a series of blog posts to help you along the way. Check out the packagecloud.io blog.