Making packages

Making packages

There are two ways to make a package - using debhelper or cdbs. A quick overview is available at the ubuntu packaging guide.

Structure of a debian package is the program sources + a debian/ folder with certain files specific to the package, and not the program source itself. Some common files in it are:

• debian/copyright - the license of the package
• debian/changelog - the changelog of the package - so both program changes and packages changes are listed here. It's in GNU ChangeLog format
• debian/control - 'The control file contains the information that the package manager (such as apt-get, synaptic, and aptitude) uses, build-time dependencies, maintainer information, and much more.'
• debian/rules - the essense of the package. Describes what to do in certain actions (how to compile it if needed, what to do when installing, etc.). Also calls helper dh_* functions - the list is available here.

Debhelper is the traditional method of creating a package. The workflow that you have with it is that you use dh_make to add a template debian/ folder, then hand-edit the certain files it created there. dh documentation is available here[1].

cdbs 'is a tool that uses debhelper to make building and maintaining Debian packages even easier'. Using cdbs involves adding "cdbs" to build-depends in debian/control, and the resulting debian/rules file can be made much, much shorter. cdbs documentation is available here[2].

Note that dh 7, which comes with jaunty, is supposedly better than cdbs. cdbs also has not been updated since 2006 with one update in 2009, while debhelper has seen continuous support. Might be better to stick to debhelper.

Building packages

Four ways:

• debuild - just builds the package, without installing anything or checking. This means that all -dev packages must be installed on the users system prior to building and removed (if they were installed by us) after. The users system isn't a 'clean' enviroment either as they have other packages installed - so something that is needed by the program, but it not listed as a dependency, will not be caught.

• pbuilder - needs to know a list of build-depends packages packages beforehand and a pbuilder enviroment requires a setup. It installs the needed packages when building and removes them after though, making it a "clean" enviroment. It's also the preferred Ubuntu MOTU way. It downloads a large amount of packages to initialize it though.
• sbuild - can initiate the build process in a schroot environment. It opens a schroot, installs the build-dependencies inside it and runs the clean, build and install target to build the debian package. The schroot is ended again after the build. Hence, this approach does not require root privileges to build the debian package.
• launchpad ppa - use debuild to make a .changes file and a bunch of others, and send that all off to a launchpad ppa for clean-room building (for lpia, 32bit, and 64bit architectures even).

Working with dh7

Prior to debhelper 7 (introduced in ubuntu intrepid), the process went like this:

• call dh_make with some arguments (license, etc)
  • this creates the initial debian/ folder with the common files
• hand-edit the debian/rules to add/remove calls to the dh_* helper functions during different stages of the program

dh7 introduced "override rules", which changes the rules editing process significantly for the better. Now, you can use a single "catch-all" rule, and override individual ones as necessary.

A catch-all and minimal rules looks like this:

#!/usr/bin/make -f
%:
    dh $@

Yeah, that's just it. This will compile a generic autotools (./configure ; make ; sudo make install) or python distutils package (dh_auto_configure takes care of that)

Now, you'll need to override rules in these cases:

• you want to pass arguments to functions - for example, enable specific options with ./configure

• you want to disable some dh_* calls.

For overriding, the syntax is:

override_dh_blah:
     what to do instead

ie since dh_auto_configure doesn't support waf, we want to override it:

override_dh_auto_configure:
     ./waf configure

or you want to enable some configure options:

override_dh_auto_configure:
     dh_auto_configure -- --enable-bla --disable-bla2 --with-something=woohoo

To disable a rule, override it with nothing.

debugging: doing

dh <debian/rules default rule, e.g. binary, clean, etc> --no-act

will display all of the dh_* calls that will be made.

Impelementation notes

Lets go with pbuilder and debhelper as the initial build stack. Additional components will be added / are welcome to be added later on.

Since pbuilder installs and uninstalls packages for us automatically, we'll just need to set the build-depends correctly. A plugin that will be making the package will try to automatically fill this out.

We can probably implement debhelper in the core, and cdbs if there is demand for it - these are just the only two systems, and since they are complex, I don't foresee any new ones showing up soon.

Functions that a package generation plugin must implement for the core to call

• if this is a build-system-specific plugin (for compiling source programs) - a check to see if it should be used to build the package. This will be used as part of the autodetection.
• a function to have it create and update the files in debian/ folder of the project as necessary (after the function returns, the package should be fine for building)

Functions that the core (or the debhelper plugin...) should provide to plugins

• a function to call the initial dh_make with some arguments

• a way to get/set the properties in certain fields of the debian/control file <- this probably requires a separate 'control' object with it's functions.
• a way to set the license - but this, being very common to all packages and ways of building, should be handled on it's own [3]

Examples

Example 1: In the following, the instructions required for packaging the ed gnu editor are listed. The instructions are taken from the ubuntudevelopers youtube videos [4][5]

• The tarball can be grabbed with: wget ftp://ftp.gnu.org/pub/gnu/ed/ed-1.0.tar.bz2
• Because the debian policy requires tar.gz tarballs in the form: packagename_version.orig.tar.gz the upstream tarball has to be repacked:
  • tar xjf ed-1.0.tar.bz2
  • tar czf ed_1.0.orig.tar.gz ed-1.0
• Next the debian template is created. Because the COPYING file inside the source directory mentions GPL-3 as the license the proper template can be created automatically:
  • cd ed-1.0 ; dh_make -c gpl -s -f ../ed_1.0.orig.tar.gz
• The example template files can be removed:
  • cd debian; rm *.ex *.EX dirs docs info README.Debian
• Next the changelog file can be edited using dch to change the release, version and comments.
• The control file can be edited to list the correct Section[6], Priority[7], Homepage and Descriptions. Also the build dependencies
• It is very important to edit the copyright file in order to list all license holders of the source code. The license of each file has to be respected. So if only one file out of hundreds has a different license it has to be listed here explicitly.
• The rules file that is created by dh_make should work for most autoconf/automake based sources.
• At last the dsc and diff.gz file can be created:
  • 'cd .. ; debuild -S -sa'