While attenting at this year’s RMLL conferences, I had the opportunity to listen to a great presentation of the APT package management system by Lucas Nussbaum. I then had the idea to create this post as a quick reference on how to quickly build someone’s first Debian package.
You are kindly invited to take a glance at the complete presentation hosted here if you want to learn more about this exciting part of the Debian systems.
Your first Debian package
First, you will need to pull all the required dependencies required to build any package – please ensure that you have some deb-src entries in your sources.list (using Synaptic or your good old fashioned CLI editor) or else you will get a “E: You must put some ‘source’ URIs in your sources.list” error.
apt-get update apt-get install build-essential devscripts debhelper
Then we will try to build a simple package, with minimal dependencies :
apt-get build-dep dash apt-get source dash cd dash-(version) debuild -us -uc (No package signing)
After a while, you hopefully get your fresh debian package(s) in the upper directory :
# ls -l ../*.deb ash_0.5.5.1-7ubuntu1_all.deb dash_0.5.5.1-7ubuntu1_i386.deb
Now, here are some few tips about the debian packaging system:
Every package to be built has the same structure:
- A plain sources directory, sometimes patched with debian specific code bits,
- a “debian” directory.
Inside this “debian” directory you get all the files that will describe how to build the package and every meta informations about it.
For example, you have regular version attached to the source directory, plus a Debian specific one, in dash’s case :
- 0.5.5.1 is the source version, called “upstream” version
- -1 is the Debian specific patch level (relative to the patches in the Debian bugtracker)
Let’s see some important components of the “debian” directory :
The “compat” file
This file specifies the compatibility level of the package definition, the current level is 7.
The “control” file
This file describes the place that this package will take in the APT ecosystem, with key metadata that help the system to identify the target architecture, the dependencies … the format is based on the rfc-822, which you can also see in HTTP and Mail headers.
Essential: yes
For example, the Architecture definition, which defines on which architecture this package will work:
- any : Will build on any architecture
- all : This package is architecture independant
- amd64, hurd-i386 : Will only build and run on these platforms
You can also encounter entries like $(shlibs:dep), that automatically analyse on which libraries depends the build binaries and automatically fill the dependencies list with the associated packages, or the Essential entry (found in the dash package) which specifies that this package is critical for correct system operation. (trying to delete it will trigger the following warning)
WARNING: The following essential packages will be removed. This should NOT be done unless you know exactly what you are doing! bash dash (due to bash) 0 upgraded, 0 newly installed, 5 to remove and 60 not upgraded. After this operation, 6756 kB disk space will be freed. You are about to do something potentially harmful. To continue type in the phrase 'Yes, do as I say!' ?]
The “rules” file
This file is the bridge between the APT system and the upstream/patched sources and it is basically a GNU Makefile, it specifies how the binaries/bytecodes are to be build before packaging them, basically specifying options for the configure script or triggering a make task.
There are five mandatory targets :
- build : How to configure and build the package
- binary, binary-arch, binary-indep : How to compile the binaries
- clean : How to clean up the rubbish
Hopefully, you will try someday to build something much more complex than dash. And you will be very limited by the syntax of a basic makefile to do your work.
This is where the helpers save the day, the most used one being debhelper : Its objective is to factor the most common tasks used for binary compilation and source preparation, like configure scripts runs, documentation preparation …
Debhelper is used in the rules files with keywords like package.dirs and package.docs, the helpers being called are redacted in various languages, and there are some more modern implementations of it: CDBS (critisized for his complexity and slowness) and dh (created in 2008 to “kill” CDBS, identifiable by all his commands prefix : dh_*)
Here is a sample of a trivial dh usage :
#!/usr/bin/make -f %: dh $@ override_dh_auto_configure : dh_auto_configure --with-kitchen-sink override_dh_auto_build : make world
and a quick reference of some useful dh_* statements :
- binary – arch : build install
- dh_testdir : Test directories according to parameters
- dh_testroot : Test the sources according to parameters
- dh_installchangelogs : Install changelogs
- dh_installexamples : Install examples (in /usr/share/doc/package/examples)
- dh_link : Create links
- dh_strip : Strip binaries
- dh_compress : Compress files
- dh_fixperms : Adjust permissions
- dh_installdeb : Install deb files
- dh_shlibdeps : Build shared libs dependencies
- dh_gencontrol : Generate a control file
- dh_md5sums : Generate md5 sums
- dh_builddeb : Build the deb file
According to statistics, dh grows rapidly comparing to plain debhelper, while CDBS stays stable. The current consensus is: use dh if you can, you might also want to get some documentation about schroot and sbuild if you have complex needs (which enables you to build packages using LVM snapshots to always have a clean build environment), or about package maintenance using VCS systems (See the Vcs-Git: http://smarden.org/git/dash.git/ entry in dash’s control file)
You are now encouraged to play around with simple packages like dash, like bumping versions using the changelog file or creating your own simple package !
Get involved !
When you will be a little more experienced, you might consider to get involved in the Debian project, you will then have multiples possibilities to do so:
- Adopt an unmaintained package (using wnpp-alert or http://www.debian.org/devel/wnpp)
- Get involved in a packaging team (http://wiki.debian.org/Teams), which is recommended for new contributors, teams are often happy to share experience
- Get some new softwares in Debian (Please, only useful and non-redundant things, we don’t want another hot-babe scandal)
- Try to ease Debian-Ubuntu collaboration (Launchpad teams)
- Find a mentor : http://mentors.debian.net
