DEBIAN PACKAGING

SEMINAR REPORT
PRESENTED BY

BIMAL VARGHESE

Department of Computer Science & Engineering

Govt Engineering College,

Thrissur
 ACKNOWLEDGEMENT

I   would   like   to   thank  Prof.   K.V   Manoj   Kumar,   Head   of   the 

Department, Department of Computer Science and Engineering, Thrissur, for his support in making 

my seminar a success 

I hereby, honor Lt. Sminesh C.N. for his valuable guidance thought the 

seminar

I  also take this opportunity to highlight my indebtedness to all   my 

teachers and friends for their moral and technical support

  .
 ABSTRACT

 Debian  is considerd as one of the best possible free operating 
system. It is a completely free operating system with a social contract and 
free software guidelines. The most important feature of Debian is its 
packaging system. Debian have good package management system which 
helps the user to install and remove software easily. Debian packages can 
be created by any one with the availiable standard Unix tools. 

Debian packages are not more than standard BSD ar archive. So a 
debian package can be created and manipulated using standard BSD 
archiving tools.  Packages  created specifically for debian need not be 
debianised but packages released commonly for all linux distribution can 
be debianise. This paper discribes about the creation of deb packages in 
both sence. Here first we create a debian specific package and then a 
general linux package is converted into a debian package. For converting a 
general linux package to debian package we need to use some tools 
provided by the Debian system. Debian specific package can be even 
created from a non debian system
 CONTENTS

1. INTRODUCTION
2. DEBIAN PACKAGS
3. MANUAL PACKAGING
4. BUILDING PACKAGES
5. A PACKAGE FROM SCRATCH
1. CHANGELOG
2. COPYRIGHT
3. CONTROL
4. RULES
6. BUILDING THE .deb PACKAGE
7. CHECKING PACKAGE
8. CONCLUSION
9. REFERENCES
 INTRODUCTION

Debian GNU/Linux is one of the most prominent and efficient Linux 
distribution. It is considerd as one of the most favourite Linux flavour. The 
most important feature of Debian compared to other Linux flavour is its 
Debian Social contract and Debian free software guidelines. The idea of  a 
social contract cme from 18th century pro­democraccy philosophers like 
John Locke and Jean­Jacques Rousseau. The Debian manifesto states that, 
“Rather than being developed by one isolated individual or group, as other 
distribution of Linux have been developed in the past, Debian is being 
developed openly in the spirit of Linux and GNU. The primary porpose of 
the Debian project is to finally create a distribution that lives up to the 
Linux name. Debian is being carefully and conscientiously put together 
and will be maintained and supported with similar care.”
Debian GNU/Linux is not just an operating system for philosophers. 
It is well regarded for its many excellent features, the most prominent of 
which is its packaging system. A package is a unit of softaware that you 
can add or remove from your computer. A large piece of software may be 
split up into several packages, or several small pieces may be combined 
into one package. A package contains metadata, such as a description, 
version number, contact information for the author, package maintainer, 
etc. It also contains dependency information like what other packages need 
to be installesd for this one to work correcctly and what package will 
conflict with it, preventing it from working correctly. Users of distribution 
such as Fedora, Suse o Mandriva will be familiar with the RPM(RedHat 
Package Management) package format. The Debian package format, often 
reffered as .deb, is some thing similar to rpm. The .deb and .rpm format 
not compatible with each other. A command line tool called dpkg allows 
the user to installa package,remove it,etc.

Package management is among  the most important feature of an 
operating system. The most basic feature of a good package management 
system are easy installation and removal of packages. The system should 
keep track of the files it drops onto the filesystem and be able to remove 
them later without leaving a trace. For instance when a bug is found with a 
programe, the package management system should be able to tell which 
package provide the programe so that the bug can be files appropriately. In 
addition to the files installed as part of the software, the oackage 
management system should allow proper handling of files created by the 
software at runtime. For instance, a database server may drop a bunch of 
cache files next to its data files. Upon removal, it may be desirable to clean 
the system of the temporary files but to preserve the data files. After all, 
we are deinstalling the software, not the data.

Often softwares cannot be dropped onto the file system, but require 
further configuration to work. Similarly, a programmme may need to clean 
up when the user requests its deinstallation. A package management 
system should allow for costam action to be taken at various points during 
the installation and deinstallation process, allowing the maintainer to 
harness the full power and flexibility of regular Unix scripts.

Another crucial factor that separates good from bad package 
management system is the handling of configuration files. No matter how 
the package management system approaches configuration filres, it must 
never overwrite the administtator's changes. At the same time as it 
preserves modifications it should also allow for unmodifed parts of the 
configuration to be merged with the newer version. However, configuration 
file management should not impose any limitations on the syntax of the 
configuration file, or the software configuration options.

Based on the Unix philosopy, a typical programme uses a number of 
libraries and possibly other programes to accomplish its tasks. A good 
package management system should have a full grasp of these 
relationships, including the automatic resolution of dependencies when a 
software is to be installed.

 Debian packages   

Most of the Debian system is based on packages: regular softwares 
comes in package form just like low­level components, such as the kernel, 
and device drivers. The files governing the boot initialisation sequence are 
also managed through the package management system, and the same 
applies to other administrative aspects of the system which are not really 
software in the typical sense of the world. Two types of packages exist in 
the Debian world.

Binary packages
A binary package comes  in the form of a file with the .deb 
extension. These files are commonly called DEB files, and usually contain 
the executables, documentation, configuration files, and copyright 
information, or any subset of these. However, apart from the copyright 
information, binary packages can also be empty and serve as transitional or 
meta packages, whose sole purpose is the satisfaction of dependencies.

Source package
 Even thogh the word “package” has the connotation of a single file 
“packaging” the content, a source package actually consists of two or three 
files. Together, these files provide everything needed for the package 
maintainer scripts to create the binary packages generated by the source 
package. A source package therefore provides the source code of the 
software as wll as the source code needed to generate the binary package.

A source package is used to create one or more binary packages. In 
most cases, only a single binary package is generated. However, in some 
cases, it make sence to modularise the software at the package level. 
Debian users generally deal with binary packages, although source 
packages provide for interesting possibilities even to normal users

 A debian binary package resides in a single DEB file, and vice versa: 
a DEB file can only ever contain a single binary package. While the name 
of this file gives you various information about the package, management 
tools do not actually care about it. Despite this, the file contained in the 
Debian archive are named accordig to the following scheme.

Postfix_2.1.5­1_i386.deb

postfix    2.1.5­1      i386

The package name consist of three fields separated by underscores. 
The policy fobids the use of underscores in package name, version, and 
architecture, thereby assuring the non ambiguity of these fields. The fields 
encode the package name, version number and debian revision and 
architecture, for which the binary package has been compiled, respectively. 
The architecture may be all, which suggests a package containing 
architecture­independent data files, or programmes written in interpreted 
script languages which need not be compiled.

A .deb is an ar(1) archive that contains three files. 

A small text file called 'debian binary' contains a version number so 
that in the event the .deb format changes, the tools will be able to recognise 
which versio they are dealing with. 

A gzipped tarball called data.tar.gz which contains the actual code in 
the package.

A  gzipped tarball called control.tar.gz contains the metadata for the 
package.

The beauty of this format is that in the event dpkg stops working or 
you are not on a debian system, you can still manipulate .debs with ar, tar 
and gzip ­tools that are found in almost every standard linux distributions.

Manual packaging

Debian binary packages are nothinng more than a set ot files which 
can be manipulated with standard Unix archiving tools. In addition to the 
files installed by the package, which are laid inside the package to match 
their installation footprint on the target system, a DEB file contains a small 
number of control files used by the package management tools to manage 
the package. These files are kept in separate tarballs within the DEB file, 
which is nothing more than a simple BSD ar archive.
In the unpacked state, a Debian binary package consist of the 
./DEBIAN directory, which holds the control files, along with the set of 
installed files spread out across the standard Unix filesystem hierarchy. The 
installation of the deb files meerely causes the installed files to be 
unpacked in the / directory, where their locations are determined by their 
relative location within the package.
To demonstrate the all thing we are creating a very simple package 
namastey. The namastey package installs a simple shell script as 
/usr/bin/namastey, which will clear the screen an welcomes the user. This 
package is for illustrating the the low­level components of a Debian binary 
package.
The namastaey script is as follows
$ cat <<EOF >script
#!/bin/sh ­e
clear
echo namastey
echo welcome to the debian system
EOF

Since the script is supposed to reside in /usr/bin, it is installed into 
usr/bin relative to the directory ./namastey, representing the package 
contents. The namastey.1 which is the namastey(1) manpage is created, 
since every file residing in the /usr/bin must have a man page according to 
debian policy.

$ mkdir namastey
$ cd namastey
~/namastey$ mkdir ­p usr/bin usr/share/man/man1
~/namastey$ install ­­mode=755 /home/bimal/script usr/bin/namastey
~/namastey$ install –mode=644 /home/bimal/namastey.1 
usr/share/man/man1
 ~/namastey$ gzip ­f9 usr/share/man/man1/namastey.1

Now the script resides as ./namastey/usr/bin/namastey, and its path 
relative to the ./namastey package identifies its final location when the 
DEB file is installed: /usr/bin/namastey.
The Debian policy requires every package to provide copyright and 
change log information. The copyright file is supposed to contain all 
necessary licencing information, as well as the author, the location where 
to obtain the source, and ideally the maintainer who packaged it and when.

~namastey$ mkdir ­p usr/share/doc/namastey
~namastey$ vim usr/share/doc/namastey/copyright
This package was manually created by Willia Hell on monday 15th 
september 2008

copyright:
do whatever you want with this software 
But do not claim to have invented it.

The change log file should indicate the version, the target 
distribution, and give information about when which changes were made 
by whom.
~namastey$ cat <<EOF | gzip ­9 \
> usr/share/doc/namastey/changelog.Debian.gz
namastey (1.0­1) unstable; urgency=low

* The “Wer hats erfunden?” release

~namastey$ chmod ­R og=rX .

Now the control file is to be created, which specifies dependency 
relation and other meta data of Debian packages. The deb­control(5) 
manpage has the details of this file. The following abbrevated version 
suffices for namastey 

~namastey$ mkdir DEBIAN
~namastey$ cat <<EOF > DEBIAN/control
package: namastey
Section: misc
Priority: extra
Maintainer: William Hell
Architecture : All
Version : 1.0­1
Description : clears the screen and welcomes you to the debian 
system
EOF

The directory is now properly prepared and the package can be 
created with standard Unix tools:

~$ tar cz ­C namastey/DEBIAN ­f control.tar.gz .
~$ tar cz –exclude=DEBIAN ­C namastey ­f data.tar.gz .
~$ echo 2.0 > debian­binary
~$ ar rcu namastey.deb debian­binary control.tar.gz data.tar.gz

Finally get into root to install the package just like any other DEB 
file:
~# dpkg ­­install namastey.deb
[.....]
Unpacking namastey (from namastey.deb) .....
Setting up namastey (1.0­1) ......
#namastey
welcome to debian system
 Here only the standard tools and directory lay outs have been used for 
creating this package. The result is abinary only package without its source 
counterpart. Eventhough it can be installed and used in a debian system.

Building packages

.debs are created at the basic level with a utility called dpkg­
buildpackage. The source code is downloaded from the upstream author 
and unpacked. A copy is made and, if necessary, patched in whatever in 
whatever way is needed for integration into the debian system. A debian 
sub directory is created that contains the metadata and scripts needed to 
build the package. A package creator can also add scripts to the package 
that will be run before or after it is installed or removed. These scripts can 
be used to configure the package or clean up after it. With a utility called 
debconf, packages can even interact with the user at installation time.

A package from scratch

Before we are building a .deb of a particular program, we must have 
the informations like the name of the program, it's upstream authors name, 
licence, copyright, and the URL to download the program. These details 
are required for all packages.
Download the source using any download manager.

$wget <URL to download the package>

After the dowmload is over rename the source to 
<source>_<upstream version>.orig.tar.gz. Always try to work with a tar.gz 
format. If it is not availiable ask the the upstream author to provide a .tar.gz 
format.
 Now extract the source

$ tar xvzf  <source>_<upstream version>.orig.tar.gz

After unpacking, change the working directory to the newly created 
source directory. Install the dh­make package for generating the .deb 
package for the program. dh­make have many options so that by utilising it 
we can create a redt made template for the new package. We must have the 
knowledge about the licence, binary type etc so that we can them as 
options with dh­make, and in return it will provide ready made template 
for use.

For example:
$ dh_make ­e bimzee@gmail.com ­c GPL ­s ­f 
/home/bimal/pipewalker­0.4.3­src.tar.gz 
 

bimal/pipewalker­0.4.3­src.tar.gz 

Maintainer name : Bimal Varghese

Email­Address   : bimzee@gmail.com 

Date            : Tue, 16 Sep 2008 20:53:50 +0530

Package Name    : pipewalker

Version         : 0.4.3

License         : gpl
 Using dpatch    : no

Type of Package : Single

Hit <enter> to confirm: 

Done. Please edit the files in the debian/ subdirectory now. Pipew
alker
 uses a configure script, so you probably don't have to edit the 
Makefiles.

Now dh_make had made some extra directories amd files in the 
source program. This includes some unwanted files also. We should 
remove them before proceeding forward. Now go to the 'debian' directory 
created by the dh_make tool. Their will a number of *.ex files created by 
the dh_make. They are all example files provided by default. Most of them 
are of no use so we can remove them.

Before proceeding some changes have to be made to the files 
generated by the dh_make tool. For that we should examine the files 
generated by the dh_make tool one by one.

Changelog 

This file contains all the changes made by Debian, with time stamps and 
the maintainers/modifier's name. So the current changelog file looks like 
whats shown below

pipewalker (0.4.3­1) unstable; urgency=low
  * Initial release (Closes: #nnnn)  <nnnn is the bug number of your ITP>

 ­­ Bimal Varghese <bimzee@gmail.com>  Tue, 16 Sep 2008 20:53:50 
+0530

It is the only template that was prepared based on the information we 
had provided earlier to the dh_make tool. We need to add the ITP bug ID 
in this file. ITP bug ID is the Intend To Package ID given to the developer 
by the Debian Bug Tracking System(BTS). Any changes added to the 
source package should also be added to this file.
The 'pipewalker (0.4.3­1) unstable; urgency=low
' line shows that the package name is pipewalker. While the upstream 
version number is 0.4.3, Debian has added “­1” after it as a Debian 
revision number. It will incremented by +1 in the next version of this 
package. “Unstable” indicates the default distribution where this package 
will be uploaded, while urgency indicates the importance of the package 
transition time from Debian unstable to Debian testing. 

Copyright 

This file contains the copyright and licence file. The upstream download 
URL is also listed here. The entire licence text, except if it is GPL/LGPL 
should be paste here. The licence for upstream source should be analysed 
very carefully.

Control 

Control  describes each of the source and binary packages of the Debian 
packages. It also contains the package description that shows up in 
Debian's package management system, like when the apt­cache from 
command line or Synaptic from a Desktop environment is used. Initially 
the control file looks like the code below:

Source: pipewalker

Section: unknown

Priority: extra

Maintainer: Bimal Varghese <bimzee@gmail.com>

Build­Depends: debhelper (>= 6), autotools­dev

Standards­Version: 3.7.3

Homepage: <insert the upstream URL, if relevant>

Package: pipewalker

Architecture: any

Depends: ${shlibs:Depends}, ${misc:Depends}

Description: <insert up to 60 chars description>

 <insert long description, indented with spaces>

Some changes have to be made in this file so that finally the file will be 
simililar to this

Source: pipewalker

Section: utils

Priority: optional

Maintainer: Bimal Varghese <bimzee@gmail.com>

Build­Depends: debhelper (>= 6), autotools­dev

Standards­Version: 3.7.3

Homepage: <insert the upstream URL, if relevant>

Package: pipewalker

Architecture: any

Depends: ${shlibs:Depends}, ${misc:Depends}

Description: This is my first attempt to create a deb file. 

 <insert long description, indented with spaces>
Homepage: <http://pipewalker.com>

Rules 

This is a Debian make file. It involes configure and make, using 
some added features from Debian. A basic knowledge about make is 
required to deal with this.
The generated rule file for the program is shown below. Some of the 
major points are explained under it.

#!/usr/bin/make ­f

# ­*­ makefile ­*­

# Sample debian/rules that uses debhelper.

# This file was originally written by Joey Hess and Craig Small.

# As a special exception, when this file is copied by dh­make into a

# dh­make output file, you may use that output file without restriction.

# This special exception was added by Craig Small in version 0.37 of dh­
make.

# Uncomment this to turn on verbose mode.

export DH_VERBOSE=1

# These are used for cross­compiling and for saving the configure script
# from having to guess our platform (since we know it already)

DEB_HOST_GNU_TYPE   ?= $(shell dpkg­architecture 
­qDEB_HOST_GNU_TYPE)

DEB_BUILD_GNU_TYPE  ?= $(shell dpkg­architecture 
­qDEB_BUILD_GNU_TYPE)

ifneq ($(DEB_HOST_GNU_TYPE),$(DEB_BUILD_GNU_TYPE))

CROSS= ­­build $(DEB_BUILD_GNU_TYPE) ­­host 
$(DEB_HOST_GNU_TYPE)

else

CROSS= ­­build $(DEB_BUILD_GNU_TYPE)

endif

config.status: configure

        dh_testdir

        # Add here commands to configure the package.
ifneq "$(wildcard /usr/share/misc/config.sub)" ""

        cp ­f /usr/share/misc/config.sub config.sub

endif

ifneq "$(wildcard /usr/share/misc/config.guess)" ""

        cp ­f /usr/share/misc/config.guess config.guess

endif

        ./configure $(CROSS) ­­prefix=/usr ­­mandir=\$${prefix}/share/man 
­­infodir=\$${prefix}/share/info CFLAGS="$(CFLAGS)" 
LDFLAGS="­Wl,­z,defs"

build: build­stamp

build­stamp:  config.status

        dh_testdir

        # Add here commands to compile the package.

        $(MAKE)

        #docbook­to­man debian/pipewalker.sgml > pipewalker.1
        touch $@

clean:

        dh_testdir

        dh_testroot

        rm ­f build­stamp

        # Add here commands to clean up after the build process.

        [ ! ­f Makefile ] || $(MAKE) distclean

        rm ­f config.sub config.guess

        dh_clean

install: build

        dh_testdir
        dh_testroot

        dh_clean ­k

        dh_installdirs

        # Add here commands to install the package into debian/pipewalker.

        $(MAKE) DESTDIR=$(CURDIR)/debian/pipewalker install

# Build architecture­independent files here.

binary­indep: build install

# We have nothing to do by default.

# Build architecture­dependent files here.

binary­arch: build install

        dh_testdir

        dh_testroot
        dh_installchangelogs ChangeLog

        dh_installdocs

        dh_installexamples

#       dh_install

#       dh_installmenu

#       dh_installdebconf

#       dh_installlogrotate

#       dh_installemacsen

#       dh_installpam

#       dh_installmime

#       dh_python

#       dh_installinit

#       dh_installcron

#       dh_installinfo

        dh_installman

        dh_link
        dh_strip

        dh_compress

        dh_fixperms

#       dh_perl

#       dh_makeshlibs

        dh_installdeb

        dh_shlibdeps

        dh_gencontrol

        dh_md5sums

        dh_builddeb

binary: binary­indep binary­arch

binary: binary­indep binary­arch

.PHONY: build clean binary­indep binary­arch binary install

~                                                             

clean will execute first. So make sure that the package has clean 
“clean “ rules. After that, the configure and build steps will be taken care 
of. Install will install the package in the debian/packagename. Binary­arch 
is to build archetecture specific parts of the package, while binary­indep is 
for archetecture­independent parts of it. It is recomended to keep the 
debian/rules file simple and readable.

There are two more files named compat and docs. Compat shows the 
version of the debhelper program used in the debian/control file. Docs can 
be used to install any extra documentation at the proper location. 
README.Debian file can be used for any debian specific instructions.

Building the .deb package
As mentioned earlier, dpkg­buildpackage is used for creating the .deb 
package. Now change the working directory to the source package 
directory and ececute the following code:

$ dpkg­buildpackage ­rfakeroot ­uc ­us ­sa

we use the fakeroot option to build our package since it is not 
recomented using root to build packages. The ­us ­uc options instruct the 
utility not to sign the source package, and the .changes file and ­sa instruct 
it to include the original source in upload.

Unless the dependencies are not resolved and file created by the 
dh_make are not clear, hopefully the package will just build fine. There 
will be the following files in the end.

pipewalker_0.4.3­1.diff.gz 
pipewalker_0.4.3­1.dsc 
pipewalker_0.4.3­1_i386.changes
pipewalker_0.4.3­1_i386.deb
 pipewalker_0.4.3.orig.tar.gz

The *.changes file contains changelog entries and some basic 
information regarding package. *.deb is the binary package.

We can install this *.deb file using the command as a super user as 
#dpkg ­i pipewalker_0.4.3­1_i386.deb 
(Reading database ... 102265 files and directories currently 
installed.)

Preparing to replace pipewalker 0.4.3­1 (using 
pipewalker_0.4.3­1_i386.deb) ...

Unpacking replacement pipewalker ...

Setting up pipewalker (0.4.3­1) ...

Processing triggers for menu ...

Checking packages
 Now our deb package is ready. But we have to check whether it is 
okey to go into Debian or not, since Debian is all about quality. Their are 
tools availiable to analyse it. The tools like lintian, linda, pbuilder etc are 
tools associated with this.
Now use lintian to analyse the package.
$ lintian ­iIcv *.changes
N: Setting up lab in /tmp/XyTwIrlFps......
N: Processing change files pipewalker_0.4.3­1_i386.changes....
N: ­­­­­
N: Processing source package pipewalker (version 0.4.3­1)....
 N: ­­­­
N: Processing binary package pipewalker (version 0.4.3­1)....
N: Removing /tmp/ XyTwIrlFps.....

No errors and warnings can will help us to proceed further. The same 
procedure is used with linda. Although lintian is much more usefull, 
always check packages with both the tools.

Pbuilder is the personal builder tool. It will ceate a chroot 
environment and test the package for dependencies. To install and 
configure root power is required.
# pbuilder create

This will download the required 'base' packages from unstable and 
create the base.tgz tarball. Now when the package is created normally 
usiing the ways as discussed use pbuilder to test the package in a clean 
chroot environment as follows:
#pbuilder build pipewalker_0.4.3­1.dsc

 The utility will build the package. However, most importantly, it will 
die if your package doesn't have the proper build­dependency set. If the 
build is sucessful, it will tell you where the generated package is stored. 

Now the a standard debian package is created and you can upload it 
into the Debian testing repository. Now it is the developers responsibility 
for any bugs assigned to the package. 
 Conclusion

Debian is one of the most efficient linux system with very high 
standard and quality. The most imprtant feature of Debian system is its 
packaging system. So a knowledge about its basic packaging and 
debianising other packages is of very high importance. As a Debian user 
we all interacts with Debian system we must have a basic knowledge about 
the working of Debian and its packaging. 

In Debian every thing is treated as packages. Even the linux kernel is 
also considered to be a debian package. But there are separate tools for 
handling linux kernels in Debian system. The kernel modules and patches 
are include in the Debian system as special debian packages called udeb 
files. These files are also treated as same as a standard .deb file. So to get a 
deep undersanding of linux and Debian system, a basic knowledge of 
Debian packaging is necessary

REFERENCES
 The Debian System : Concepts and Techniques Martin F Kraft
 Debian New Maintainers Guide
 http://www.debian.org/doc/manuals/maint­guide/index.en.html

 Building Debian Package  article by Karthik Mistry
 Debian GNU/Linux 3.1 Bible by Benjamin Macko Hill