Ubuntu Wiki

Before we begin

• There are a lot of useful script and apps that have been developed over the years to make packaging .debs easier. I'll be using several of them in my session. If you want a head start install:

devscripts debhelper dpatch cdbs dh-make patchutils fakeroot lintian pbuilder

Also, it would be a great help if you can create an edgy pbuilder before class starts:

1. If you are running Edgy skip to step 2. If you are running Dapper download Edgy's debootstrap from [http://packages.ubuntu.com/cgi-bin/download.pl?arch=all&file=pool%2Fmain%2Fd%2Fdebootstrap%2Fdebootstrap_0.3.3.0ubuntu3_all.deb&md5sum=17dd4c70a76bd2aa33e8e095dec19b11&arch=all&type=main packages.ubuntu.com] and install it with dpkg -i

2. Install pbuilder sudo apt-get install pbuilder

3. Create a pbuilder by running:

sudo pbuilder create --distribution edgy \
        --othermirror "deb http://archive.ubuntu.com/ubuntu edgy universe multiverse"

4. Wait. debootstrap is creating a minimal ubuntu chroot environment so it can take some time.

IRC Log

Welcome to the MOTU School. These sessions are presented by the Universe development community (MOTU) as a way of helping Ubuntu users to get involved with Ubuntu development. See http://wiki.ubuntu.com/MOTU for more info. Today what I will be presenting is not in any way a comprehensive reference to packaging. What I want you to get out of this is some understanding of the tools and techniques that people use to make and maintain source packages.

First of all, we need to know what a source package is. A source package is actually made up of 3 different files:

1. .dsc (description) file that holds md5sums of the other files
2. .orig.tar.gz which is the source tarball as you would download it from the program's homepage
3. .diff.gz that holds any changes we make to the .orig.tar.gz

Today we are going to look at a particular source package, plotdrop. It's a fairly easy package, and was my first package from scratch. Ok let's make a temp directory where we can work in:

mkdir -p ~/motuschool/plotdrop
cd ~/motuschool/plotdrop
apt-get source plotdrop

Note 1: you need to have the source repo's (deb-src) enabled in your /etc/apt/sources.list BR Note 2: unlike apt-get install, you should not run apt-get source via sudo BR

OK, now you have 3 files (the source package) and a directory (which is the unpacked source package). Let's have a look around:

ls plotdrop-0.5/

and we see that this a small C program with typical files (COPYING, Makefile, Changelog, etc.). In fact, if we were to extract the tarball from the plotdrop homepage the only difference we would find is that debian directory. If you want you can look at the diff to the source tarball by:

zless plotdrop_0.5-0ubuntu1.diff.gz

Question from ubuntu_demon: The diff is between upstream and ubuntu ? or between debian and ubuntu ?

Answer: Between upstream (what you get from the app's homepage) and Ubuntu or between upstream and Debian if you are packaging for Debian or Ubuntu uses the Debian package without modification.

Now, let's actually dig into that debian/ directory and see what's going on:

cd plotdrop-0.5/debian/
ls

We see several files and a patches directory. All of the packaging info and patches to the source need to produce a good quality .deb are in here. What we need to do know is go through what the files are for.

Let's start with changelog:

less changelog

The first thing to note is that the format of the changelog is particular. dch is a program (found in the devscripts packages) that helps you with the formating. One the first line you will find the package name, version, and release. Each time a new source package is uploaded to the Ubuntu build machines it should have a higher version than the previous one. The version goes like this: (program version)-(debian revision)ubuntu(ubuntu revision)

In this case the program's version is 0.5, the Debian revision is 0 because at the time it wasn't in Debian, and the Ubuntu revision is 1 .

Question from FLeiXiuS: It's not automated by DCH right?

Answer: dch just creates a template

Question from redguy: what happens whem a package get included in debian?

Answer: the debian revision goes to 1 as in 0.5-1

Question from neutrinomass: The current kdeadmin source package version is "4:3.5.4-0ubuntu2 " . What does the '4:' mean ?

Answer: That is called an epoch which is used when upstream versioning has changed or package version mistakes. This assures that a newer package is installed even if the versioning scheme has changed. See http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version for more info.

Question from matid: Is it possible to append to a current changelog with dch?

Answer: Yes. Check man dch to find out about the options.

Question from gnube: Are there packages in Ubuntu that aren't in debian?

Answer: Yes. If a package doesn't isn't in Debian then (Debian revision) = 0 . If the package doesn't need any changes (which is what we like) then we just keep the Debian versioning. We only change the version when we need to.

Ok, back to the changelog file. Next we see various notes as to what was changed from one version to the next and finally a "who done it" line that shows who made the changes and at what time. The things to note here are that the name and email address you use are important and will be used to track who did what and if you digitally sign the package you will need to make sure the email address is the same that is in your gpg key but we'll get to that later

Ok, on to the control file

less control

The control file holds a lot of information about the source package and it's resulting binary package (.deb). It is arranged in field: value form and most of the fields are fairly self-explanitory but the values are, as you will see, more difficult to determine.

For the source package there is:

• Source: the source package name
• Section: what section of the repository does the program belong in
• Priority: is the program essential for a properly running Linux system?
• Maintainer: who is taking on the responsiblity, mostly for Debian
• Build-Depends: the packages that must be installed for the source package to be able to build the .deb
• Standards-Version: which version of the Debian Policy does this package adhere to

There are more fields available but these are found in most all packages. Check out the Debian Policy for more info: http://www.debian.org/doc/debian-policy/ch-source.html and http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-sourcecontrolfiles

Note that Priority is not random, there are specific values you can have and they are explained in the Debian Policy and Ubuntu Packaging Guide

Question from gnube: An improperly formatted control file can cause problems, correct?

Answer: Yes, it will fail to build. The packaging files are often read by various scripts so it is important to watch the formatting.

Question from gnube: Is there an automated tool to determine Build-Depends information?

Answer: Not really. There are a few scripts out there that can help, but mostly you need to figure out what the program needs to build and add them to Bild-Depends. Let's say a program uses GTK, it needs to have libgtk2.0-dev in the Build-Depends in order to compile correctly. Reading the README file in the source tarball as well as the programs homepage are a good idea.

For the binary package there is:

• Package: binary package name, you can have more than 1 per source package so you need to specify
• Architecture: what architecture the binary will build on. "any" means it should build on all archs and "all" means it doesn't have any arch dependent files (i.e. a program written in an interpreted language like python)
• Depends: the packages that the binary package depends on
• Description: First line holds the short description. Subsequent lines hold the long description. Be careful of the first space in each line, it is important.

This is again pretty self explainitory.