Ubuntu Packaging Guide

Introduction

Welcome to the Ubuntu Packaging Guide! This guide is primarily addressed to those who would like to make and maintain Ubuntu packages. Although many of the concepts in this guide could be used to make binary packages for personal use, it is designed for those people wanting to distribute their packages to and for others. While it is also written with the Ubuntu Linux distribution in mind, it should also be useful for any Debian-based distribution.

There are several reasons you might want to learn how to package for Ubuntu. First, building and fixing Ubuntu packages is a great way to contribute to the Ubuntu community. It is also a good way to learn how Ubuntu and the applications you have installed work. Maybe you want to install a package that is not in the Ubuntu repositories. Hopefully after you have completed this guide you will have the tools and knowledge you need to do all of these things.

Where to Begin

If you are completely new to Debian-based packaging then you will want to read this guide completely through, paying special attention to the section called Prerequisites, and the section Basic Packaging. People who are experienced with Debian-based packaging will find section Ubuntu Packaging and section Bugs most helpful.

Prerequisites

This guide assumes that the reader has a reasonable knowledge of building and installing software from source on Linux distributions. The guide also uses the Command Line Interface (CLI) throughout, so you should be comfortable using a terminal. You should be able to at least use the following:

• ./configure:This script is included in almost all Linux source, especially for software written in compiled languages such as C and C++. It is used to generate a Makefile (file used by make) that is properly configured for your system. Standard Debian packaging tools use it, so it is important that you know what the configure script does. Information on ./configure can be found in the make documentation.

• Apt/Dpkg: Beyond the basic use of installing programs, apt and dpkg have many features that are useful for packaging.

  • apt-cache dump - lists every package in the cache. This command is especially helpful in combination with a grep pipe such as apt-cache dump | grep foo to search for packages whose names or dependencies include foo.

  • apt-cache policy - lists the repositories (main/restricted/universe/multiverse) in which a package exists.

  • apt-cache show - displays information about a binary package.

  • apt-cache showsrc - displays information about a source package.

  • apt-cache rdepends - shows reverse dependencies for a package (which packages require the queried one.

  • dpkg -S - lists the binary package to which a particular file belongs.

  • dpkg -l - lists currently installed packages. This is similar to apt-cache dump but for installed packages.

  • dpkg -c - lists the contents of a binary package. It is useful for ensuring that files are installed to the right places.

  • dpkg -f - shows the control file for a binary package. It is useful for ensuring that the dependencies are correct.

  • grep-dctrl - searches for specialized information in packages. It is a specific use of the grep package (but not installed by default).

• diff and patch:

  • The diff program can be used to compare two files and to make patches. A typical example might be diff -ruN file.old file.new > file.diff. This command will create a diff (recursively if directories are used) that shows the changes, or delta, between the two files.

  • The patch program is used to apply a patch (usually created by diff or another similar program) to a file or directory. To apply the patch created above, we can invoke patch -p0 <>. The option -p tells patch how much it should strip from the paths for the file names in the patch. The option -p0 means to strip nothing, or leave the path intact.

make: GNU Make is a very important software building tool. It is used to transform a complex compilation task into a trivial one. It is important that you know how to use it, because we will store most of the information about the packaging process in a Makefile. Documentation is available at the GNU website.

Getting Started

Binary and Source Packages

Most users of a Debian-based distribution such as Ubuntu will never have to deal with the actual source code that is used to create all of the applications on their computers. Instead, the source code is compiled into binary packages from the source package that contains both the source code itself and the rules for making the binary package. Package maintainers upload the source packages with their changes to the build systems that then compile the binary packages for each architecture. A separate system distributes the generated binary .deb files and source changes to the repository mirrors.

Packaging Tools

" lang="en">">

There are many tools written specifically for packaging on Debian-based systems. Many of them are not essential to creating packages but are very helpful and often automate repetitive tasks. Their man and info pages are good sources of information. However, the following is a list of packages that are deemed necessary to begin packaging:

• build-essential is a metapackage that depends on libc6-dev, gcc, g++, make, and dpkg-dev. One package that you might not be familiar with is dpkg-dev. It contains tools such as dpkg-buildpackage and dpkg-source that are used to create, unpack, and build source and binary packages.

• devscripts contains many scripts that make the packager's maintenance work much easier. Some of the more commonly used are debdiff, dch, debuild, and debsign.

• ubuntu-dev-tools is also a collection of scripts (like devscripts), but specific for Ubuntu. It contains tools like update-maintainer, dgetlp, what-patch, pbuilder-dist, etc.

• debhelper are scripts that perform common packaging tasks.

• dh-make can be used to create a template for your packaging.

• diff and patch are used to create and apply patches, respectively. They are used extensively in packaging because it is easier, cleaner, and more efficient to represent small changes as patches rather than to have multiple copies of a file.

• quilt manages a series of patches by keeping track of the changes each of them makes. They are logically organized as a stack, and you can apply, un-apply, refresh them easily by traveling into the stack (push/pop). This package completely integrates into the CDBS, allowing maintainers using this new paradigm for their packaging scripts to benefit from the comfort of quilt when editing their diff against upstream. The package also provides some basic support for those not using CDBS.

• gnupg is a complete and free replacement for PGP used to digitally sign files (including packages).

• fakeroot simulates running a command with root privileges. This is useful for creating binary packages as a regular user.

• lintian and linda dissect Debian packages and report bugs and Policy violations. They contain automated checks for many aspects of Debian Policy as well as for common errors. linda is not available from the hardy heron repositories, but is still available in previous releases repositories.

• pbuilder constructs a chroot system and builds a package inside the chroot. It is an ideal system to use to check that a package has correct build dependencies and to build clean packages to be tested and distributed.

The Personal Builder: pbuilder

Using pbuilder as a package builder allows you to build the package from within a chroot environment. You can build binary packages without using pbuilder, but you must have all the build dependencies installed on your system first. However, pbuilder allows the packager to check the build dependencies because the package is built within a minimal Ubuntu installation, and the build dependencies are downloaded according to the debian/control file.

PbuilderHowto is a comprehensive guide to almost anything you could wish to do with pbuilder.

A short overview:

• to create a pbuilder environment, run

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

• to build a package using pbuilder, run

  sudo pbuilder build *.dsc

• to update a pbuilder environment, run

  sudo pbuilder update

• use pbuilder-dist (of the ubuntu-dev-tools) to have several different pbuilder setups for different Ubuntu releases.

Basic Packaging

Two of the problems that many novice packagers face are that there are multiple ways of packaging, and there is more than one tool to do the job.

Package development often requires installing many packages (especially -dev packages containing headers and other common development files) that are not part of a normal desktop Ubuntu installation. If you want to avoid installing extra packages or would like to develop for a different Ubuntu release (the development one, for instance) from what you currently have, the use of a chroot environment is highly recommended. A guide to setting up a chroot can be found at DebootstrapChroot.

We will go through two examples with the common build systems. We will use debhelper, the most common build system in Debian. It helps the packager by automating repetitive tasks. Then we will briefly cover the Common Debian Build System (CDBS), a more streamlined build system that uses debhelper.

Packaging From Scratch

Requirements: build-essential, automake, gnupg, lintian, fakeroot, pbuilder, debhelper and dh-make. In this example we will be using the GNU hello program as our example. You can download the source tarball from ftp.gnu.org. For the purposes of this example, we will be using the ~/hello/ directory.

mkdir ~/hello
cd ~/hello
wget http://ftp.gnu.org/gnu/hello/hello-2.4.tar.gz

If you are packaging your own software, or the software is not available as a tar.gz file, you can create the required .tar.gz from an unpacked source directory with a command like the following:

mkdir hello-2.4
tar czf hello-2.4.tar.gz hello-2.4

For the purpose of this example, we will also compare our package (hello) to one that is already packaged in the Ubuntu repository (called hello-debhelper). For now, we will place it in the ubuntu directory so we can look at it later. This will unpack the source:

mkdir ubuntu
cd ubuntu
apt-get source hello-debhelper
cd ..

Unlike most apt-get commands, you do not need to have root privileges to get the source package, because it is downloaded to the current directory. In fact, it is recommended that you only use apt-get source as a regular user, because then you can edit files in the source package without needing root privileges. What the apt-get source command does is:

1. Download the source package. A source package commonly contains a .dsc file describing the package and giving md5sums for the source package, an .orig.tar.gz file containing the source code from the author(s), and a .diff.gz file containing the packaging (in the debian/ directory) and patches applied against the source code.
2. Untar the .orig.tar.gz file into the current directory.
3. Apply the unzipped .diff.gz to the unpacked source directory.

If you manually download the source package (.dsc, .orig.tar.gz, and .diff.gz files), you can unpack them in the same way apt-get source does by using dpkg-source as follows:

dpkg-source -x *.dsc

We want to recreate the above from scratch. The first thing you will need to do is make a copy of the original (sometimes called "upstream") tarball in the following format: _.orig.tar.gz. This step does two things. First, it creates two copies of the source code. If you accidentally change or delete the working copy you can use the one you downloaded. Second, it is considered poor packaging practice to change the original source tarball unless absolutely necessary. See the section called “Common Mistakes” for reasons.

cp hello-2.4.tar.gz hello_2.4.orig.tar.gz
tar -xzvf hello_2.4.orig.tar.gz

The underscore, "_", between the package name (hello) and the version (2.4), as opposed to a hyphen, "-", is very important. The packaging tools will look for a file with that exact name. If you get it wrong, the result is that the tools will incorrectly assume that there is no original source at all and the package will be built as a Debian native package.

We now have a hello-2.4 directory containing the source files. Now we need to create the customary debian directory where all the packaging information is stored, allowing us to separate the packaging files from the application source files. We will let dh_make do the work for us:

cd hello-2.4
dh_make -e your.maintainer@address

dh_make will then ask you a series of questions about your package:

Type of package: single binary, multiple binary, library, kernel module or cdbs?
[s/m/l/k/b] s

Maintainer name : Your Name
Email-Address   : your.maintainer@address
Date            : Thu,  6 Apr 2006 10:07:19 -0700
Package Name    : hello
Version         : 2.4
License         : blank
Type of Package : Single
Hit  to confirm: Enter

Only run dh_make once. If you run it again after you do it the first time, it will not work properly. If you want to change it or made a mistake, remove the source directory and untar the upstream tarball afresh. Then you can migrate into the source directory and try again.

Running dh_make creates the basic files needed in debian/ and many template files (.ex) that may be needed. The Hello program is not very complicated, and as we have seen in the section called “Packaging From Scratch”, packaging it does not require much more than the basic files. Therefore, let us remove the .ex files:

cd debian
rm *.ex *.EX

For hello, some additional files from the debian directory will also be unnecessary:

• README.Debian: the README file for specific Debian issues, not the program's README.

• dirs: Used by dh_installdirs to create needed directories.

• docs: Used by dh_installdocs to install program documentation.

• info: Used by dh_installinfo to install the info file.

Keep in mind that for most packages, these files are required. For more information on them, see the section called “dh_make example files”.

At this point, you should have only changelog, compat, control, copyright, and rules files in the debian directory.

changelog

The changelog file is, as its name implies, a listing of the changes made in each version. It has a specific format that gives the package name, version, distribution, changes, and who made the changes at a given time. If you have a GPG key, make sure to use the same name and email address in changelog as you have in your key. The following is a template changelog:

package (version) distribution; urgency=urgency

* change details
 more change details
* even more change details

-- maintainer name [two spaces]  date

The format (especially of the date) is important. The date should be in RFC822 format, which can be obtained by using the command date -R. For convenience, the command dch may be used to edit changelog. It will update the date automatically.

Minor bullet points are indicated by a dash "-", while major points use an asterisk "*".

Here is a sample changelog file for hello:

hello (2.4-0ubuntu1) jaunty; urgency=low

* New upstream release with lots of bug fixes and feature improvements.

-- Captain Packager   Wed,  5 Jan 2009 22:38:49 -0700

Notice that the version has a -0ubuntu1 appended to it, this is the distro revision, used so that the packaging can be updated (to fix bugs for example) with new uploads within the same source release version.

Ubuntu and Debian have slightly different package versioning schemes to avoid conflicting packages with the same source version. If a Debian package has been changed in Ubuntu, it has ubuntuX (where X is the Ubuntu revision number) appended to the end of the Debian version. So if the Debian hello 2.4-1 package was changed by Ubuntu, the version string would be 2.4-1ubuntu1. If a package for the application does not exist in Debian, then the Debian revision is 0 (e.g., 2.4-0ubuntu1).

Now look at the changelog for the Ubuntu source package that we downloaded earlier:

less ../../ubuntu/hello-debhelper-2.2/debian/changelog

Notice that in this case the distribution is unstable (a Debian branch), because the Debian package has not been changed by Ubuntu. Remember to set the distribution to your target distribution release.

Consult Debian changelog Policy for more information.

control

" lang="en">">

The control file contains the information that the package manager (such as apt-get, synaptic, and adept) uses, build-time dependencies, maintainer information, and much more.

For the Ubuntu hello package, the control file looks something like:

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu MOTU Developers 
XSBC-Original-Maintainer: Captain Packager 
Standards-Version: 3.7.3
Build-Depends: debhelper (>= 5)
Homepage: http://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
The GNU hello program produces a familiar, friendly greeting. It
allows non-programmers to use a classic computer science tool which
would otherwise be unavailable to them. Seriously, though: this is
an example of how to do a Debian package. It is the Debian version of
the GNU Project's `hello world' program (which is itself an example
for the GNU Project).

In Ubuntu we set the Maintainer field to a general address because anyone can change any package (this differs from Debian where changing packages is usually restricted to an individual or a team).

Edit control using the information above (making sure to provide your information for the XSBC-Original-Maintainer field).

The first paragraph gives information about the source package. Let us go through each line:

• Source: This is the name of the source package.

• Section: The apt repositories are split up into sections for ease of browsing and categorization of software.

• Priority: This sets the importance of the package to users. It should be one of the following:

  • Required - packages that are essential for the system to work properly. If they are removed it is highly likely that your system will break in an unrecoverable way.

  • Important - minimal set of packages for a usable system. Removing these packages will not produce an unrecoverable breakage of your system, but they are generally considered important tools without which any Linux installation would be incomplete. Note: This does not include things like Emacs or even the X Window System.

  • Standard - Somewhat self explanatory.

  • Optional - in essence this category is for non-required packages, or the bulk of packages. However, these packages should not conflict with each other.

  • Extra - packages that may conflict with packages in one of the above categories. Also used for specialized packages that would only be useful to people who already know the purpose of the package.

• Maintainer: The name of the package maintainer and their email address.

• Standards-Version: The version of the Debian Policy to which the package adheres. An easy way to find the current version is apt-cache show debian-policy | grep Version .

• Build-Depends: One of the most important fields and often the source of bugs, this line lists the binary packages (with versions if necessary) that need to be installed in order to create the binary package(s) from the source package. Packages that are essential are required by build-essential and do not need to be included in the Build-Depends line. Note, that you don't need to list packages that are a part of build-essential. The list of build-essential packages can be found at /usr/share/doc/build-essential/list.

• Homepage: A URL where more information on the software can be found.

The second paragraph is for the binary package that will be built from the source. If multiple binary packages are built from the source package, there should be one section for each one. Again, let us go through each line:

• Package: The name for the binary package. Many times for simple programs (such as hello), the source and binary packages' names are identical.

• Architecture: The architectures for which the binary package(s) will be built. Examples are:

  • all - The source is not architecture-dependent. Programs that use Python or other interpreted languages would use this. The resulting binary package would end with _all.deb.

  • any - The source is architecture-dependent and should compile on all the supported architectures. There will be a .deb file for each architecture (_i386.deb for instance)

  • A subset of architectures (i386, amd64, ppc, etc.) can be listed to indicate that the source is architecture-dependent and does not work for all architectures supported by Ubuntu.

• Depends: The list of packages that the binary package depends on for functionality. For hello, we see ${shlibs:Depends}, which is a variable that is used by dpkg-shlibdeps to add the shared library packages needed by the binaries to Depends:. See the dpkg-source(1) and dpkg-shlibdeps(1) man page for more information.

• Recommends: Used for packages that are highly recommended and usually are installed with the package. Some package managers, most notably aptitude, automatically install Recommended packages.

• Suggests: Used for packages that are similar or useful when this package is installed.

• Conflicts: Used for packages that will conflict with this package. Both cannot be installed at the same time. If one is being installed, the other will be removed.

• Description: Both short and long descriptions are used by package managers. Note that there is one space at the beginning of each line in the long description. More information on how to make a good description can be found at http://people.debian.org/~walters/descriptions.html

copyright

This file gives the copyright information. Generally, copyright information is found in the COPYING file in the program's source directory. This file should include such information as the names of the author and the packager, the URL from which the source came, a Copyright line with the year and copyright holder, and the text of the copyright itself. An example template would be:

This package was debianized by {Your Name} 
{Date}

It was downloaded from: {URL of webpage}

Upstream Author(s): {Name(s) and email address(es) of author(s)}

Copyright:
     Copyright (C) {Year(s)} by {Author(s)} {Email address(es)}

License:

     {Add licence text here.  For GNU licences add the licence header
       and a link to the appropriate file in /usr/share/common-licences.}

Packaging:
     Copyright (C) {Year(s)} by {Your Name} 
     released under {the licence you choose for your packaging}

As one can imagine, hello is released under the GPL license. In this case it is easiest to just copy the copyright file from the Ubuntu package:

cp ../../ubuntu/hello-debhelper-2.2/debian/copyright .

Notice that the Ubuntu package's copyright includes a license statement for the manual. It is important that all the files in the source be covered by a license statement.

More information, caveats and tips are available in the Copyright section.

rules

The last file we need to look at is rules. This does all the work for creating our package. It is a Makefile with targets to compile and install the application, then create the .deb file from the installed files. It also has a target to clean up all the build files so you end up with just a source package again.

Here is a simplified version of the rules file created by dh-make:

package = hello

CC = gcc
CFLAGS = -g -Wall

ifeq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
CFLAGS += -O2
endif

#export DH_VERBOSE=1

clean:
     dh_testdir
     dh_clean
     rm -f build
     -$(MAKE) -i distclean

install: build
     dh_clean
     dh_installdirs
     $(MAKE) prefix=$(CURDIR)/debian/$(package)/usr \
             mandir=$(CURDIR)/debian/$(package)/usr/share/man \
             infodir=$(CURDIR)/debian/$(package)/usr/share/info \
             install

build:
     ./configure --prefix=/usr
     $(MAKE) CC="$(CC)" CFLAGS="$(CFLAGS)"
     touch build

binary-indep: install
# There are no architecture-independent files to be uploaded
# generated by this package.  If there were any they would be
# made here.

binary-arch: install
     dh_testdir -a
     dh_testroot -a
     dh_installdocs -a NEWS
     dh_installchangelogs -a ChangeLog
     dh_strip -a
     dh_compress -a
     dh_fixperms -a
     dh_installdeb -a
     dh_shlibdeps -a
     dh_gencontrol -a
     dh_md5sums -a
     dh_builddeb -a

binary: binary-indep binary-arch

.PHONY: binary binary-arch binary-indep clean checkroot

Let us go through this file in some detail. One of the first parts you will see is the declaration of some variables:

package = hello

CC = gcc
CFLAGS = -g -Wall

ifeq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
CFLAGS += -O2
endif

#export DH_VERBOSE=1

This section sets the flags for the compiler and also handles the noopt options for debugging.

Now look at the build rule:

build:
     ./configure --prefix=/usr
     $(MAKE) CC="$(CC)" CFLAGS="$(CFLAGS)"
     touch build

This rule runs ./configure with the proper prefix, runs make, and creates a build file that is a timestamp of the build to prevent erroneous multiple compilations.

The next rule is clean, which runs make -i distclean and removes the files that are made during the package building.

clean:
     dh_testdir
     dh_clean
     rm -f build
     -$(MAKE) -i distclean

Next we see an empty binary-indep rule. Some packages create architecture-independent .debs if they do not contain files that are specific to the processor. Most Python or artwork packages would be examples of this, their packages end with _all.deb.

hello is a C program, so it compiles different code for each architecture. The packages will end with _i386.deb for 32bit, _amd64.deb for 64bit, _lpia.deb for MIDs and etc. For these architecture-dependent packages, binary-arch field is used:

binary-arch: install
     dh_testdir -a
     dh_testroot -a
     dh_installdocs -a NEWS
     dh_installchangelogs -a ChangeLog
     dh_strip -a
     dh_compress -a
     dh_fixperms -a
     dh_installdeb -a
     dh_shlibdeps -a
     dh_gencontrol -a
     dh_md5sums -a
     dh_builddeb -a

This is running a number of debhelper scripts which create our .deb packages. dh_testdir and dh_testroot make some sanity checks. dh_installdocs and dh_installchangelogs install files which you can specify in *.doc and *.changelog files. dh_strip will take debugging symbols out of the application files making them much smaller. dh_compress runs gzip on some documentation files. dh_shlibdeps adds library dependencies to the "Depends: ${shlibs:Depends}" field in debian/control. Finally dh_builddeb builds our .deb file. You do not have to worry too much about these scripts, they should create the packages without problems.

There is one other file, compat which just contains a version number for the debhelper scripts. Occationally new versions of debhelper are released, the current version is 6 so you should set compat to 6. If it is set to an older version then the debhelper scripts will behave slightly differently.

Building the Package

You are now ready to build the package. There is a simple command to do this.

debuild

Debuild will first check that all the build-depends packages are installed, it will then use dpkg-buildpackage to compile, install and build the .debs using the rules in debian/rules. If that succeeds it will attempt to digitally sign the packages with GPG, if it gives an error that it can not find your key that means it has successfully compiled the .deb packages but you do not have a GPG key with the same name, comment, and e-mail as you used in debian/changelog. See GnuPrivacyGuardHowto for instructions on creating your key.

Your finished package should now be in the directory above your source. Have a look at it and install it.

cd ..
lesspipe *deb
sudo dpkg --install *deb

Building the Source Package

Now that we have gone through the files in the debian directory for hello in detail, we can build the source (and binary) packages. First let us move into the root of the extracted source then we build the source package using debuild:

debuild -S

The -S flag tells debuild to build a source package using another script dpkg-buildpackage and fakeroot to allow us to have fake root privileges when making the package. It will take the .orig.tar.gz file and produce a .diff.gz (the difference between the original tarball from the author and the directory we have created, debian/ and its contents) and a .dsc file that has the description and md5sums for the source package. The .dsc and *_source.changes (used for uploading the source package) files are signed using your GPG key.

If you do not have a gpg key set up you will get an error from debuild. You can either set up a gpg key or use the -us -uc keys with debuild to turn off signing. However, you will not be able to have your packages uploaded to Ubuntu without signing them. To make sure debuild finds the right gpg key you should set the DEBFULLNAME and DEBEMAIL environment variables (in your ~/.bashrc for instance) to the name and email address you use for your gpg key and in the debian/changelog. Some people have reported that they were unable to get debuild to find their gpg key properly, even after setting the above environment variables. To get around this you can give debuild the -k flag where is your gpg key ID.

To check the package builds in a clean environement we can also build the binary package with pbuilder:

sudo pbuilder build ../*.dsc

Using pbuilder to build the binary packages is very important. It ensures that the build dependencies are correct, because pbuilder provides only a minimal environment, so all the build-time dependencies are determined by the control file.

We can check the source package for common mistakes using lintian:

cd ..
lintian -Ivi *.dsc

Requirements for new Ubuntu packages

When a source package is uploaded to Ubuntu which does not yet exist in the archive, or builds a new binary package, it will be held in the NEW queue and has to be reviewed by an Ubuntu archive team member.

Packaging

• Most importantly: see copyright and licensing information below.

• The source and binary packages should have a sane name: neither they should clutter the namespace (such as "editor") nor should they have an entirely nonsensical name (such as "new-stuff-manager").

• debian/control and debian/rules should build packages with the right Architecture:, Build-Depends[-Indep]:, and rules target (binary-arch vs. binary-indep).

• Maintainer and init scripts should not excessively mess up the system.

• A more comprehensive list of package checks is available from the Code Review page.

Other

• The Debian NEW Reject FAQ lists some important special cases which mostly apply to Ubuntu as well.

• Process documentation: UbuntuDevelopment/NewPackages

Packaging With CDBS

CDBS is a set of Makefile includes that uses debhelper to make building and maintaining Debian packages even easier. It uses advanced features of Makefiles to abstract the build process, so rules files end up primarily as a series of include statements. It has many advantages:

• It produces a short, readable, and efficient debian/rules

• It automates debhelper use for you, so you do not have to worry about repetitive tasks

• It helps you focus on more important packaging problems, because it helps without limiting customization
• Its classes have been well tested, so you can avoid dirty hacks to solve common problems

• Switching to CDBS is easy

• It is extendable

However if your package has an oddity about how it is built you may need to tackle some of the Makefile syntax to extend CDBS and tell it what is needed.

Using CDBS for Ubuntu packages is very easy, if the software you are packaging can be configured and built using the GNU autoconf tools (the "configure-make-make install" idiom). After adding cdbs to the Build-Depends in debian/control, a basic debian/rules file using CDBS can fit in 2 lines. For a simple C/C++ application with no extra rules, such as hello, debian/rules can look like this:

#!/usr/bin/make -f
                          
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk

That is all you need to build the program! CDBS handles installing and cleaning. You can then use the .install and .info files to tune your package with the usual debhelper functions in the various sections for debian/rules.

Sometimes the upstream author has hardwired non-standard defaults into the autoconf scripts. For example, a package may place man pages in /usr/man/. In this case, you can specify the correct path using the following:

DEB_CONFIGURE_MANDIR=/usr/share/man

Another situation frequently encountered with configure scripts is that you need to specify certain configuration options provided by the software author. This is handled by substituting the appropriate option for the right side of a DEB_CONFIGURE_EXTRA_FLAGS assign statement like the following:

DEB_CONFIGURE_EXTRA_FLAGS = --enable-graphics --with-gsl=/usr

Here is the list of standard configure options that are always passed to configure:

--prefix=$(DEB_CONFIGURE_PREFIX)
--includedir=$(DEB_CONFIGURE_INCLUDEDIR)
--mandir=$(DEB_CONFIGURE_MANDIR)
--infodir=$(DEB_CONFIGURE_INFODIR)
--sysconfdir=$(DEB_CONFIGURE_SYSCONFDIR)
--localstatedir=$(DEB_CONFIGURE_LOCALSTATEDIR)
--libexecdir=$(DEB_CONFIGURE_LIBEXECDIR)

CDBS mostly works by including .mk Makefiles in debian/rules. The cdbs package provides such files in /usr/share/cdbs/1/ that allow you to do quite a lot of packaging tasks. Other packages, such as quilt, add modules to CDBS and can be used as Build-Depends. Note that you can also use your own CDBS rules and include them in the package. The most useful modules included with the cdbs package are:

• rules/debhelper.mk: Calls debhelper in all required sections

• rules/dpatch.mk: Allows you to use dpatch to ease patching the source. Must be included before any other rule.

• rules/simple-patchsys.mk: Provides a very easy way to patch the source

• rules/tarball.mk: Allows you to build packages using the compressed tarball in the package

• class/autotools.mk: Calls autotools in all required sections

• class/gnome.mk: Builds GNOME programs (requires the proper Build-Depends in debian/control)

• class/kde.mk: Builds KDE programs (requires the proper Build-Depends in debian/control)

• class/xfce.mk: Build Xfce4 programs (requires the proper Build-Depends in debian/control)

• class/python-distutils.mk: Facilitates packaging Python programs

It may happen that you need to patch files belonging to the autoconf system, in which case you will probably need to run aclocal, automake and autoconf after applying the patch. CDBS has options to assist you in this situation. It will run patch first, then rebuild autotools, and finally run configure "et al." Here is an example where versions 1.10 of autoconf and automake are chosen:

include /usr/share/cdbs/1/rules/dpatch.mk
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk

DEB_AUTO_UPDATE_ACLOCAL = 1.10 -I ./config
DEB_AUTO_UPDATE_LIBTOOL = pre
DEB_AUTO_UPDATE_AUTOMAKE = 1.10 --foreign --add-missing --copy
DEB_AUTO_UPDATE_AUTOCONF = 1.10

The DEB_AUTO_UPDATE_LIBTOOL variable can take the values "pre" or "post", depending on how you want libtool to be run. Notice that (curiously) aclocal is only invoked if aclocal.m4 is already present in the top level directory.

A word of warning is in place at this point: Some packagers do not trust that the autoconf system can be generated correctly on a foreign build system.

CDBS runs the debhelper scripts after the package has been compiled and installed. Sometimes you may need to modify the behaviour of certain debhelper scripts. A bunch of variables are available for this purpose:

debhelper script	CDBS variable
dh_builddeb	DEB_BUILD_DEB_ARGS
dh_compress	DEB_COMPRESS_ARGS
dh_fixperms	DEB_FIXPERMS_ARGS
dh_gencontrol	DEB_GENCONTROL_ARGS
dh_installcatalog	DEB_INSTALLCATALOGS_ARGS
dh_installchangelogs	DEB_INSTALLCHANGELOGS_ARGS
dh_installdebconf	DEB_INSTALLDEBCONF_ARGS
dh_installdeb	DEB_INSTALL_DEB_ARGS
dh_installemacsen	DEB_INSTALLEMACSEN_ARGS
dh_installinit	DEB_INSTALLINIT_ARGS
dh_installlogcheck	DEB_INSTALLLOGCHECK_ARGS
dh_installlogrotate	DEB_INSTALLLOGROTATE_ARGS
dh_installmime	DEB_INSTALLMIME_ARGS
dh_installpam	DEB_INSTALLPAM_ARGS
dh_installudev	DEB_INSTALLUDEV_ARGS
dh_install	DEB_INSTALL_ARGS
dh_makeshlibs	DEB_MAKESHLIBS_ARGS
dh_md5sums	DEB_MD5SUMS_ARGS
dh_perl	DEB_PERL_ARGS
dh_shlibdeps	DEB_SHLIBDEPS_ARGS
dh_strip	DEB_STRIP_ARGS

See the manpages of the individual debhelper scripts to see what options are available. One thing that is commonly needed is to exclude files from the action of certain debhelper scripts. For example, you may arrange that a certain file maintains the permissions with which it was installed, and not become modified by the dh_fixperms script:

DEB_FIXPERMS_EXCLUDE = /usr/sbin/suid-program

" lang="en">">

The complete list of CDBS' exclude variables is:

DEB_COMPRESS_EXCLUDE

DEB_FIXPERMS_EXCLUDE

DEB_CLEAN_EXCLUDE

DEB_DH_ALWAYS_EXCLUDE

DEB_STRIP_EXCLUDE

Packaging Python modules with CDBS

CDBS is also very well suited for packaging Python modules, when these make use of the distutils building system. Following is an example of a debian/rules file, which in fact could be used ad verbatim for a great number of not-too-complicated modules. Notice that we also tell CDBS not to compress Python source files:

DEB_PYTHON_SYSTEM=pysupport

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/python-distutils.mk

# Don't compress .py files
DEB_COMPRESS_EXCLUDE := .py

Important note on DEB_AUTO_UPDATE_DEBIAN_CONTROL:: Do not use DEB_AUTO_UPDATE_DEBIAN_CONTROL:=yes to automatically change debian/control. It can cause bad things, and Debian considers it a reason to reject a package from entering the archives. See http://ftp-master.debian.org/REJECT-FAQ.html for more information.

For more information on CDBS, see Marc Dequènes's guide at https://perso.duckcorp.org/duck/cdbs-doc/cdbs-doc.xhtml.

See also this tutorial.

Advanced Packaging

Creating More Than One Binary Package

Often you will want to split a source package into more than one binary package.

For single binary packages files are installed to debian/ and packaged from there. For multiple packages they are installed to debian/tmp and split up by using multiple .install files ">

Packaging Shared Libraries

This document explains what shared libraries are, focusing on exported symbols, and explains some of the details of how to package them.

It is a work in progress, based on a MOTU/School session. To see the log of that session please see MOTU/School/LibraryPackaging

Shared Libraries

Shared libraries are object files containing compiled code that can be linked in to an executable. This is usually done for one of two reasons:

1. To provide a dynamically loaded plugin mechanism using dlopen.

2. To share code between multiple applications.

This guide will mainly concern itself with the second application.

The structure of an (ELF) shared library is an object file containing "symbols" split in to "sections". Usually the details of the sections used are not important when packaging, merely the list of symbols, and as such we will focus on those.

A symbol is an item that is exported from the shared object. This means that it is accessible from an executable that loads the shared library. A symbol can be a variable, or a function, or something else like a struct. If it is a variable then the executable can read and write the value of the variable, and if it is a function then the executable can call the function.

The important thing to note is that if an executable contains code to call a function do_foo that it expects to find in libfoo.so and libfoo.so does not export a function with that name the program will not run. There are more complications that arise if the program and the library differ in what they think the definition of a symbol are, and so we must strive to make sure that this never happens.

Where a symbol comes from

Symbols are created by the compiler from certain constructs in the source code. Consider the following code:

#include 

static int static_global = 42;
int extern_global;
const int const_extern_global = 42;

static void
local_function(int n)
{
     int local_var = 3;
     static int static_local_var = 23;

     if (n > 3) {
             local_var = n;
             static_local_var = 2 * n;
     }

     if (local_var > 4) {
             fprintf(stderr, "static_var=%d\n", static_global);
     } else {
             fprintf(stderr, "static_local_var=%d\n", static_local_var);
     }
}

void
global_function(int n)
{
     fprintf(stderr, "extern_global=%d\n", extern_global);
}

int
main(int argc, char **argv)
{
     local_function(argc);
     global_function(argc);

     return 0;
}

When this code is compiled the compiler will decide whether each of the variables, functions etc. used in the code should be exported as a symbol. If we compile this code we will be able to see what becomes a symbol. Save the code to a file named

• example.c and then run the following command to compile it:

$ gcc -c example.c -o example.o

This doesn't create a shared library yet, just an object file, but we are able to see some of the symbol information. Use nm to see the symbol list:

$ nm example.o
00000000 R const_extern_global
00000004 C extern_global
      U fprintf
0000006b T global_function
00000000 t local_function
00000092 T main
00000000 d static_global
00000004 d static_local_var.1781
      U stderr

In the rightmost column you can see the name of each of the symbols. There is one created for most of the variables and functions used in the file. However, local_var is not there, as this is a local variable to a function, and as such is allocated on the stack.

The other interesting feature is the number that is included in the name of static_local_var. This is to avoid name clashes if you were to have a static variable named static_local_var in another function in the file. (However, as we will see, this symbol will not make it in to the shared object, so this point is not too important.)

In the middle column of the output there are letters that correspond to the type of symbol. You can find the definitions in man nm. The ones listed above are

• R - The symbol is in the read only data section.

• C - Common symbol, i.e. uninitialized data.

• U - The symbol is defined somewhere other than this file.

• T - The symbol is in the text section, i.e. it is code.

• t - The symbol is in the text section.

• d - The symbol is in the initialized data section.

You may notice that the local symbols are given a lowercase letter, and the global symbols an uppercase letter. This means that only symbols with an uppercase letter will make it in to the shared object.

The interesting symbols are the ones given the symbol U, which indicates that they refer to the symbol, but do not define it, which means that it must be defined elsewhere. In this case stderr and fprintf fall in to that category, as they are defined in libc. The symbols will be matched up by the linker later.

---

CategoryPackagingGuide

Common Mistakes

dh_make Example Files

When you use dh_make to create the initial "debianisation", example files for various tasks are created in the debian/ directory. The templates have a .ex extension. If you want to use one, rename it to remove the extension. If you do not need it, remove it to keep the debian/ directory clean.

Abusing dh_installdirs .dirs files

Many packages wrongly use dh_installdirs and .dirs files to create directories. 99% of those cases are not necessary, since dh_install and .install files will automatically take care of creating directories. You only need to use dh_installdirs if your package needs to ship empty nonstandard directories, e. g. /etc/mypackage/plugins.d/.

Changing the Original Tarball

There are two types of source packages, native and non-native.

A native package is one that is specific to Ubuntu/Debian. It has the debian/ directory containing the packaging information and any changes to the source included in the tarball (usually _.tar.gz).

Non-native packages are more common. A non-native package splits the source package into a _.orig.tar.gz tarball that is identical (hopefully including md5sum) to the source tarball downloaded from the project's homepage and a .diff.gz file that contains all the differences (debian/ directory and patches) from the original source tarball. This whole paragraph just deals with non-native packages.

Here is a list of potential problems that can occur if you change the original tarball:

1. Reproducibility: If you take just the .diff.gz and .dsc, you or someone else has no means to reproduce the changes in the original tarball.

2. Upgradeability: It is much easier to upgrade to a new upstream (from the author) version if the .orig.tar.gz is preserved and there is a clear separation between the upstream source and the changes made to produce the Ubuntu source package.

3. Debian to Ubuntu Synchronization: Changing original tarballs makes it hard to automatically sync from Debian to Ubuntu. Normally, only the .diff.gz and .dsc files change within the same upstream version, since the .orig.tar.gz file is shared by all the Debian or Ubuntu revisions. It is much more difficult to sync if the md5sums of the .orig.tar.gz files are not the same.

4. Usage of Revision Control for Debian package: If you use svn (and svn-buildpackage) or similar tools to handle your Debian package, you usually don't store the original tarball inside. If someone else does a checkout, he'll need to get the original tarball separately. Other revision control systems can be used to track only the packaging files (debian/, etc.) and not the whole source. However, if the .orig.tar.gz is not the same, then obviously problems can occur.

5. Security tracking: Consider a situation where someone wants to introduce a backdoor/rootkit or other evil stuff. If the original tarball is intact, it can be scanned easily through the .diff.gz to see if the person who modified the package tried to do something evil. If the tarball has changed, however, you also need to check the differences between the tarball and the original source.

6. The .diff.gz: The option to use the .diff.gz to reflect changes to the original tarball already exists, so it is easy to make changes without touching the original tarball.

It is acceptable to change the original tarball if one or more of the following hold true:

• It contains non-free parts that cannot be redistributed. Remove those parts, and note it in the packaging. Often such packages use "dfsg" (which stands for Debian Free Software Guidelines) in the package name and/or versioning to indicate that non-free parts have been removed.
• The authors only provide bzip2'ed source.

  • Just bunzip2 the .tar.bz2 and gzip -9 the resulting tar.

  • The md5sums of the .tar you provide and the original .tar must match!
  • Eventually provide a get-orig-source rule in debian/rules that does this conversion automatically.
• Directly imported from SVN
  • Provide get-orig-source in debian/rules.

The following are not reasons to change the original tarball:

• Wrong Directory Layout

• Files need to be removed to keep the .diff.gz small (e.g., files created by autotools). Everything that needs to be deleted should be removed in the clean rule. Since the .diff.gz is created with diff -u, you will not see removed files in the .diff.gz.

• Files need to be modified. Files that need to be modified should to go into .diff.gz. That is its purpose!

• Wrong permissions on files. You can use debian/rules to do this.

Solutions

• get-orig-source:
       cd ..; wget http://somesite.org/stuff/somesoftware-4.2.tar.bz2
       bzcat ../somesoftware-4.2.tar.bz2 | gzip -9fn -c - > ../somesoftware-4.2.tar.gz
       ln -s somesoftware-4.2.tar.gz ../${DEB_SOURCE_PACKAGE}_4.2.orig.tar.gz

• get-orig-source for zip files:

  PACKAGE := $(shell dpkg-parsechangelog | sed -n 's/^Source: //p')
  VERSION := $(shell dpkg-parsechangelog | sed -ne 's/^Version: \(.*\)-.*/\1/p')
  
  get-orig-source:
       rm -rf $@
       mkdir -p $@/$(PACKAGE)-$(VERSION)
       cd $@ && wget http://somesite.org/stuff/somesoftware-$(VERSION).zip
       unzip -o $@/somesoftware-$(VERSION).zip -d $@/$(PACKAGE)-$(VERSION)
       cd $@ && tar -cf - $(PACKAGE)-$(VERSION) | gzip -9f - > ../../$(PACKAGE)_$(VERSION).orig.tar.gz
       rm -r $@

• another get-orig-source target:

  get-orig-source:
       cd .. && wget http://somesite.org/stuff/somesoftware-4.2.tar.bz2
       tar xjf ../somesoftware-4.2.tar.bz2
       rm ../somesoftware-4.2.tar.bz2
       mv somesoftware-4.2 somesoftware-4.2.orig
       tar -cf ../somesoftware-4.2.orig.tar somesoftware-4.2.orig
       rm -fr somesoftware-4.2.orig
       gzip -9fn ../somesoftware-4.2.orig.tar

  (and maybe also provide the rule ../somesoftware_4.2.orig.tar.gz: get-orig-source , or list get-orig-source within .PHONY).

• if you use a watch file, this can be:

  # Path to the debian directory
  DEBIAN_DIR := $(shell echo ${MAKEFILE_LIST} | awk '{print $$1}' | xargs dirname )
  UPSTREAM_VERSION ?=$(shell uscan --dehs | sed -n 's/.*\(.*\)<\/upstream-version>.*/\1/p')
  
  get-orig-source:
       cd ${DEBIAN_DIR}/.. && uscan --force-download
       bzcat ../somesoftware-${UPSTREAM_VERSION}.tar.bz2 | gzip -9fn -c - > \
       ${CURDIR}/${DEB_SOURCE_PACKAGE}_${UPSTREAM_VERSION}.orig.tar.gz

• directly imported from cvs

  CVSDATE+=22 May 2007
  SW_VERSION+=4.2
  
  TARFILE+=somesoftware_$(SW_VERSION)~cvs$(shell date -d "$(CVSDATE)" +%Y%m%d).orig.tar.gz
  CVSHOME+=:pserver:anonymous@somesoftware.cvs.sourceforge.net:/cvsroot/somesoftware
  
  get-orig-source::
       cvs -d$(CVSHOME) login
       cvs -d$(CVSHOME) export -D "$(CVSDATE)" somesoftware
       tar czf $(CURDIR)/../$(TARFILE) $(CURDIR)/somesoftware
       rm -rf $(CURDIR)/somesoftware
  
  ../$(TARFILE):: get-orig-source

get-orig-source target:

Tips

• It's always a good idea to contact upstream and ask that stuff like autoconf-issues or directory layout (or old FSF-address) or other things you need to "patch" afterwards in .diff.gz be corrected.
• Older packages (from Debian Policy 3.3.8 or earlier) keep the information on repacking in debian/README.Debian-source. When updating an older package, it is acceptable to leave it here, although when upgrading or packaging new software, debian/copyright is much preferred.

• If a package already contains a debian/ dir: Do not repackage it. You can ask the author(s) to delete the debian/ dir and provide a diff.gz instead. This makes it easier to review their work, and it separates packaging from program source. It is always a good idea to contact the program's author(s) and ask if you may correct autoconf issues, directory layout, an outdated Free Software Foundation address in COPYRIGHT files, or other things that are not specific to the packaging but would be convenient for you so you do not need to "patch" the source in .diff.gz.

Always remember to reference get-orig-source: in debian/rules when you need to repack the orig.tar.gz, explaining why you repacked it, and how others can verify your work.

Copyright Information

When dealing with copyright information of packages, the following points are critical, since they determine whether we are allowed at all to redistribute the package. Packages must not be accepted if any of these points is not fulfilled:

• The upstream tarball must contain verbatim copies of all licenses that are used by the files in the tarball. References to URLs or paths to system files (such as /usr/share/common-licenses/) are not sufficient. The license(s) must accompany the source code.

• For all files it must be clear under which license they fall. Source code files should usually have a short comment at the top which points out the license.

• Files shipped under the GPL must be in the 'preferred form of modification' format. This applies to some other free licenses like the MPL, too (but e. g. not to BSD). Negative examples are Flash animations (*.swf), most PostScript/PDF files, and automatically generated source code. The suspicious-source script in the ubuntu-dev-tools package helps to spot such files.

• debian/copyright must list the primary copyright holders and all licenses (use pointers to /usr/share/common-licenses/ licenses included there), and declare which licenses apply to which parts of the package.

• Since there are now multiple versions of the GPL and LGPL, the copyright headers and files must be clear about which version(s) apply.

Common errors:

• Not shipping a copy of the LGPL when e. g. the build system is under LGPL, but the actual source is GPL

• Shipping PDFs and other files without source like a LaTeX or OpenOffice document

• Documentation is actually under GFDL, but debian/copyright does not mention it. As of gutsy, the GFDL is in /usr/share/common-licenses/, so a pointer there is sufficient for debian/copyright.

• debian/copyright only mentions a license, but no copyright

• The source files and/or debian/copyright are not clear about which files fall under which license

• Source is shipped under "GPL 2 only", while debian/copyright says "GPL 2 or later"

• GPLed packages link against OpenSSL (directly or indirectly)
• Different copyright holders and different licenses not mentioned in debian/copyright. Please grep -ir copyright * your package's directorys to make sure you got them all. In the case of large numbers of trivial copyright holders, not all need be mentioned (ask on IRC if you are in doubt), but all licenses must be listed.

The rule of thumb is: look at copyright definitions in the source code, the accompaning COPYING/AUTHORS file and at the involved licenses. There is no such thing as a general rule of thumb to get it right: Different licenses have different requirements for redistribution. While a public domain license may even state that you can do everything with the source code (which would mean that you need not put anything into debian/copyright, or could even choose your own "may be distributed in cd form only on rainy saturday's"-license), other licenses will impose certain restrictions like including the copyright statement and/or authors and making it clear if the source code is altered from its original form. Sometimes the involved licenses even conflict with each other (e.g. GPL and OpenSSL-license), which means that the resulting binary package cannot be distributed.

Example 1: GPL

The GPL requires that the complete license text is distributed (you can refer to /usr/share/common-licenses/GPL, which is always there on debian/ubuntu systems), the authors and the short disclaimer of warranty (which you should include into debian/copyright). For example

License: GPL-2

Copyright (C)   
.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA

X-Comment: On Debian GNU/Linux systems, the complete text of the GNU General
Public License can be found in the /usr/share/common-licenses/GPL file.

Please note that we use the new machine-readable copyright format here.

Please also note, that upstream may also choose to restrict the license to one specific version of the GPL, then you'll need to modify the text above. Usually that very disclaimer can be found in the sourcecode of a package. Then you can simply paste it to debian/copyright.

Always ensure you are using the correct version, GPL 2 or 3, LGPL 2.0, 2.1 or 3. Use licencecheck to check that the licence of all files is consistent. Make sure full copies of the licences used are included by upstream, it is not uncommon for LGPL or FDL to be missing.

General advice

Combining GPL and another license will always make the combined work to be GPL or, if the licenses conflict, undistributable. What licenses can be combined can be found at http://www.gnu.org/licenses/license-list.html.

Usually you will need to list the different licenses as well in debian/copyright. A good way to do this, is to list files with a different license together with the license in question. Whether you will actually need to list the different licenses depends solely on the license involved.

What you don't need to mention is licenses from libraries against which the package links. They are accompanied by their own copyright file and the package in question can never be installed w.o. the library in question. Of course there are exceptions which impose different restrictions, like the OpenSSL license which requires a disclaimer to be present in debian/copyright if it's used (as in linked against) in a project. But these additional restriction mean, that the used library is incompatible with the GPL.

While usually most of the projects don't have any legal issues, it's very simple to introduce these with inaccurate copyright-files. Finally there is a rule of thumb: Better safe than sorry - be verbose and list everything which you are not sure if it should go into debian/copyright or not.

Reference Packages

Simple installation of files

ubuntu-artwork

example-content

PHP

gallery2

roundcube

Python
Python Central	Python Support
jokosher	linda
scribes	bittornado
pyenchant	aptoncd
python-imaging	exaile
pyparallel	rhythmbox

debconf

wvdial

Maintainer scripts (postinst, postrm, prerm, preinst)

Java packages

">

Patch Systems

Quite often it turns out that the upstream source needs to be patched, either to adjust the program to work with Ubuntu or to fix bugs in the source before they are fixed upstream. But how should we represent these changes? We could simply make the changes in the unpacked source package, in which case the patch would be expressed in the .diff.gz file. However, this is not ideal. If there is more than one patch you lose the ability to separate the patches as you just see one big diff that also contains the packaging files (in debian/). This can make it more difficult when you want to send the patches upstream. It is also very convenient to separate the author's source from the changes made for Ubuntu. The best place to put this information is in the debian/ that is already used for the packaging files. For the rest of this chapter we will be looking at the various ways to set up patches in this way.

General Tips

There will almost always be the need to apply patches before building a package. Here are a few patching tips taken from http://wiki.debian.org/Games/ToolsDiscuss .

Some tips on how to use patches efficiently (Thanks Linas Žvirblis):

• Provide descriptive file names for your patches: 'fix-loading-libfoo-on-architecture-bar.patch' is a good name, '001.patch' is not;
• Make your patches stand-alone. Each patch should apply cleanly without depending on any other patch being applied;
• Avoid modifying the same file in multiple patches;
• If you absolutely need to create patches that depend on each other, specify that in the filenames: '00patchfoo-do-this.patch', '01patchfoo-do-that.patch' or similar;
• Do not include multiple unrelated modifications into a single patch;
• Patch your packages at build time. There is no need to ship a patch plus an already patched source. This only increases the size of the diff.
• Make sure patch is applied before anything else happens with your package. Make configure rule depend on the patch rule;
• Clean first, unpatch afterwards. Some files could have been modified during the build so unpatching may fail, unless you restore them. If simply makecleaning the sources does not restore their state, it may be a good idea to make backup copies, for example, in patch rule.

• Debian policy 3.8.0 imposes that packages specify explicit how to apply their patches when using a patch system (cf. [WWW] http://lists.debian.org/…ce/2008/06/msg00001.html). The page README.sourceHowTo attempts to collect sample README.source file for each packaging systems.

• To find out which patch system is used, use what-patch from the ubuntu-dev-tools package (also requires CDBS to be installed):

  daniel@lovegood:~/jokosher-0.9$ what-patch
  cdbs
  daniel@lovegood:~/jokosher-0.9$

  or

  daniel@lovegood:~/seahorse-2.22.2$ what-patch
  quilt
  daniel@lovegood:~/seahorse-2.22.2$ 

Patching Without a Patch System

As was mentioned above, one can patch the original source by simply making the changes in the unpacked source directory. A real-life example of this is cron. If you grab cron's source package and look at the .diff.gz you will see that several of the original source's files were changed.

apt-get source cron
zgrep +++ cron*.diff.gz

But as we mentioned before this is not really the best way to represent patches. One better way is to create individual patch files, put them in debian/patches/ and apply the patches (using patch) in debian/rules. This is what is done for udev:

apt-get source udev
zgrep +++ udev*.diff.gz
ls udev*/debian/patches/
less udev*/debian/rules

The rules file has the following rules for applying and unapplying the patches:

# Apply patches to the package
patch: patch-stamp
patch-stamp:
     dh_testdir
     @patches=debian/patches/*.patch; for patch in $$patches; do \
             test -f $$patch || continue; \
             echo "Applying $$patch"; \
             patch -stuN -p1 < $$patch || exit 1; \        done        touch $@  # Remove patches from the package unpatch:        dh_testdir        @if test -f patch-stamp; then \                patches=debian/patches/*.patch; \                for patch in $$patches; do \                        reversepatches="$$patch $$reversepatches"; \                done; \                for patch in $$reversepatches; do \                        test -f $$patch || continue; \                        echo "Reversing $$patch"; \                        patch -suRf -p1 < $$patch || exit 1; \                done; \                rm -f patch-stamp; \        fi

That is all very nice, but how do we create new patches for udev using this scheme? The general approach is:

1. copy the clean source tree to a temporary directory

2. apply all patches up to the one you want to edit; if you want to create a new patch, apply all existing ones (this is necessary since in general patches depend on previous patches)
   
   if you want, you can use debian/rules for this: remove the patches that come *after* the one you want to edit, and call 'debian/rules patch'. The actual name for the patch target varies, I have seen the following ones so far: patch setup apply-patches unpack patch-stamp. You have to look in debian/rules to see what it is called.

3. copy the whole source tree again: cp -a /tmp/old /tmp/new

4. go into /tmp/new, do your modifications

5. go back into your original source tree, generate the patch with: diff -Nurp /tmp/old /tmp/new > mypatchname.patch

Example 1.

Let us make a new patch for udev called 90_penguins.patch which replaces Linux with Penguin in the udev README file:

cd udev*/
cp -a . /tmp/old
pushd /tmp/old
debian/rules patch
cp -a . /tmp/new; cd ../new
sed -i 's/Linux/Penguin/g' README
cd ..
diff -Nurp old new > 90_penguins.patch
popd
mv /tmp/90_penguins.patch debian/patches
rm -rf /tmp/old /tmp/new

Example 2.

What happens if we want to edit an existing patch? We can us a similar procedure as Example 1 but we will apply the patch to be edited first:

cp -a . /tmp/old
pushd /tmp/old
cp -a . /tmp/new
cd ../new; patch -p1 <> 10-selinux-include-udev-h.patch
popd
mv /tmp/10-selinux-include-udev-h.patch debian/patches
rm -rf /tmp/old /tmp/new 

So this way of patching the source, while technically fine, can become very complicated and unmanageable. To make patching easier and more straightforward patch systems were developed. We will take a look at couple popular ones.

CDBS with Simple Patchsys

The CDBS build helper system (see the section called “Packaging With CDBS”) has a very simple patch system built in. You simply need to add an include for simple-patchsys.mk in debian/rules. An example is pmount. Its entire rules looks like:

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk
include /usr/share/cdbs/1/rules/simple-patchsys.mk

common-post-build-arch::
     # Generate a POT file
     cd po; intltool-update -p --verbose 

Simple patchsys also has a patch editor built in called cdbs-edit-patch. You can give cdbs-edit-patch either the name of an existing patch to edit or a new patch to create. It will apply the existing patch, if it exists, and put you in a new shell. You can then make any changes you want added to the patch and finally type Ctrl-D to exit the shell and create the new patch. The patches are stored in debian/patches/

cdbs with simple-patchsys (example package: pmount)

cdbs' simple-patchsys.mk module matches its name; it has no bells and whistles whatsoever. However, it is pretty popular since it is sufficient for most tasks, and long ago Martin Pitt wrote a script 'cdbs-edit-patch' which most people can live with pretty well. This script is contained in the normal cdbs package.

You just supply the name of a patch to the script, and depending on whether it already exists or not, it will create a new patch or edit an existing one.

Example with pmount:

  cd /wherever/you/unpacked/the/source/pmount-0.9.11
cdbs-edit-patch 03-simple-readme.patch
echo 'This should document pmount' > README

Editing an already-existing patch works exactly the same way.

Since the Ubuntu Edgy version of cdbs, cdbs-edit-patch also works for packages using tarball.mk, and it can edit patches which produce rejections.

dpatch

A popular patch system is dpatch. It has a dpatch-edit-patch script like cdbs has but stores the patches a little differently. It uses a file named debian/patches/00list to find the name and order of patches to apply. This means you can order your patches in whichever way you want and can disable a patch without removing it altogether. However, it also means you need to update 00list if you add a patch. If dpatch-edit-patch is called with two arguments it will edit/create the patch named by the first argument relative to the patch named by the second argument. In other words:

dpatch-edit-patch new.dpatch old.dpatch

will apply patches up to old.dpatch and then create new.dpatch. Note that dpatch patches usually have a .dpatch suffix. This is because dpatch stores the patches in a slightly different format than a normal patch that adds a special header.

quilt (example package: xterm)

quilt is the other non-dumb standard patch system. Like dpatch, it has a list of patches to apply in debian/patches/series. It is non-trivial to set up and has a lot of advanced commands which make it very flexible, but not very easy to use.

So I will only show a small example here, too. First, set yourself up to use quilt:

  cd /wherever/you/unpacked/the/source/
mkdir debian/patches
export QUILT_PATCHES=debian/patches
touch debian/patches/series

Note that since QUILT_PATCHES is sent, you cannot use "cd" to move around the source tree and expect quilt to still operate sanely. You need to stay in the top level source directory for any quilt operations.

Now let's edit the already existing patch 901_xterm_manpage.diff:

  quilt push 901_xterm_manpage.diff
sed -i 's/Copyright/Copyleft/' xterm.man
quilt refresh 901_xterm_manpage.diff
quilt pop -a

So unlike the other patch systems, quilt works with patched inline sources, but keeps track of modifications.

Finally, let's add a new patch to the top of the stack:

  quilt push -a
quilt new muhaha.diff
quilt add README  # you have to do that for all files you modify
sed -i '1 s/^/MUHAHA/' README
quilt refresh
quilt pop -a

Patching other people's packages

The most important thing to keep in mind when patching packages maintained by other people is to keep the patch system (or lack thereof) that the maintainer has set up. This will ensure consistency and make the package maintainer more likely to accept your patch.

It is also a good idea to separate patches logically rather than creating one giant patch. If the upstream authors apply one of your changes but not another it is much easier to just drop a patch than edit a monolithic patch to update it.

KDE

The basic packaging section in the PackagingGuide will explain the basic, while this page tries to explain KDE specific bits.

If it's not already done, you have to install all the software listed in the Debian New Maintainer's Guide and the Debian Developer's Reference.

Also recommended are

• the kdesdk package which furnish many useful applications and scripts and

• docbook2x, because it can be useful to convert docbook into man pages (remember debian policy implies that every single application has a man page!).
  

Essential Packaging Bits

KDE 3 applications usually use the GNU autoconf/automake build system. There is a CDBS include file designed for KDE.

include /usr/share/cdbs/1/class/kde.mk

You will need to build-dep on kdelibs4-dev and, if the package build kcontrol modules, kdebase-dev.

If you patch any Makefile.am or configure.in.in files you will need to re-run the auto-tools. Do this with:

make -f debian/rules buildprep

This is also necessary if your upstream has not already run this, e.g. if there is no configure file.

KDE 4 applications use a new build system, CMake. The way we build KDE 4 packages is still changing so there is no file included in CDBS yet. You can get a suitable kde.mk by downloading the source for kde4libs and copying debian/cdbs.

include debian/cdbs/kde.mk

You will need to build-depend on kdelibs5-dev and sometimes also libphonon-dev and kdepimlibs5-dev.

If there is already a KDE 3 application with the same name in the archive, rename the package to -kde4.

KDE Manpages

A template of a KDE manpage can be found here http://people.ubuntu.com/~dholbach/packagingguide/kde/sample.1.docbook

This file is a standard file for a basic KDE application. Customize it for your application and check that every important command line option is described in detail. If you don't want to edit the file by hand, install the manedit package and type

manedit [manpage name or file]

Add a build-depend on docbook2x in debian/control.

After that just add this line to the debian/rules file (assuming the name of the binary package is myapp):

build/myapp::
     docbook2x-man debian/myapp.1.docbook

cleanbuilddir/myapp::
     rm -f myapp.1

DEB_INSTALL_MANPAGES_myapp = myapp.1

Of course you have to replace myapp.1.docbook with your manual source file. You also have to add a docbook2x build dependency to the debian/control file. If you have more than one manpage to install (e.g. if your .deb installs a program and its daemon) simply separate their names with a space:

DEB_INSTALL_MANPAGES_myapp = myapp.1 myappdaemon.8

As an alternative you can use the kdemangen.pl script to generate a man page based on the command line help of the program.

Supplementary Files

.desktop Files

In order to ensure that the menus are properly populated, and that software is easily installable with Add/Remove Packages, each package should contain a .desktop file. As a matter of policy, .desktop files should only be present for GUI interfaces: software intended to be used from the command-line should not provide such an interface.

.desktop files may be included in packages in two ways, either as part of the upstream distribution, or as part of the distribution packaging. Including the .desktop file in the upstream distribution is vastly preferred, as this allows for appropriate translation of the .desktop file. If it cannot be included upstream, the .desktop file should be stored in the debian/ directory.

Criteria for the inclusion of .desktop files:

1. The package must provide a binary with a GUI interface
2. The binary must be typically executed with constant arguments
3. Users would expect to launch the program from the menu

Packages typically not needing a .desktop file are: Window Managers, programs that do not have sensible defaults, programs that only act on files (rather than having a standard interface), programs that have no GUI, programs that start up invisible.

Some packaging notes:

• In debian/control, if cdbs is not used, Build-Depend on debhelper (>= 4.2.21).

• In debian/rules, if cdbs's gnome.mk is not used, call dh_desktop in binary*

• ensure that .desktop files are installed or moved to /usr/share/applications/.desktop

• ensure that icon files are installed or moved to /usr/share/pixmaps/

Some ideas about icons:

• Provide an 32x32 pixel XPM icon for use by the Debian menus
• Optionally provide a 48x48 pixel PNG icon for use by freedesktop.org menus (the Debian icon will be used if this is unavailable)
• If neither format is available, many formats can be converted as follows:
  1. Get a base icon (clip of package graphic, .ico file, from scratch, etc.)
  2. Crop / resize to 32x32 pixels

  3. run convert editedicon.ico .xpm (requires imagemagick)

  4. if convert generated multiple images, select one (and name correctly)

About .desktop files generally:

• Check the spec at http://standards.freedesktop.org/desktop-entry-spec/latest/

• Avoid Absolute pathnames in .desktop files

• Do not include a file type extension in Icon=

• Ensure that Categories= includes at least one Registered Category

• Add any other applicable Additional Categories

• Check with desktop-file-validate to ensure everything is correct

The Workflow:

• Find a package without a .desktop file

• Verify there is no .desktop file in the latest development version

• If no .desktop file is needed, add the package to the list below

• If a .desktop is needed:

  1. Check to see if there is a .desktop in the upstream or Debian bug tracker

  2. Create the necessary .desktop / icon if necessary

  3. Open a wishlist bug in the package reporting the missing .desktop file

  4. Attach the .desktop file and icon to the bug (optionally a patch for both)

  5. Link the bug to the Debian BTS (create a BTS bug if required)

  6. Tag the bug with "desktop-file"

Simple Creation techniques:

• In GNOME: use Nautilus' "Create Launcher" to create a template file
• Scripted: Some of this can be automated. Please check the results of the automation prior to submission. Most importantly, please ensure that any useful additional categories are included.

Shell sniplets that might prove useful:

• Using an absolute path for an icon:

  grep -E "^Icon=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate

• Using an absolute path for a binary:

  grep -E "^Exec=\/usr\/" /usr/share/applications/*.desktop | cut -d: -f1 | xargs dlocate

• .desktop file fails validation:

  for i in /usr/share/applications; do desktop-file-validate $i >> /dev/null || echo $i; done | xargs dlocate

A minimal desktop file for a program to appear in the application menu looks like this:

[Desktop Entry]
Type=Application
Name=foo
Name[xx]=foo
GenericName=Bar description
Exec=kfoo
Icon=kfoo
Terminal=false
Categories=Qt;KDE;Utility;

You should ensure that the icon pointed to by Icon= exists in the hicolor namespace and not in the crystalsvg or oxygen themes, this is so it can be found by Gnome and other desktops.

Some notes about KDE .desktop files:

" lang="en">">

KDE also uses .desktop files to describe many resources such as libraries to be loaded or kcontrol modules.

.desktop files for applications should be in /usr/share/applications/kde for KDE 3 or /usr/share/applications/kde4 for KDE 4.

Sometimes packages install the desktop file in the old directory (/usr/share/applnk). You may want to copy the furnished desktop file to the new location (/usr/share/applications/kde). Add these lines to debian/rules:

install/myapp::
 #other stuff
 dh_install desktop_file usr/share/applications/kde

Man Pages

Using POD

POD is a very simple but also elegant format for writing manual pages. It is much easier to learn than writing it directly in groff or using other alternatives like docbook.

Basic template

Below is a sample manpage template in POD format. Customize it for your application and check that every important command line option is described in detail. You can see a real example here.

=head1 NAME

Command - Short one-line description.

=head1 SYNOPSIS

command [options...]

=head1 DESCRIPTION

Command is a foo that does bar.

=head1 OPTIONS

=over 8

=item B<--key=I>

Uses the given value as key.

=item B<--moo>

Shows an easter egg (don't explain this in real man pages ;)).

=item B<--stupid-example>

Doesn't do anything.

=item B<--version>

Displays information about the currently installed version and exists.

=head1 BUGS

This command has absolutely no bugs, as I have written it. Also, as it has no bugs, there is no need for a bug tracker.

=head1 AUTHORS

B was written by Joe Hacker  and John Dough . This manual page was written by Cool Packager .

Both are released under the GNU General Public License, version 3 or later.

=cut

Some formatting options

B<...text...>  -  "...text..." will be shown in bold.
I<...text...>  -  "...text..." will be shown in italics.

Usually, the command name is always written in bold (except in the NAME and SYNOPSIS sections), and variables that the user should replace in italics (as in --key=I).

Necessary packaging changes

• - Add a build dependency on 'perl' in debian/control.

  - After that just add this line to the debian/rules file (assuming the name of the binary package is 'myapp' and that it is using cdbs):

  build/myapp::
       pod2man --section=1 --release=$(VERSION) --center "" debian/myapp.pod > myapp.1
  
  cleanbuilddir/myapp::
       rm -f myapp.1
  
  DEB_INSTALL_MANPAGES_myapp = myapp.1

Of course you have to replace 'myapp.pod' with the name of your manpage source file, and the section number with that one corresponding to what you are documenting (see 'man man' for a list of all sections).

If you have more than one manpage to install (e.g. if your .deb installs a program and its daemon) simply separate their names with a space:

DEB_INSTALL_MANPAGES_myapp = myapp.1 myappdaemon.8

">

Recipes

Recipe: Updating An Ubuntu Package

Introduction

In this recipe we'll update brasero 0.5.2-0ubuntu1 to 0.6.1-0ubuntu1. This should give you a good introduction to updating packages to a new upstream version.

Ingredients

1. The debian packaging tools use some environment variables to put your name and e-mail address in the changelog and to find your GPG key ID. To set these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:

   export DEBFULLNAME='Daniel Holbach'
   export DEBEMAIL='daniel.holbach@ubuntu.com'

   to make these changes take affect, start a new terminal or type source ~/.bashrc in the terminal.

2. pbuilder is a very handy command used to test-build packages. See the PbuilderHowto for a guide to setting it up for the active development release.

3. Install some necessary tools:

   sudo apt-get install devscripts build-essential wget cdbs fakeroot liburi-perl debhelper pbuilder dpatch quilt gnome-pkg-tools

To sign the package once it's finished, you'll need a GPG key. See the GnuPrivacyGuardHowto for a guide.

Method

1. For that, you'd usually just run apt-get source brasero. As this is just an example, you can run:

   dget -xu http://people.ubuntu.com/~dholbach/motu/brasero_0.5.2-0ubuntu1.dsc

2. Get the new source.
   Usually, you'd look up from where the old version was downloaded (check debian/copyright) and use the source from there. But as this is a prepared example...:

   wget http://people.ubuntu.com/~dholbach/motu/brasero-0.6.1.tar.gz

3. Unpack and rename the new source tarball:

   tar xfz brasero-0.6.1.tar.gz
   mv brasero-0.6.1.tar.gz brasero_0.6.1.orig.tar.gz

   (If you use the _.orig.tar.gz scheme, a .diff.gz file will be created automatically during one of the next steps that contains all your changes regarding the Upstream Tarball.)

4. Copy the packaging over into the new source tree:

   cp -r brasero-0.5.2/debian brasero-0.6.1/

5. Add a debian/changelog entry:

   cd brasero-0.6.1
   dch -i

   Here you enter something like "New upstream version" and make sure the version number is 0.6.1-0ubuntu1.

6. Create the source package from it:

   debuild -S -sa

7. Try to build it:

   cd ..
   sudo pbuilder build brasero_0.6.1-0ubuntu1.dsc

8. DONE **Note: This package does not build using pbuilder in Intrepid. It looks like the old brasero package uses an older version of GCC. You should not have this problem when you build other packages.

Get the source of the old brasero package.

For Bonus Points...

1. diff -u brasero-0.{5.2,6.1}/configure.in

   Sometimes this file might be called configure.ac. Most software programmed in C or C++ has this file which generates checks during the configure run of the build.BR If you look closely, you'll notice that most changes are reformatting and only

   -LIBBURN_REQUIRED=0.2.3
   +LIBBURN_REQUIRED=0.3.4

   might be relevant to us. In debian/control you'll see that we don't use libburn, so we're done here.

2. Read the NEWS file before:

   less brasero-0.6.1/NEWS

   This file (if the upstream project uses it) contains valuable information about what the package update is about. As a maintainer you want to know what's been going on.

3. Compare the contents of the old vs. the new package:

   wget http://people.ubuntu.com/~dholbach/motu/brasero_0.5.2-0ubuntu1_i386.deb
   debdiff brasero_0.5.2-0ubuntu1_i386.deb /var/cache/pbuilder/result/brasero_0.6.1-0ubuntu1*.deb

   1. The output will show you that some icons have been replaced with others and some translations were added. Nothing to worry about. All looks good.

   2. To download the old package, you would normally run something like

      aptitude download brasero

4. Get working on upgrade bugs: https://bugs.launchpad.net/ubuntu/+bugs?field.tag=upgrade

Check configure.in for changes you need to reflect in the packaging:

Creating A Debdiff

Introduction

In this recipe we'll fix a simple problem with a package and create a debdiff which you can send to others or attach to bug reports to fix a package.

Ingredients

1. export DEBFULLNAME='Daniel Holbach'
   export DEBEMAIL='daniel.holbach@ubuntu.com'

   to make these changes take effect, start a new terminal or type source ~/.bashrc in the terminal.

2. pbuilder is a very handy command used to test-build packages. See the PbuilderHowto for a guide to setting it up for the active development release.

3. Install some necessary tools:

   sudo apt-get install devscripts build-essential wget fakeroot cdbs patchutils debhelper

4. To sign the package once it's finished, you'll need a GPG key. See the GnuPrivacyGuardHowto for a guide. Note that this is only important if you plan to upload the result to a access-restricted archive directly : most of the time it is not important when creating a debdiff.

The debian packaging tools use some environment variables to put your name and e-mail address in the changelog and to find your GPG key ID. To set these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:

">

Method

" lang="en">">

1. Let's pretend we got a bug report saying that colour in the description of xicc should be color and we want to fix it. (This is just a bad joke and a bad example.) First verify if that's true:

   $ apt-cache show xicc
   Package: xicc
   Priority: optional
   Section: universe/x11
   Installed-Size: 72
   Maintainer: Ross Burton 
   Architecture: amd64
   Version: 0.2-2
   Depends: libc6 (>= 2.3.4-1), libglib2.0-0 (>= 2.8.0), libice6, libsm6, libx11-6
   Filename: pool/universe/x/xicc/xicc_0.2-2_amd64.deb
   Size: 8224
   MD5sum: a266d60cd721ef91fcb1d3d47ecd6a40
   SHA1: b8da21b8dfba7ed9c7ac6fa5c9c3e70b438d7124
   SHA256: 635c287a1c43df31670a20194e774561479d70d981bf24c143c3711799bd839a
   Description: set the ICC colour profile for an X display
   This utility lets you set an ICC colour profile for an X display, so that
   applications can use it to display colour calibrated images.  Applications have
   to specifically look for this atom but several applications such as Gimp and
   Eye Of Gnome already do.
   Bugs: mailto:ubuntu-users@lists.ubuntu.com
   Origin: Ubuntu

2. Time to act on it... get the source of the package:

   dget -xu http://people.ubuntu.com/~dholbach/motu/xicc_0.2-2.dsc

   (We would typically do this with "apt-get source xicc"; dget is used in this example to grab this specific file)

3. Edit debian/control and fix colour:

   cd xicc-0.2
   sed -i 's/colour/color/g' debian/control

   Of course patching is not always that easy and you might have to patch bigger parts of the package. Please refer to our Patch guidelines.

4. Adhere to DebianMaintainerField: Edit debian/control and replace

   Maintainer: Ross Burton 

   with

   Maintainer: Ubuntu MOTU Developers 
   XSBC-Original-Maintainer: Ross Burton 

   You can use the update-maintainer tool (in the ubuntu-dev-tools package) for that.

5. Update debian/changelog:

   dch -i

   and describe the changes you did.

6. Generate a new source package:

   debuild -S

   or if you're creating an unsigned package:

   debuild -S -us -uc

7. Look at the debdiff:

   cd ..
   debdiff xicc_0.2-2.dsc xicc_0.2-2ubuntu1.dsc | less

8. To create a patch file that you can send to others, run

   debdiff xicc_0.2-2.dsc xicc_0.2-2ubuntu1.dsc > xicc_0.2.2ubuntu1.debdiff

9. And we're done. You can now attach the debdiff to a bug report or send it to the relevant person. SponsorshipProcess explains how to get a package uploaded to Ubuntu.

Creating And Using A debian/watch File

Introduction

This should show you why it is important to add a debian/watch file to your package and how easy it is to upload a new upstream version.

Note: the method is exactly the same for an Ubuntu package, just change revision number in changelog version.

Ingredients

1. To sign the package once it is ready, you will need a GPG key. See GnuPrivacyGuardHowto for a guide.

2. Debian packaging tools use some environment variables to put your name and e-mail address in the changelog and to find your GPG key ID. To set these up, edit ~/.bashrc and add your name and mail address (the ones you used for the GPG key), example:

   export DEBFULLNAME='Arthur Loiret'
   export DEBEMAIL='arthur.loiret@gmail.com'

   to make these changes take effect, start a new terminal or type source ~/.bashrc in the terminal.

3. pbuilder is a very handy command used to test-build packages. See the PbuilderHowto for a guide on how to set it up for the current development release.

4. Install some necessary tools:

   sudo apt-get install devscripts build-essential wget fakeroot

Method

In this recipe we will update medit 0.8.5-1 to 0.9.4-0ubuntu1 using uscan and uupdate.

1. Get the source of the current medit (0.8.5) package. Run:

   dget -xu http://people.ubuntu.com/~dholbach/motu/medit_0.8.5-1.dsc

2. Now, instead of getting new upstream sources by hand, we are going to add a debian/watch file, which is going to allow us to check automatically new upstream versions using uscan.
   The very first line of the watch file must be the format version, currently 3, and then other lines can contain urls to parse.
   For example, we are going to try

   version=3
   
   http://sf.net/mooedit/medit-(\d.*)\.tar\.bz2

   As you can see the syntax for [http://sourceforge.net SourceForge] projects is http://sf.net// (Also note that if the project is tar.gz, you must change the bz2 to gz, see the man page of [http://dehs.alioth.debian.org/uscan.html uscan] for more information).

3. Then, we are going to run uscan to ensure the debian/watch works, run in sources directory:

   uscan --verbose
   -- Scanning for watchfiles in .
   -- Found watchfile in ./debian
   -- In debian/watch, processing watchfile line:
   http://sf.net/mooedit/medit-(\d.*)\.tar\.bz2
   -- Found the following matching hrefs:
     medit-0.6.98.tar.bz2
     medit-0.6.99.tar.bz2
     medit-0.7.0.tar.bz2
     medit-0.7.1.tar.bz2
     medit-0.7.9.tar.bz2
     medit-0.7.95.tar.bz2
     medit-0.7.96.tar.bz2
     medit-0.7.97.tar.bz2
     medit-0.8.0.tar.bz2
     medit-0.8.1.tar.bz2
     medit-0.8.10.tar.bz2
     medit-0.8.11.tar.bz2
     medit-0.8.2.tar.bz2
     medit-0.8.3-b20060223.tar.bz2
     medit-0.8.3.tar.bz2
     medit-0.8.4.tar.bz2
     medit-0.8.5.tar.bz2
     medit-0.8.6.tar.bz2
     medit-0.8.7.tar.bz2
     medit-0.8.8.tar.bz2
     medit-0.8.9.tar.bz2
     medit-0.9.0.tar.bz2
     medit-0.9.1.tar.bz2
     medit-0.9.2.tar.bz2
     medit-0.9.3.tar.bz2
     medit-0.9.4.tar.bz2
   Newest version on remote site is 0.9.4, local version is 0.8.5
   => Newer version available from
    http://qa.debian.org/watch/sf.php/mooedit/medit-0.9.4.tar.bz2
   -- Downloading updated package medit-0.9.4.tar.bz2
   -- Successfully downloaded updated package medit-0.9.4.tar.bz2
    and symlinked medit_0.9.4.orig.tar.bz2 to it
   -- Scan finished

   Perfect, we have just got the new upstream version :)

4. Have a look at the new orig tarball name. Just type:

   ls ..
   medit-0.8.5/  medit_0.8.5-1.diff.gz  medit_0.8.5-1.dsc  medit_0.8.5.orig.tar.gz  medit_0.9.4.orig.tar.bz2  medit-0.9.4.tar.bz2

   So, new orig tarball's name is medit_0.9.4.orig.tar.bz2. Don't worry about the archive type, uupdate supports .tar.gz, .tar.bz2, .tar.Z, .tgz, .tar and .zip formats, but if you still have doubts about the new orig tarball format, please read [https://wiki.ubuntu.com/PackagingGuide/Basic#ChangingOrigTarball this]

5. Run uupdate on new orig tarball:

   uupdate ../medit_0.9.4.orig.tar.bz2
   New Release will be 0.9.4-0ubuntu1.
   -- Untarring the new sourcecode archive ../medit_0.9.4.orig.tar.bz2
   8 out of 11 hunks FAILED -- saving rejects to file config.sub.rej
   4 out of 6 hunks FAILED -- saving rejects to file config.guess.rej
   uupdate: the diffs from version 0.8.5-1 did not apply cleanly!
   Rejected diffs are in ./config.sub.rej
   ./config.guess.rej
   Remember: Your current directory is the OLD sourcearchive!
   Do a "cd ../medit-0.9.4" to see the new package
   (Did you see the warnings above?)

   Don't worry about the failure on config.sub, this usually happens very often. Go to the new directory and remove config.sub.rej ;)BRNow the package is almost ready. You have to update changelog and check it builds fine. For that the easiest and the cleanest way is to type dch -e, here is the result you should get:

   medit (0.9.4-0ubuntu1) intrepid; urgency=low
   
   * New upstream release
   * Add debian watch
   
   -- Your Name   Tue, 04 Nov 2008 20:32:22 -0500

   (You dont have to forget to include the debian/watch on previous upload don't worry )

6. Let's test the new upstream release, run debuild -S -sa, and finally:

   sudo pbuilder build ../medit_0.9.4-0ubuntu1.dsc)

Notes

Steps 3 and 5 (of the howto) can be combined by using additional parameters in the URL line of the watch file

version=3

http://sf.net/medit/mooedit-(.*).tar.bz2 debian uupdate

You may want to continue at MOTU/Contributing#head-b205c74e27fe15e79e10c9e7f14d3cdfb359d81d to create an interdiff for sponsorship.

Appendix

Additional Resources

Debian Resources

• Debian New Maintainers Guide - Good resource for learning to package.

• Debian Policy - The essential Policy manual for Debian and Debian-based distros.

• Debian Developer's Reference - Specific information for Debian Developers but has some items of interest for packagers.

• Library Packaging Guide - Guide for packaging libraries.

• Debian Women Packaging Tutorial - Another good introduction to Debian packaging.

• Debian Mentors FAQ

• debian-mentors mailing list - new maintainers can ask questions and find a Debian sponsor here

• Generating multiple binaries from a single source

• Debian New Python Policy

• Debian CLI Policy

• Debian Packaging Handbook

• packaging from upstream SVN repository

• Debian Type of Sections

Wiki Resources

• MOTU/GettingStarted

• PackagingGuide

• UbuntuDevelopment

• PbuilderHowto

• DebootstrapChroot

• UbuntuDevelopment/NewPackages

Other Resources

• IBM Packaging Tutorial

• Duckcorp CDBS Documentation

• Managing packages with Subversion and pbuilder

• Creating .desktop files (Categories)

• Debian Library Packaging Guide

• Make Manual (debian/rules is a Makefile)

example files

• conffiles.ex: If the package installs a configuration file, when the package is upgraded dpkg can prompt a user whether to keep his or her version if modified or install the new version. Such configuration files should be listed in conffiles (one per line). Do not list configuration files that are only modified by the package or have to be set up by the user to work.

• cron.d.ex: If your package requires regularly scheduled tasks to operate properly, you can use this file to configure it. If you use this file, rename it to cron.d.

• dirs specifies the directories that are needed but the normal installation procedure (make installapplication) somehow doesn't create.

• docs specifies the filenames of documentation files that dh_installdocs will install into the temporary directory.

• emacsen-*.ex specifies Emacs files that will be bytecompiled at install time. They are installed into the temporary directory by dh_installemacsen.

• init.d.ex: If your package is a daemon that needs to be run at system startup rename this file to init.d and adjust it to your needs.

• manpage.1.ex and manpage.sgml.ex are templates for man pages if the package does not already have one.

• menu.ex is used to add your package to the Debian menu. Ubuntu uses the freedesktop.org standard .desktop files but remember that packages in Universe/Multiverse are widely used in other (desktop-less) environments. Beside, we strongly want to give-back to Debian (where menu files are required by policy), therefore you are encouraged to include them in your Ubuntu package too.

• watch.ex: The package maintainer can use the uscan program and a watch file to check for a new upstream source tarball. (PackagingGuide/Recipes/DebianWatch)

• ex.package.doc-base is used to register your package's documentation (other than man and info pages) with doc-base.

• postinst.ex, preinst.ex, postrm.ex, and prerm.ex: These maintainer scripts are run by dpkg when the package is installed, upgraded, or removed.

Readme.Debian is used to document changes that you have made to the original upstream source that other people might need to know or information specific to Debian or Ubuntu.

For more details refer to the Debian New Maintainer's Guide.

List of Debhelper Tools

• dh_clean - clean up package build directories

• dh_clideps - calculates CLI (.NET) dependencies

• dh_compress - compress files and fix symlinks in package build directories

• dh_desktop - Register .desktop files

• dh_fixperms - fix permissions of files in package build directories

• dh_gconf - generate GConf schema registration scripts

• dh_gencontrol - generate and install control file

• dh_install - install files into package build directories

• dh_installcatalogs - install and register SGML Catalogs

• dh_installchangelogs - install changelogs into package build directories

• dh_installcligac - register assemblies to be late installed into a GAC

• dh_installcron - install cron scripts into etc/cron.*

• dh_installdeb - install files into the DEBIAN directory

• dh_installdebconf - install files used by debconf in package build directories

• dh_installdefoma - install a defoma related scripts

• dh_installdirs - create subdirectories in package build directories

• dh_installdocs - install documentation into package build directories

• dh_installemacsen - register an emacs add on package

• dh_installexamples - install example files into package build directories

• dh_installinfo - install and register info files

• dh_installinit - install init scripts into package build directories

• dh_installlogcheck - install logcheck rulefiles into etc/logcheck/

• dh_installlogrotate - install logrotate config files

• dh_installman - install man pages into package build directories

• dh_installmanpages - old-style man page installer

• dh_installmenu - install debian menu files into package build directories

• dh_installmime - install mime files into package build directories

• dh_installmodules - register modules with modutils

• dh_installpam - install pam support files

• dh_installppp - install ppp ip-up and ip-down files

• dh_installtex - register Type 1 fonts, languages, or formats with TeX

• dh_installudev - install udev rules files

• dh_installwm - register a window manager

• dh_installxfonts - register X fonts

• dh_installxmlcatalogs - install and register XML catalog files

• dh_link - create symlinks in package build directories

• dh_listpackages - list binary packages debhelper will act on

• dh_make - Debianize a regular source archive

• dh_makeclilibs - automatically create clilibs file

• dh_makeshlibs - automatically create shlibs file

• dh_md5sums - generate DEBIAN/md5sums file

• dh_movefiles - move files out of debian/tmp into subpackages

• dh_perl - calculates perl dependencies

• dh_pycentral - use the python-central framework to handle Python modules and extensions

• dh_pysupport - use the python-support framework to handle Python modules

• dh_python - calculates python dependencies and adds postinst and prerm python scripts

• dh_scrollkeeper - generate ScrollKeeper registration scripts

• dh_shlibdeps - calculate shared library dependencies

• dh_strip - strip executables, shared libraries, and some static libraries

• dh_suidregister - obsolete suid registration program

• dh_testdir - test directory before building debian package

• dh_testroot - ensure that a package is built as root

• dh_testversion - ensure that the correct version of debhelper is installed

• dh_undocumented - obsolete undocumented.7 symlink program

• dh_usrlocal - migrate usr/local directories to maintainer scripts

dh_builddeb - build debian packages