ISVPackagingGuide

Creating a Source Package using debhelper

Though there are different ways to create a package for Ubuntu, this article is meant as an intro guide to get the novice packager up and running as soon as possible. As such, the most common packaging method using debhelper tools will be discussed.

Please note that the term "Source Package" does not imply any actual source code is being shipped with the product. A Source Package simply builds one or more Binary Packages. That is the process that will be explained here.

Before we start, there are some prerequisites that need addressing. First, the environment variables DEBFULLNAME and DEBEMAIL should be set. You can place these in your ~/.bashrc file as such:

DEBFULLNAME='John Smith'
DEBEMAIL='foo@bar.com'

Next, be sure to install the following packages:

debhelper
build-essential
lintian
fakeroot
gnupg
dh-make

'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. That topic is beyond the scope of this article, but two popular tools are pbuilder and sbuild

Let's now jump right in and get our hands dirty. 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.1.1.tar.gz

After downloading the file, you will need to make a copy of the original (sometimes called "upstream") tarball in the following format: <packagename>_<version>.orig.tar.gz.

cp hello-2.1.1.tar.gz hello_2.1.1.orig.tar.gz
tar -xzvf hello_2.1.1.orig.tar.gz

The underscore, "_", between the package name (hello) and the version (2.1.1), as opposed to a hyphen, "-", is very important. Your source package will incorrectly be built as a Debian native package. We now have a hello-2.1.1 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.

cd hello-2.1.1
dh_make

dh_make is a handy utility which creates a templatized debian directory automatically. It creates the required packaging files (rules, control, copyright, etc...) as well as provides example files (postinst.ex, preinst.ex, etc...) for other, optional packaging files.

For hello, you will not need some of the files created by dh_make in the debian directory:

  • 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.

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

changelog

You will need to adjust the changelog slightly in this case to reflect that this package is named hello-debhelper rather than just hello:

hello-debhelper (2.1.1-1) edgy; urgency=low

  * Initial release

  -- Captain Packager <packager@coolness.com>  Thu,  6 Apr 2006 10:07:19 -0700

control

By using debhelper, the only things we need to change in control are the name (substituting hello for hello-debhelper) and adding debhelper (>= 4.0.0) to the Build-Depends field for the source package. The Ubuntu package for hello-debhelper looks like:

Source: hello-debhelper
Section: devel
Priority: extra
Maintainer: Capitan Packager <packager@coolness.com>
Standards-Version: 3.6.1
Build-Depends: debhelper (>= 4)

Package: hello-debhelper
Architecture: any
Depends: ${shlibs:Depends}
Conflicts: hello
Provides: hello
Replaces: hello
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).
 .
 This is the same as the hello package, except it uses debhelper to
 make the deb.  Please see debhelper as to what it is.

rules

In order to be less verbose in this section, please take the time to download an already finished version of this package for reference.

apt-get source hello-debhelper

We can copy the copyright file and the postinst and prerm scripts from the Ubuntu hello-debhelper package just downloaded. More information concerning the copyright can be viewed below, while information regarding the postinst and postrm scripts can be found in the section "Maintainer Scripts". We will also copy the rules file so we can inspect it.

cp ../../ubuntu/hello-debhelper-2.1.1/debian/copyright .
cp ../../ubuntu/hello-debhelper-2.1.1/debian/postinst .
cp ../../ubuntu/hello-debhelper-2.1.1/debian/prerm .
cp ../../ubuntu/hello-debhelper-2.1.1/debian/rules .

The last file we need to look at is rules, where the power of debhelper scripts can be seen.

The rules file looks like this:

 #!/usr/bin/make -f

package = hello-debhelper

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

Notice that tasks like testing if you are in the right directory (dh_testdir), making sure you are building the package with root privileges (dh_testroot), installing documentation (dh_installdocs and dh_installchangelogs), and cleaning up after the build (dh_clean) are handled automatically. Many packages much more complicated than hello have rules files no bigger because the debhelper scripts handle most of the tasks. For a complete list of debhelper scripts, please see the section called “List of debhelper scripts”. They are also well documented in their respective man pages. It is a useful exercise to read the man page (they are well written and not lengthy) for each helper script used in the above rules file.

compat

The compat file is automatically generated by dh_make and basically lists the version of debhelper used when the package was created. It can normally just be left alone.

This file gives the copyright information. It is also helpful if 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. 'source does not necessarily mean "source code", but rather the contents of the orig tarball.'

Building the Source Package

Now that we have gone through the files in the debian directory for hello-debhelper, we can build the source (and binary) packages. First, let us move back into the source directory:

cd ..

Now we build the source package using debuild, a wrapper script for dpkg-buildpackage:

debuild -S

the binary package, using pbuilder:

sudo pbuilder build ../*.dsc

and finally check the source package for common mistakes using lintian:

cd ..
lintian -i *.dsc

Common Mistakes

dh_make Example Files

When you use dh_make to create the initial "debianization", 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.

These points are critical to inform users of the copyrighted materials contained in the packages you have uploaded to the commercial repository.

  • The upstream tarball must contain verbatim copies of all licenses that are used by the files in the tarball.
  • 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.

Common errors:

  • Not shipping a copy of the LGPL when e. g. the build system is under LGPL
  • 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

TODO

  • Wikify all debhelper script manpages with editmoin and augment where needed
  • Create a page describing maintainer scripts


CategoryLookMergeDelete

ISVPackagingGuide (last edited 2008-08-06 17:01:43 by localhost)