Chapter 2. First steps

Please note that the character separating package and version was changed from - (hyphen) in the tarball name to _ (underscore) in the Debian package filenames.

In the file names above, replace the package part with the package name, the version part with the upstream version, the revision part with the Debian revision, and the arch part with the package architecture, as defined in the Debian Policy Manual. ^[5]

Each step of this outline is explained with detailed examples in later sections.

If the package already exists, well, install it! :-) If it happens to be orphaned (that is, if its maintainer is set to Debian QA Group), you may be able to pick it up if it's still available. You may also adopt a package whose maintainer has filed a Request for Adoption (RFA).^[6]

There are several package ownership status resources:

As a side note, it's important to point out that Debian already has packages for most kinds of programs, and the number of packages already in the Debian archive is much larger than that of contributors with upload rights. Thus, contributions to packages already in the archive are far more appreciated (and more likely to receive sponsorship) by other developers ^[7]. You can contribute in various ways:

If you are able to adopt the package, get the sources (with something like apt-get source packagename) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable to your case.

If the package is new, and you decide you'd like to see it in Debian, proceed as follows:

Of course, the last one is just a safety measure, and is intended to save you from enraging users if you do something wrong in some setuid daemon… When you gain more experience in packaging, you'll be able to package such software.

As a new maintainer, you are encouraged to get some experience in packaging with easier packages and discouraged from creating complicated packages.

Packaging high complexity packages is not too hard, but it requires a bit more knowledge. You should seek specific guidance for every complex feature. For example, some languages have their own sub-policy documents:

There is another old Latin saying: fabricando fit faber (practice makes perfect). It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages while reading this tutorial. A trivial upstream tarball, hello-sh-1.0.tar.gz, created as follows may offer a good starting point:^[8]

$ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
$ cat > hello <<EOF
#!/bin/sh
# (C) 2011 Foo Bar, GPL2+
echo "Hello!"
EOF
$ chmod 755 hello
$ cd ..
$ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0

If your program's source comes as some other sort of archive (for instance, the filename ends in .Z or .zip^[9]), you should also unpack it with the appropriate tools and repack it.

If your program's source comes with some contents which do not comply with DFSG, you should also unpack it to remove such contents and repack it with a modified upstream version containing dfsg.

As an example, I'll use a program called gentoo, a GTK+ file manager. ^[10]

Create a subdirectory under your home directory named debian or deb or anything you find appropriate (e.g. just ~/gentoo would do fine in this case). Place the downloaded archive in it, and extract it (with tar xzf gentoo-0.9.12.tar.gz). Make sure there are no warning messages, even irrelevant ones, because other people's unpacking tools may or may not ignore these anomalies, so they may have problems unpacking them. Your shell command line may look something like this:

$ mkdir ~/gentoo ; cd ~/gentoo
$ wget http://www.example.org/gentoo-0.9.12.tar.gz
$ tar xvzf gentoo-0.9.12.tar.gz
$ ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz

Now you have another subdirectory, called gentoo-0.9.12. Change to that directory and thoroughly read the provided documentation. Usually there are files named README*, INSTALL*, *.lsm or *.html. You must find instructions on how to compile and install the program (most probably they'll assume you want to install to the /usr/local/bin directory; you won't be doing that, but more on that later in Section 3.3, “Installation of files to their destination”).

You should start packaging with a completely clean (pristine) source directory, or simply with freshly unpacked sources.

Simple programs usually come with a Makefile and can be compiled just by invoking make.^[11] Some of them support make check, which runs included self-tests. Installation to the destination directories is usually done with make install.

Now try to compile and run your program, to make sure it works properly and doesn't break something else while it's installing or running.

Also, you can usually run make clean (or better make distclean) to clean up the build directory. Sometimes there's even a make uninstall which can be used to remove all the installed files.

A lot of free software programs are written in the C and C++ languages. Many of these use Autotools or CMake to make them portable across different platforms. These build tools need to be used to generate the Makefile and other required source files first. Then, such programs are built using the usual make; make install.

Autotools is the GNU build system comprising Autoconf, Automake, Libtool, and gettext. You can recognize such sources by the configure.ac, Makefile.am, and Makefile.in files. ^[12]

The first step of the Autotools workflow is usually that upstream runs autoreconf -i -f in the source directory and distributes the generated files along with the source.

configure.ac-----+-> autoreconf -+-> configure
Makefile.am -----+        |      +-> Makefile.in
src/Makefile.am -+        |      +-> src/Makefile.in
                          |      +-> config.h.in
                      automake
                      aclocal
                      aclocal.m4
                      autoheader

Editing configure.ac and Makefile.am files requires some knowledge of autoconf and automake. See info autoconf and info automake.

The second step of the Autotools workflow is usually that the user obtains this distributed source and runs ./configure && make in the source directory to compile the program into an executable command binary.

Makefile.in -----+                +-> Makefile -----+-> make -> binary
src/Makefile.in -+-> ./configure -+-> src/Makefile -+
config.h.in -----+                +-> config.h -----+
                 |
  config.status -+
  config.guess --+

You can change many things in the Makefile; for instance you can change the default location for file installation using the option ./configure --prefix=/usr.

Although it is not required, updating the configure and other files with autoreconf -i -f may improve the compatibility of the source. ^[13]

CMake is an alternative build system. You can recognize such sources by the CMakeLists.txt file.

If the upstream source comes as gentoo-0.9.12.tar.gz, you can take gentoo as the (source) package name and 0.9.12 as the upstream version. These are used in the debian/changelog file described later in Section 4.3, “changelog”, too.

Although this simple approach works most of the time, you may need to adjust package name and upstream version by renaming the upstream source to follow Debian Policy and existing convention.

You must choose the package name to consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing packages. It is a good idea to keep its length within 30 characters. ^[14]

If upstream uses some generic term such as test-suite for its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution. ^[15]

You should choose the upstream version to consist only of alphanumerics (0-9A-Za-z), plus signs (+), tildes (~), and periods (.). It must start with a digit (0-9). ^[16] It is good idea to keep its length within 8 characters if possible. ^[17]

If upstream does not use a normal versioning scheme such as 2.30.32 but uses some kind of date such as 11Apr29, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the debian/changelog file. If you need to invent a version string, use the YYYYMMDD format such as 20110429 as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as 0.1 in the future, use the 0~YYMMDD format such as 0~110429 as the upstream version.

Version strings ^[18] can be compared using dpkg(1) as follows:

$ dpkg --compare-versions ver1 op ver2

The version comparison rule can be summarized as:

One tricky case occurs when upstream releases gentoo-0.9.12-ReleaseCandidate-99.tar.gz as the pre-release of gentoo-0.9.12.tar.gz. You need to make sure that the upgrade works properly by renaming the upstream source to gentoo-0.9.12~rc99.tar.gz.

Set up the shell environment variables $DEBEMAIL and $DEBFULLNAME so that various Debian maintenance tools recognize your email address and name to use for packages. ^[19]

$ cat >>~/.bashrc <<EOF
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc

$ cd ~/gentoo
$ wget http://example.org/gentoo-0.9.12.tar.gz
$ tar -xvzf gentoo-0.9.12.tar.gz
$ cd gentoo-0.9.12
$ dh_make -f ../gentoo-0.9.12.tar.gz

Of course, replace the filename with the name of your original source archive. ^[20] See dh_make(8) for details.

You should see some output asking you what sort of package you want to create. Gentoo is a single binary package — it creates only one binary package, i.e., one .deb file — so we will select the first option (with the s key), check the information on the screen, and confirm by pressing ENTER. ^[21]

This execution of dh_make creates a copy of the upstream tarball as gentoo_0.9.12.orig.tar.gz in the parent directory to accommodate the creation of the non-native Debian source package with the name debian.tar.gz later:

$ cd ~/gentoo ; ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz
gentoo_0.9.12.orig.tar.gz

Please note two key features of this filename gentoo_0.9.12.orig.tar.gz:

You should also notice that many template files are created in the source under the debian directory. These will be explained in Chapter 4, Required files under the debian directory and Chapter 5, Other files under the debian directory. You should also understand that packaging cannot be a fully automated process. You will need to modify the upstream source for Debian (see Chapter 3, Modifying the source). After this, you need to use the proper methods for building Debian packages (Chapter 6, Building the package), testing them (Chapter 7, Checking the package for errors), and uploading them (Chapter 9, Uploading the package). All the steps will be explained.

If you accidentally erased some template files while working on them, you can recover them by running dh_make with the --addmissing option again in a Debian package source tree.

Updating an existing package may get complicated since it may be using older techniques. While learning the basics, please stick to creating a fresh package; further explanations are given in Chapter 8, Updating the package.

Please note that the source file does not need to contain any build system discussed in Section 2.4, “Simple build systems” and Section 2.5, “Popular portable build systems”. It could be just a collection of graphical data, etc. Installation of files may be carried out using only debhelper configuration files such as debian/install (see Section 5.11, “install”).