— Konstantin Mikhaylov Thu, 18 Sep 2008 15:07:30 +1100
Building binary deb packages: a practical guide
How to ship your apps on Debian and derivatives.
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.
On the outside instead, all deb package files follow a specific naming convention:
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 /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:
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:
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:
So in our example:
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:
Make sure it can be also uninstalled easily. You can just remove the package:
or remove it along with the configuration files (if any):
Make sure the application has been removed correctly by issuing:
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 :
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:
Taking care of external dependencies
Run scripts before or after package installation and removal
ΠΠ°ΠΊ ΡΠΎΠ±ΡΠ°ΡΡ Π±ΠΈΠ½Π°ΡΠ½ΡΠΉ deb ΠΏΠ°ΠΊΠ΅Ρ: ΠΏΠΎΠ΄ΡΠΎΠ±Π½ΠΎΠ΅ HowTo
There is some new and interesting documentation on packaging:
If you need to create rapidly a package, use equivs.
If you prefer to gain real knowledge about Debian packaging:
Then read the interesting PDF file included in the package: packaging-tutorial
This is a pragmatic approach to learning how to create Debian packages.
If the information below doesn’t answer your questions, please look in the New Maintainer’s Guide and in Debian Policy
The Debian package management chapter of the Developers Reference contains lots of useful information for handling all kinds of problems one runs into with apt and dpkg.
If you want to create an official Debian package, make sure it’s not already packaged.
If somebody is working on the package, you should contact them if you intend to make an official package together.
For a slightly more modern way of managing all of this, check out git-buildpackage. TODO: write this page around git-buildpackage, instead of quilt, for a less baroque and more familiar experience.
Initial compilation
Before starting there are some risks you should be aware of:
WARNINGS:
All these operations are preferably done in a chroot environment for safety/security reasons. pbuilder and sbuild are such environments. Please consult the pbuilder or sbuild documentation.
running make on a system can be a security risk! It is recommended to check beforehand that the Makefile does not contain any funny stuff. Obscure/specially crafted applications might fall into this case.
do NOT run make install, unless you are absolutely sure is safe to do that (check the install target of the makefile). This is a security risk and you may risk to break and/or compromise your system.
the package is not being worked on (ITP (Intent To Package) is pending)
are you sure it’s not packaged? You could check other Debian based distributions, too.
It is best to create a chroot jail in which to build the application. This mitigates security and system corruption problems. In addition it ensures that any local changes to your machine will not interfere with the build.
»Debianization»
After the first compilation, it’s time to create the Debian specific part of the package.
Debianize the package by using dh_make or one of the other automatic packaging tools.
File debian/control: Add to the Build-Depends (sometimes even Build-Depends-Indep) the list of packages needed to be installed for the application to compile (remember the list done previously). You should leave out any packages that are listed in /usr/share/build-essential/essential-packages-list or /usr/share/build-essential/list and also leave out any packages that listed as dependencies by any of those packages.
Review each of the template files (debian/*.ex). If your package needs that feature, then customize the file as needed and rename it without the «.ex».
Make sure that all the directories you will place files in are listed in the debian/dirs file without a leading slash (/).
Make sure that the files are installed in the proper place (under a directory, not on the root system). Take care at the install target from the application makefile. If the application uses autoconf and automake, it may be enough to set the environment variable DESTDIR, e.g. «make DESTDIR=$(CURDIR)/debian/packagename». (dh_make will set this up automatically.)
Note: very often the upstream package will install files under /usr/local. DO NOT INSTALL ANY FILES IN THERE.
Initial compilation of the package
Building Debian packages
To make sure that a Debian package meets all build dependencies and is not influenced by anything specific to the user’s environment, packages should be built in a chroot environment. Tools like pbuilder can be used for this.
When working on a package, a faster rebuild can be done with ‘debuild’. But then, all build-dependencies must be satisfied in the installation where the package is built. All necessary packages can be installed automatically with apt-get build-dep. A complete example for building the foo package looks like this: A very basic introduction to create an empty package or a package with just a pdf file (sentence fragment added by HenriLeFoll in Rev. 76)
This is usually enough for you to backport packages.
Testing and Check the package
All tests in chroot
Testing the package
Lintian
Test all the packages with lintian.
Piuparts
Check points for any package
If there are architecture independent things in the package and if they are big enough, are those packaged in a separate package with arch all?
This list of checks is deprecated as check-all-the-things replaces it, except for a couple of checks documented in the TODO file.
Other ideas can be taken from the check-build script in the pkg-perl-tools package.
This page is still incomplete; please help by adding information to it. Do not forget that the information here should be in a concise form.
Examples
There are interesting examples in the PDF file included in the package : packaging-tutorial.
You could check other Debian based distributions, too.
This list of checks is deprecated as check-all-the-things replaces it, except for a couple of checks documented in the TODO file.