Differences between revisions 61 and 62
Revision 61 as of 2007-10-16 20:50:36
Size: 11398
Editor: LucaBrivio
Comment: ccache added
Revision 62 as of 2007-10-16 21:01:36
Size: 11561
Editor: LucaBrivio
Comment:
Deletions are marked like this. Additions are marked like this.
Line 190: Line 190:
 * http://doc.ubuntu.com/ubuntu/packagingguide/C/index.html (note: it will probably be moved to the wiki)
Line 191: Line 192:
 * http://wiki.debian.org/SoftwarePackaging  * http://wiki.debian.org/SoftwarePackaginghttp://doc.ubuntu.com/ubuntu/packagingguide/C/index.html

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:

  • Is the software released under a [http://www.debian.org/social_contract#guidelines debian Free Software Guidelines (DFSG)] compatible license? Note that if this isn't the case, you can't get the package into the main section of the archive.

  • Do you use the package? Are you familiar enough with it to handle bug reports? It is essential that you at least use the package so that you can interpret and help out with bug reports which may arise from users. Also, though knowledge of the source code is not absolutely necessary, it is very useful enabling you to send patches upstream. This is most useful when upstream is not active or available immediately for bug fixes.
  • Are you sure the package you are considering does something very different from packages already in Debian which provide similar functionality?
  • Are you sure there'll be a sufficient audience for the package in Debian?
  • Are you willing to take the required responsibility to maintain the package and keep it updated and fixed on a regular basis?

What to do before packaging

  • Ensure that the package is not in Debian already. An apt-cache search <pkgname>, followed by a search on Google to find out whether the package already has been packaged as a ""deb"" should be sufficient. Don't duplicate work already done, you'll feel badly knowing that you've spent a week on packaging something someone has already been packaged months ago!

  • File an "Intent to Package" (ITP) bug to the Debian project, and CC the bug report to the debian-developers mailing list (reportbug does this automatically). The people on debian-devel might have some comments to make on your proposed ITP. If there isn't any opposition for a period of time, (say a week), you can assume that nobody opposes your intention of packaging the software.

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

  • ?PkgSplit

Packaging according to the build system

Simple top level Makefile

autotools

How to package upstream source which uses automake and autoconf and contains generated files

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

Other tools useful when building

ccache

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

  • uupdate ../foo-2.1.tar.gz

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

  • find . -name \*.rej

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: