This project is in a very early stage. Any contributions are welcome. 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
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
- 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
Bazaar
Darcs
Git
Mercurial
Subversion
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
Appenndix: Useful links
Some (useful) stuff about packaging: