I have been asked how the various pieces in a Debian source package relate to those in a corresponding binary package. For the sake of simplicity, I'll start with a one-source -> one-binary packaging situation. Let's choose worklog, a primitive task timer, as our sample package.

The simplest way to get started is to pick a simple package and get the source. In an empty directory, do this:

$ apt-get source worklog
Reading package lists... Done
Building dependency tree       
Reading state information... Done
Skipping already downloaded file 'worklog_1.8-6.dsc'
Skipping already downloaded file 'worklog_1.8.orig.tar.gz'
Skipping already downloaded file 'worklog_1.8-6.debian.tar.gz'
Need to get 0 B of source archives.
dpkg-source: info: extracting worklog in worklog-1.8
dpkg-source: info: unpacking worklog_1.8.orig.tar.gz
dpkg-source: info: unpacking worklog_1.8-6.debian.tar.gz
dpkg-source: info: applying ferror_fix.patch
dpkg-source: info: applying makefile_fix.patch
dpkg-source: info: applying spelling_fix.patch

It will pull down the source package's parts and unpack and patch it. The result looks like this:

$ ls
worklog-1.8  worklog_1.8-6.debian.tar.gz  worklog_1.8-6.dsc
worklog_1.8.orig.tar.gz

The various parts are:

worklog_1.8.orig.tar.gz: Upstream's code in a tarball
worklog_1.8-6.debian.tar.gz: This tarball unpacks into the ./debian subdirectory inside of the actual working dir
worklog-1.8: The ready-made project dir containing upstream's code, the ./debian subdirectory, and with all patches applied.
worklog_1.8-6.dsc: This is the file holding it all together, with package description, checksums, a digital signature etc.

The contents of the unpacked source package looks like this:

$ cd  worklog-1.8
$ ls
.pc Makefile  README  TODO  debian  projects
worklog.1  worklog.c  worklog.lsm

We are now going to examine the contents of the ./debian subdirectory, which contains the packaging instructions and assorted data:

$ ls
.pc  changelog  compat  control  copyright  dirs  docs
patches  rules  source

The ubiquitious .pc subdirectories are created by quilt, a patch management application used by this package. They won't leave a trace in the binary package.

Above, in the listing of the project dir, you see the two files README and TODO. Now compare with the contents of docs:

$ cat docs 
README
TODO

These files, alongside the copyright, will end up in the package's documentation directory, in this case /usr/share/doc/worklog. Also in the documentation directory, you will find a copy of the changelog:

$ ls /usr/share/doc/worklog/
README  TODO  changelog.Debian.gz  copyright  examples

The control file represents the information about which packages are going to be created, and the rules file specifies the actions which are to be performed for actually building the package. Also very relevant for this task are compat, which specifies the debhelper API to use, source/format, which specifies the source package format (see http://wiki.debian.org/Projects/DebSrc3.0 for details), and the patches subdirectory, containing any required patches. Usual cases for patches are eg. to adjust hardcoded paths to Debian standards, implement security fixes, or other required changes that can't be done via the rules file. Look:

$ ls patches
ferror_fix.patch  makefile_fix.patch  series  spelling_fix.patch

The series file contains an ordered list of patches and is used to specify which patches to apply, and in which order. In this example, the makefile_fix.patch corrects such a hardcoded path.

If things are getting more complicated, the debian subdirectory also contains things like init scripts (which then end up in eg. /etc/init.d), and possibly manually crafted scripts like postinst, which are executed by the package management software. These, along with other administrative files, end up in /var/lib/dpkg/info. In our example, there are only two files:

$ ls /var/lib/dpkg/info/worklog.*
/var/lib/dpkg/info/worklog.list
/var/lib/dpkg/info/worklog.md5sums

The worklog.list file contains one entry per file for the whole directory tree, including directories, while the worklog.md5sums file contains checksums for every regular file in the package. See, for comparison, the same listing for mdadm (a popular software raid implementation for Linux):

$ ls /var/lib/dpkg/info/mdadm.*
/var/lib/dpkg/info/mdadm.conffiles
/var/lib/dpkg/info/mdadm.config
/var/lib/dpkg/info/mdadm.list
/var/lib/dpkg/info/mdadm.md5sums
/var/lib/dpkg/info/mdadm.postinst
/var/lib/dpkg/info/mdadm.postrm
/var/lib/dpkg/info/mdadm.preinst
/var/lib/dpkg/info/mdadm.prerm
/var/lib/dpkg/info/mdadm.templates

Here, the mdadm.config works together with debconf to create an initial configuration file, and the *.{pre,post}{inst,rm} scripts are designed to trigger such configuration, to discover devices etc, and to start or stop the daemon, and do some cleanup afterwards.

This should get you started on Debian's package structure. For further information, I recommend http://www.debian.org/doc/manuals/maint-guide/ and generally, http://wiki.debian.org/DebianDevelopment .

Enjoy!

Comments