How To: Binary Deb Packages
A DEB file is a standard Unix archive that contains two bzipped or gzipped archives, one for the installer control information and another for the actual installable data. DEB files are often used for software installation packages by multiple versions of Linux. Deb files are particularly 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.
Anatomy of a Deb Package
The deb file is a standard Unix 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 /bin, /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/program will be installed to /usr/local/bin/program.
On the outside instead, all deb package files follow a specific naming convention. This is not a rule, but is preferable as it conveys important information right from the file name:
- <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 magicalapp, version 2.0, built for 64-bit ARM processors. Your deb file name would look something like magicalapp_2.0-1_arm64.deb.
Making a Deb Package
Make sure you have the dpkg-deb program installed in your system as this program will be used later on to generate the final archive. If you don't have it install it first:
apt install dpkg-deb
(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 /usr/local/bin:
mkdir -p magicalapp_2.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 ~/your_code/MagicApp/magicalapp magicalapp_2.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:
And then create the empty control file:
Now open this file 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: magicalapp Version: 2.0 Architecture: arm64 Maintainer: The Coder <email@example.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.
(4) Building the Deb Package
To build your deb binary package you need to invoke dpkg-deb as following:
dpkg-deb --build --root-owner-group <package-dir>
So in our example:
dpkg-deb --build --root-owner-group <magicalapp_2.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.
Test the 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.
This 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>
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 reason 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.
Running Scripts Before or After Installation and/or 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.