Creating Debian Packages

This document describes the decisions made in packaging and descrbes the steps taken.

For the purpose of this discussion, we'll consider the build directory to be at ~/build.

Bazaar

$ sudo aptitude install bzr

If you are creating a new project, then make a directory for the project and put it under version control. For example:

$ bzr init ihris-qualify-debian

Since you are probably dealing with code already under version control, you can just check it out. For example, to check out the my build scripts for the i2ce project from Launchpad:

$ bzr co lp:~hexmode/i2ce/debian-dev i2ce-debian
$ ls
i2ce-debian

bzr-builddeb

$ sudo aptitude install bzr-builddeb

The build scripts are kept separate repository and kept under version control. To enable this (and keep the number of revision control systems in use to a minimum), I use bzr-builddeb to build packages directly from the bzr repository.

This package generation tool can keep the debian directory under revision control. If you look at my debian repositories, you'll see that the repositories are the contents of the debian directory. During the build process, bzr-builddeb merges the directory with the pristine source tree and performs all build operations there.

bzr-builddeb uses several configuration files to control its operation. The only one we're concerned with here is the default.conf file under the .bzr-builddeb directory. This stores the defaults for this package. The contents of ~/build/i2ce-debian/.bzr-debbuild/default.conf:

[BUILDDEB]
merge = True
export-upstream = http://bazaar.launchpad.net/%7Eintrahealth%2Binformatics/i2ce/main/

The first line just confirms that this is a bzr-builddeb configuration package.

The second line (merge = True) tells bzr-builddeb to merge this directory (in this case, ~/build/i2ce-debian with the the upstream source.

The third line (export-upstream = …) gives the location of the original source in Bazaar to check out.

Running bzr builddeb from within the i2ce-debian directory will create a ~/build/build-area/i2ce-2.0 directory, check out the code from Launchpad, put the contents of the current directory in the debian subdirectory, and build the package. After the package is built, the ~/build/build-area/i2ce-2.0 directory will be removed.

dpatch

dpatch is a patch management system that I used to alter the pristine configuration files so that they would work in the Debian packages.

Patches are stored in the patches sub-directory and are applied in the order listed in the 00list file in that directory.

To apply all the patches, the command dpatch apply-all is executed. To remove all patches (i.e. in a “clean” operation), use the command dpatch deapply-all. To create a new patch, see “Creating dpatch scriptlets” in the dpatch man page.

dbconfig-common

dbconfig-common is used to set up the database structure for the i2ce. If there is any need to provide initial database data for other packages, this package should be used to handle the installation.

To setup a database, two things must be done. First, the database data must be provided. Second, the dbconfig-common post-installation hooks must be called.

The SQL data is provided during the package building process by putting an SQL file at /usr/share/dbconfig-common/data/package/install/mysql. PostgreSQL setup can be done in a similar way.

Important: Since dbconfig-common creates a database as well as a user for the application, do not perform these steps in your database setup.

In the post-installation script, a few environment variables are set to tell dbconfig-common where to place the templates it produces and then the dbconfig-common hooks are called. These hooks take care of collecting and assigning passords; creating the user and database for the application; and loading the data into the database.

ucf

Configuration files are managed with ucf (Update Configuration File).

This tool provides a way to udate configuration files so that user's changes are preserved. ucf is called from the post-installation scripts to copy over a new configuration file. If changes are detected that cannot easily be merged, the administrator performing the installtion will be prompted to confirm the update.

In the iHRIS packages, files managed with ucf are /etc/i2ce/I2CE_config.inc.php, /etc/i2ce/ihris_config.inc.php, /etc/apache2/conf.d/ihris-manage.conf, and the like.

Files and Directories in the Debian directory

The debian directories under Bazaar contain several identically named files. Here I describe the purpose of each file. To learn more about the process of creating a Debian package, see the Debian New Maintainers' Guide

.bzr

Bazaar stores all information about files under version control in this directory. I won't bother talking about the specifics of what is in here since it isn't related to the build process. Just don't delete it if you plan to use bzr-builddeb

.bzr-builddeb/default.conf

The contents of this file were explained in the [#bzr-builddeb bzr-builddeb] section.

rules

This is a makefile that controls the creating of a package. It has five mandatory targets (clean, binary, binary-arch, binary-indep, and build).

Since we're using dpatch, I've added patch and unpatch targets that build and clean depend on.

patch: patch-stamp
patch-stamp:
	dpatch apply-all -v
	dpatch cat-all > patch-stamp

unpatch:
	dpatch deapply-all
	rm -rf patch-stamp debian/patched

PHP-based packages don't really need that much “build” effort, so most of the action happens in the install target (used by the mandatory binary target) where files are re-arranged into something resembling the Filesystem Hierarchy Standard (fhs). As of this writing, for example, the i2ce package contains the following instructions:

install -d -m 755 -o root -g admin $(DESTDIR)/usr/share/ihris
install -d -m 755 -o root -g admin $(DESTDIR)/usr/share/ihris/lib
install -d -m 755 -o root -g admin $(DESTDIR)/etc/$(PACKAGE)
install -d -m 755 -o root -g admin $(SQL_DIR)

install -m 444 -o root -g admin \
	lib/*.php $(DESTDIR)/usr/share/ihris/lib

install -m 444 -o root -g admin I2CE_config.inc.php \
	$(DESTDIR)/usr/share/ihris/
install -m 444 -o root -g admin I2CE_structure.sql $(SQL_DIR)/mysql;

changelog

This is just a description of the changes to the package itself. Since it has a very specific format, use dch or Emacs' debian-changelog-mode to create new entries.

compat

(I'm not sure what this is. I believe it contains the version number the build scripts look at to make sure they build the package properly.)

control

The packages that can be produces from this debian directory as well as the description, architecture, build-dependencies and install-dependencies are listed in the file.

For example, the control file for i2ce looks like this:

Source: i2ce
Section: web
Priority: extra
Maintainer: Mark A. Hershberger <mhershberger@intrahealth.org>
Build-Depends: debhelper (>= 5), dpatch
Standards-Version: 3.7.2

Package: i2ce
Architecture: all
Pre-Depends: ucf
Depends: ${shlibs:Depends}, ${misc:Depends}, php-i18nv2, php-mdb2-driver-mysql,
         php-text-password, dbconfig-common
Description: database-driven software for forms
 IntraHealth Informatics Core Engine (I2CE) is a set of classes for handling
 database-driven HTML forms with templates and database
 abstraction. It is the core programming engine for the iHRIS Suite of
 software.

The first stanza describes the source package and build depends. Items like Section and Maintainer will be applied to the later binary package stanza's.

Since each of the packages (at present) creates only one debian package, there is only a single Package stanza. If a source tree can produce multiple packages, then more stanzas will be placed here. Of course, the packaging becomes more complex, but since the IntraHealth packages don't use this, I've not covered it here.

copyright

Every Debian package must contain a copyright file so that users can easily find the license on the package. Since we're using the GPLv3, we can just make a reference to it. For an example of a more complex copyright file, see virtualbox-ose's copyright file in Ubuntu.

patches

The patches directory contains the patches for dpatch. The contents are described in the [#dpatch dpatch] section above.

config

This is a script that is included in the binary package and executed to take care of the configuration step of package installation. The only IntraHealth package that includes a config script is the i2ce package. i2ce uses this script to call the configuration hooks for dbcommon-config.

postinst

This script is included in the binary package and executed after the files from the package have been put in place. Any final setup takes place here. For example, i2ce uses this script to set some environment variables and then call the dbconfig-common postinst hooks:

dbc_generate_include=php:/etc/i2ce/i2ce.php.inc
dbc_generate_include_owner=www-data
dbc_generate_include_perms=0400
dbc_dbtypes=mysql

. /usr/share/debconf/confmodule
. /usr/share/dbconfig-common/dpkg/postinst

dbc_go i2ce $@

Any files that are under the control of ucf ([#ucf see above]) are handled here. i2ce installs its configuration file here:

ucf /usr/share/ihris/I2CE_config.inc.php /etc/i2ce/I2CE_config.inc.php

postrm

postrm is executed after the package has been removed. In the case of i2ce, dbconfig-common recommends deleting the files it generates during removal.

README.Debian

This contains any notes the packager may wish to include. Don't just copy a README file as the packaging usually includes this.