Building binary deb packages: a practical guide

A deb file is an archive that contains data. Marked with the .deb extension, it is used to easily distribute and install programs for Linux Debian and derivatives. Deb files are handy when your app needs to take care of additional dependencies, integrate itself with the desktop, run pre and post install scripts and so on.

In this quick tutorial I want to show you how to generate a deb package from scratch that will install a binary executable in the target system. Let's start off with a bit of theoretical background.

Anatomy of a deb package

A deb is a standard Unix ar archive that contains your application and other utility files. The most important one is the control file, which stores the information about the deb package and the program it installs.

Internally, a deb package contains a collection of folders that mimics a typical Linux file system, such as /usr, /usr/bin, /opt and so on. A file put in one of those directories will be copied to the same location in the actual file system during installation. So, for example a binary file put into <.deb>/usr/local/bin/binaryfile will be installed to /usr/local/bin/binaryfile.

On the outside instead, all deb package files follow a specific naming convention:

<name>_<version>-<revision>_<architecture>.deb

That is:

• <name> – the name of your application;
• <version> – the version number of your application;
• <revision> – the version number of the current deb package;
• <architecture> – the hardware architecture your program will be run on.

For example, suppose you want to release your program called hello, version 1.0, built for 64-bit ARM processors. Your deb file name would look something like hello_1.0-1_arm64.deb.

Making the deb package

We are now ready to generate the package. Make sure you have the dpkg-deb program installed in your system: this will be used later on to generate the final archive.

1. Create the working directory

Create a temporary working directory to make your package in. Follow the same naming convention we have seen before. For example:

mkdir hello_1.0-1_arm64

2. Create the internal structure

Put your program files where they should be installed to on the target system. For example, suppose you want your program to be installed to /usr/local/bin:

mkdir -p hello_1.0-1_arm64/usr/local/bin

The -p flag to the mkdir command will create nested directories. Then copy the executable file in there:

cp ~/YourProjects/Hello/hello hello_1.0-1_arm64/usr/local/bin

3. Create the control file

The control file lives inside the DEBIAN directory. Mind the uppercase: a similar directory named debian (lowecase) is used to store source code for the so-called source packages. This tutorial is about binary packages, so we don't need it.

Let's create the DEBIAN folder first:

mkdir helloworld_1.0-1_arm64/DEBIAN

And then create the empty control file:

touch helloworld_1.0-1_arm64/DEBIAN/control

4. Fill in the control file

Open the file previously created with your text editor of choice. The control file is just a list of data fields. For binary packages there is a minimum set of mandatory ones:

• Package – the name of your program;
• Version – the version of your program;
• Architecture – the target architecture;
• Maintainer – the name and the email address of the person in charge of the package maintenance;
• Description – a brief description of the program.

For example:

Package: hello
Version: 1.0
Architecture: arm64
Maintainer: Internal Pointers <info@internalpointers.com>
Description: A program that greets you.
 You can add a longer description here. Mind the space at the beginning of this paragraph.

The control file may contain additional useful fields such as the section it belongs to or the dependency list. The latter is extremely important in case your program relies on external libraries to work correctly. You can fill it manually if you wish, but there are helper tools to ease the burden. I will show you how in the next few paragraphs.

5. Build the deb package

This is the last step. Invoke dpkg-deb as following:

dpkg-deb --build --root-owner-group <package-dir>

So in our example:

dpkg-deb --build --root-owner-group <helloworld_1.0-1_arm64>

The --root-owner-group flag makes all deb package content owned by the root user, which is the standard way to go. Without such flag, all files and folders would be owned by your user, which might not exist in the system the deb package would be installed to.

The command above will generate a nice .deb file alongside the working directory or print an error if something is wrong or missing inside the package. If the operation is successful you have a deb package ready for distribution. Keep reading for additional goodies!

Test your deb package

It's a good idea to test your deb package once created. You can install it like any other regular deb package:

sudo dpkg -i <package>

Make sure it can be also uninstalled easily. You can just remove the package:

sudo dpkg -r <appname>

or remove it along with the configuration files (if any):

sudo dpkg -P <appname>

Make sure the application has been removed correctly by issuing:

dpkg -l | grep <appname>

The dpkg -l command lists all the packages installed, while grep searches for <appname>. The output should be blank if the app has been uninstalled correctly.

Sometimes the deb installation goes wrong

Especially when you are dealing with pre/post install or removal scripts that fail at some point. This is a typical error message by dpkg:

Package is in a very bad inconsistent state - you should reinstall it before attempting a removal.

which prevents any progress. The trick is to move all references to your broken package somewhere safe (e.g. the /tmp directory) and then force remove it, like so:

sudo mv /var/lib/dpkg/info/<packagename>.* /tmp/
sudo dpkg --remove --force-remove-reinstreq <packagename>

Taking care of external dependencies

You can generate them automatically with dpkg-shlibdeps. It will parse your binary and look for external symbols. At the time of writing, that tool doesn't seem to work out of the box. For some unknown (to me) reasons it wants the debian/control file to be present in the working directory – that's for source packages, remember? The workaround here is to create it, then move into the working folder and run:

dpkg-shlibdeps -O path/to/binary/file

The -O flag will print dependencies on the standard output. Copy the output and paste it in the Depends section of your DEBIAN/control file. You can get rid of the debian/control file once done. I'm pretty sure there are better ways for this, though: I will update the article once I get additional information on this step.

Run scripts before or after package installation and removal

Four files: postinst, preinst, postrm, and prerm are called maintainer scripts. Such files live inside the DEBIAN directory and, as their names suggest, preinst and postinst are run before and after installation, while prerm and postrm are run before and after removal. They must be marked as executables. Also, remember to set permissions: must be between 0555 and 0775.

Sources

Debian Policy Manual
Debian documentation - Chapter 7. Basics of the Debian package management system
Unix StackExchange - How to uninstall a .deb installed with dpkg?