This project is in a very early stage. Any contributions are welcome. Please note that all of the book content will be licensed under the [http://www.opensource.org/licenses/mit-license.php MIT license]. First of all, a index of sections, chapters and paragraphs has to be created. Feel free to add topics you consider somewhat useful. The coordination list is at [mailto:packaging-handbook-project@lists.alioth.debian.org packaging-handbook-project@lists.alioth.debian.org]; [http://lists.alioth.debian.org/mailman/listinfo/packaging-handbook-project join us], Debian hackers! ?TableOfContents INDEX

Introduction

What is a debian package?

A debian package is essentially an archive of software that ends with a .deb designation. This software archive contains source code and other information allowing you to install the software on your debian linux system.

How to choose what to package

There are quite a few things you need to take into consideration when choosing software to package for debian. Some of these considerations include:

What to do before packaging

Sending an ITP

An ITP is an Intent To Package. This is the type of bug you send to the debian bug tracking system (debian BTS). An ITP report requires you to submit a package description along with copyright and URL for the software you wish to package for debian. Copyright information is very important, if it the copyright is too restrictive, the software connected to that copyright might not be able to be packaged for debian.

Using reportbug

You can install the reportbug utility to easily submit ITP bugs to the Work Needed Prospective Packages system (WNPP)

$ aptitude install reportbug

$ reportbug --email username@domain.tld wnpp
Using 'Your Name <username@domain.tld>' as your from address.
Getting status for wnpp...
Querying Debian bug tracking system for reports on wnpp
(Use ? for help at prompts.)

Then reportbug asks you for the different informations needed to generate a proper ITP bug. You should pay attention to the buglist that reportbug presents to you, in order to avoid sending duplicate bugs for the same package.

Via e-mail

It is also possible to submit ITP bugs to the WNPP via email. In this case, it is up to you to consult the WNPP buglist (http://www.debian.org/devel/wnpp/index.en.html) in order to prevent a second report for the same package.

The format of the submission should look like this:

To: submit@bugs.debian.org
Subject: ITP: [package name] -- [short package description]

Package: wnpp
Severity: wishlist
X-Debbugs-CC: debian-devel@lists.debian.org

* Package name    : [desired package name]
  Version         : [version of the software you are packaging]
  Upstream Author : [main author of the upstream software]
* URL             : [where tha package sources can be downloaded from]
* License         : [licence under which the software can be distributed]
  Programming Lang: [main programming language used in the sources]
  Description     : [short package description]

[long package description]

Debian package types

General (non-native)

Most Debian packages are .deb packages which are actually obtained by compiling an existing software release from source. For example, "kpat" is a Debian package obtained using the "KPatience" tarballs released by the KDE project. So, the Debian package maintainer obtains the source from the KPat website, compiles it using a procedure to make a .deb, and then submits (uploads) it into the Debian servers. This is the system in place for most Debian packages, and is what you will probably be making if you are reading this document.

Native

There are, however, some packages in Debian which are mostly useful only for Debian, and are developed in-house by the Debian project and not obtained from an external source. Such packages are called "native" packages since they are native to the Debian system and they have slightly different packaging rules.

Creating packages

The following section describes the method of creating Debian "source" packages, which can then be built for various architectures and then, if you so desire, be submitted to the Debian project for inclusion in their repositories, provided the package adheres to the packaging and license requirements demanded by Debian. This is not the way to develop binary packages. For more on that, see [http://tldp.org/HOWTO/Debian-Binary-Package-Building-HOWTO/]

Pre-requirements

Getting the source

from a tarball

from a revision control system

Packaging tools

dh-make

dh-make-perl

debhelper

CDBS

Benefits

Drawbacks

yada

dpatch

dbs

quilt

devscripts

debnest

Initial "debianization"

Naming

Initial version number

Editing debian/ files

required files

debian/copyright

debian/changelog

debian/control

using debian-xcontrol

debian/rules

other files

debian/compat

debian/docs

debian/dirs

debian/menu

debian/watch

Nelson gave an informal description in ["debian/watch"]. Maybe this could be recycled.

Editing other files

Packaging

Splitting your application into multiple binary packages

Packaging according to the build system

Simple top level Makefile

autotools

Python distutils

... other tips

Building packages

Pre-requirements

Building tools

debuild

debuild will automatically run lintian or linda, but their warning and error messages may scroll off the screen. However, debuild also creates a log file of the entire build in the parent of the source directory (with the file extension .build). You may find it convenient to open the build log in your editor to review the lintian messages.

pbuilder and cowbuilder

debaux-build

sbuild

Checking packages

lintian and linda

piuparts

autopkgtests

edos-debcheck

yaclc

debi

Of course, you should actually install your new package as one part of checking it. "debi" saves some typing by installing the most recent .deb file found in a parent of the current directory. It requires root privileges, so you will actually type "sudo debi" (or, using bash's command history, perhaps just "^Rsu").

Debian Quality Assurance Site

If there is already a version of the package in the collection, you should review its entry at the QA site. You can start at http://packages.qa.debian.org/common/index.html. Check the "Bug Count", "TODO", and "Testing Status" sections.

Uploading packages

Sponsorships

Signing packages

debsigs

Uploading tools

dtools

dput and dcut

debaux-publish

dupload

Maintaining an archive

Updating packages

If you download a new upstream source file, move it to the parent of the current source directory. Make sure it has a name with a Debian compliant version number, say "foo-2.1.tar.gz". cd into the current source directory. You can port the current patches to the new sources with

Now cd into the new source directory and look for any failed patches

Once you have cleared these up, build and check the package as described above.

Update a repository

mini-dinstall

Using version control to manage packaging

VCS-specific stuff

Bazaar

darcs

Git

Mercurial

Monotone

Subversion

SVK

Useful tools

pristine-tar

Appendix: Examples

Appendix: Editors with useful features

vi/vim

GNU Emacs

If you use emacs, be sure to install the "dpkg-dev-el" package. It provides special modes for editing the control and changelog files.

Appendix: Debian Policies

Appendix: Where to get help

Appendix: Useful links

Some (useful) stuff about packaging: