Whole document tree

Debian New Maintainers' Guide
Chapter 1 Getting started "The Right Way"

This document will try to describe building of a Debian GNU/Linux package to the common Debian user (and wannabe developer) in common language, and well covered with working examples. There is an old Roman saying, Longum iter est per preaecepta, breve et efficax per exempla! (It's a long way by the rules, but short and efficient with examples!).

One of the things that makes Debian such a top-notch Linux distribution is its package system. While there is a vast quantity of software already in the Debian format, sometimes you need to install software that isn't. You may be wondering how you can make your own packages and perhaps you think it is a very difficult task. Well, if you are a real novice on Linux, it is hard, but if you were rookie, you wouldn't be reading this doc now. :-) You do need to know a little about Unix programming but you certainly don't need to be a wizard.

Newer versions of this document should always be available online at http://www.debian.org/doc/maint-guide and in the `maint-guide' package.

1.1 Programs you need for development

Before you start anything, you should make sure that you have properly installed some additional packages needed for development. Note that the list doesn't contain any packages marked `essential' or `required' - we expect that you have those installed already.

This document has been written while the 2.1 `slink' distribution was the officially stable release of Debian, and the 2.2 `potato' was being created, thus the packages named here are mostly those from `potato'.

The following packages come with standard installation of Debian 2.1, so you probably have them (and additional packages they depend on) already. Still, you should check with `dpkg -s <package>`.

• binutils - these programs used to assemble and link object files - the stuff programs are made of. (see `info binutils`)
• cpp - the C preprocessor. (see cpp(1))
• cpio - this is an archiver like tar or zip. (see cpio(1))
• dpkg-dev - this package contains the tools needed to unpack, build and upload Debian source packages. (see dpkg-source(1))
• file - this handy program can determine what type a file is. (see file(1))
• gcc - the GNU C compiler. Most Linux programs are written in C. However, if your program is written in some other programming language, like C++, Fortran, Pascal, you should get g++, g77, or gpc, respectively. (see gcc(1), g++(1), g77(1), gpc(1))
• libc6-dev - the C libraries and header files gcc needs to link with to create object files. Although some programs still recommend and/or use libc5, you are encouraged to use the newer version (libc6). (see `info libc`)
• make - usually creation of a program takes several steps. Rather than having to type out the same commands over and over again, you can use this program to automate the process, creating `Makefile's. Some programs also use imake and xmkmf, programs used to generate Makefiles from sets of macro functions. Many newer programs use configure scripts and Makefiles with help of programs like autoconf and automake, so you might need these, too. (see `info make`, imake(1), xmkmf(1), autoconf(1), automake(1))
• patch - this very useful utility will take file containing a difference listing (produced by the diff program) and apply it to the original file, producing a patched version. (see patch(1))
• perl5 - Perl is one of the most used interpreted scripting languages on today's un*x systems, often referred to as "Unix's Swiss Army Chainsaw". (see perl(1))

From the `devel' section of the distribution you'll probably need to install these yourself:

• dh-make and debhelper - dh-make is necessary to create the skeleton of our example package, and it will use some the debhelper tools for creating packages. They are not essential for creation of packages, but it is highly recommended for new maintainers. It makes the whole process very much easier to start, and control afterwards. (see dh_make(1), debhelper(1), /usr/share/doc/debhelper/README)
• devscripts - this package contain some nice and useful scripts that can be helpful to the maintainers, but they are also not necessary for building packages. (see /usr/share/doc/devscripts/README.gz)
• fakeroot - this utility lets you emulate being root which is necessary for some parts of the build process. (see fakeroot(1))
• lintian - this is the Debian package checker that can let you know of any common mistakes after you build the package, and explain the errors found. (see lintian(1), /usr/share/doc/lintian/lintian.html/index.html)

Finally, these very important packages are in the doc section of the distribution:

• debian-policy - includes the structure and contents of the archive, several OS design issues, the Filesystem Hierarchy Standard, and the most important thing (for you) is that it describes requirements that each package must satisfy to be included in the distribution. (see /usr/share/doc/debian-policy/policy.html/index.html)
• developers-reference - for all matters not specifically about the technical details of packaging, like the structure of the archive, how to rename, orphan, pick up packages, how to do NMUs, how to manage bugs, when and where to upload etc. (see /usr/share/doc/developers-reference/developers-reference.html/index.html)

You will also need the encryption package, either PGP (the pgp-* packages) or GPG (the gnupg package), to digitally sign your package. This is especially important if you want to distribute it to other people (and you will certainly be doing that when your work gets included in the Debian distribution). However, due to a rather wacky U.S. export law, you cannot simply download this from your nearest Debian FTP site. But Debian does provide these packages through a site that is not physically located in the US, called non-US.debian.org (ftp://non-us.debian.org/debian-non-US/). Your FTP site will have a file called README.non-US, which will tell you how to find a closer mirror of that site.

The short descriptions that are given above only serve to introduce you to what each package does. Before continuing please thoroughly read how to the documentation of each program, at least the standard usage. It may seem like heavy going now, but later on you'll be very glad you read it. Note: debmake is a package that contains some programs that function similar to dh-make, but its specific use is not covered in this document. Refer to the Debmake manual for more information.

1.2 Other information

There are two types of packages you can make, source and binary. A source package contains code which you can compile into a program. A binary package contains just the finished program. Don't mix terms like source of the program and the source package of the program! Please read the other manuals if you need more details on terminology.

In Debian, the term `maintainer' is used for the person who makes packages, `upstream author' for the person that made the program, and `upstream maintainer' for the person who currently maintains that program, outside of Debian. Usually author and the upstream maintainer are the same person - and sometimes even the maintainer is the same person. If you made a program, and want it to get in Debian, feel free to submit your application to become a maintainer.

After you build your package (or while doing that), you will have to become an official Debian maintainer if you wish your program to get into the next distribution (if the program is useful, why not?). That process is explained in Developer's Reference. Please read it.