How to ship your apps on Debian and derivatives.
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
/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
On the outside instead, all deb package files follow a specific naming convention:
<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
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:
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
mkdir -p hello_1.0-1_arm64/usr/local/bin
-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 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:
And then create the empty
4. Fill in the
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.
Package: hello Version: 1.0 Architecture: arm64 Maintainer: Internal Pointers <firstname.lastname@example.org> Description: A program that greets you. You can add a longer description here. Mind the space at the beginning of this paragraph.
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>
--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>
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
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
-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
prerm are called maintainer scripts. Such files live inside the
DEBIAN directory and, as their names suggest,
postinst are run before and after installation, while
postrm are run before and after removal. They must be marked as executables. Also, remember to set permissions: must be between
Debian Policy Manual
Debian documentation - Chapter 7. Basics of the Debian package management system
Unix StackExchange - How to uninstall a .deb installed with dpkg?