Chapter 2. First steps

Table of Contents

2.1. Debian package building workflow
2.2. Choose your program
2.3. Get the program, and try it out
2.4. Simple build systems
2.5. Popular portable build systems
2.6. Package name and version
2.7. Setting up dh_make
2.8. Initial non-native Debian package

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

Let's start by creating a package of your own (or, even better, adopting an existing one).

If you are making a Debian package with an upstream program, the typical workflow of Debian package building involves generating several specifically named files for each step as follows:

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.

You have probably chosen the package you want to create. The first thing you need to do is check if the package is in the distribution archive already by using the following:

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:

  • First, you must know that the program works, and have tried it for some time to confirm its usefulness.

  • You must check that no one else is already working on the package on the Work-Needing and Prospective Packages site. If no one else is working on it, file an ITP (Intent To Package) bug report to the wnpp pseudo-package using reportbug. If someone's already on it, contact them if you feel you need to. If not — find another interesting program that nobody is maintaining.

  • The software must have a license.

    • For the main section, Debian Policy requires it to be fully compliant with the Debian Free Software Guidelines (DFSG) and not to require a package outside of main for compilation or execution. This is the desired case.

    • For the contrib section, it must comply with the DFSG but it may require a package outside of main for compilation or execution.

    • For the non-free section, it may be non-compliant with the DFSG but it must be distributable.

    • If you are unsure about where it should go, post the license text on debian-legal@lists.debian.org and ask for advice.

  • The program should not introduce security and maintenance concerns into the Debian system.

    • The program should be well documented and its code needs to be understandable (i.e., not obfuscated).

    • You should contact the program's author(s) to check if they agree with packaging it and are amicable to Debian. It is important to be able to consult with the author(s) in case of any problems with the program, so don't try to package unmaintained software.

    • The program certainly should not run setuid root, or even better, it shouldn't need to be setuid or setgid to anything.

    • The program should not be a daemon, or go in an */sbin directory, or open a port as root.

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.

  • Simple packages

    • single binary package, arch = all (collection of data such as wallpaper graphics)

    • single binary package, arch = all (executables written in an interpreted language such as POSIX shell)

  • Intermediate complexity packages

    • single binary package, arch = any (ELF binary executables compiled from languages such as C and C++)

    • multiple binary packages, arch = any + all (packages for ELF binary executables + documentation)

    • upstream source in a format other than tar.gz or tar.bz2

    • upstream source containing undistributable contents

  • High complexity packages

    • interpreter module package used by other packages

    • generic ELF library package used by other packages

    • multiple binary packages including an ELF library package

    • source package with multiple upstream sources

    • kernel module packages

    • kernel patch packages

    • any package with non-trivial maintainer scripts

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

So the first thing to do is to find and download the original source code. Presumably you already have the source file that you picked up at the author's homepage. Sources for free Unix programs usually come in tar+gzip format with the extension .tar.gz, tar+bzip2 format with the extension .tar.bz2, or tar+xz format with the extension .tar.xz. These usually contain a directory called package-version with all the sources inside.

If the latest version of the source is available through a Version Control System (VCS) such as Git, Subversion, or CVS, you need to get it with git clone, svn co, or cvs co and repack it into tar+gzip format yourself by using the --exclude-vcs option.

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:

  • Strings are compared from the head to the tail.

  • Letters are larger than digits.

  • Numbers are compared as integers.

  • Letters are compared in ASCII code order.

  • There are special rules for period (.), plus (+), and tilde (~) characters, as follows:

    0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0

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

Normal Debian packages are non-native Debian packages made from upstream programs. If you wish to create a non-native Debian package of an upstream source gentoo-0.9.12.tar.gz, you can create an initial non-native Debian package for it by issuing the dh_make command as follows:

$ 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:

  • Package name and version are separated by the character _ (underscore).

  • The string .orig is inserted before the .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).



[4] For the older style of non-native Debian source packages in 1.0 format, package_version-revision.diff.gz is used instead.

[5] See 5.6.1 "Source", 5.6.7 "Package", and 5.6.12 "Version". The package architecture follows the Debian Policy Manual, 5.6.8 "Architecture" and is automatically assigned by the package build process.

[7] Having said that, there will of course always be new programs that are worth packaging.

[8] Do not worry about the missing Makefile. You can install the hello command by simply using debhelper as in Section 5.11, “install, or by modifying the upstream source to add a new Makefile with the install target as in Chapter 3, Modifying the source.

[9] You can identify the archive format using the file command when the file extension is not enough.

[10] This program is already packaged. The current version uses Autotools as its build structure and is substantially different from the following examples, which were based on version 0.9.12.

[11] Many modern programs come with a script named configure, which when executed creates a Makefile customized for your system.

[12] Autotools is too big to deal with in this small tutorial. This section is meant to provide keywords and references only. Please make sure to read the Autotools Tutorial and the local copy of /usr/share/doc/autotools-dev/README.Debian.gz, if you need to use it.

[13] You can automate this by using dh-autoreconf package. See Section 4.4.3, “Customization of rules file”.

[14] The default package name field length of aptitude is 30. For more than 90% of packages, the package name is less than 24 characters.

[15] If you follow the Debian Developer's Reference 5.1. "New packages", the ITP process will usually catch this kind of issue.

[16] This stricter rule should help you avoid confusing file names.

[17] The default version field length of aptitude is 10. The Debian revision with preceding hyphen usually consumes 2. For more than 80% of packages, the upstream version is less than 8 characters and the Debian revision is less than 2 characters. For more than 90% of packages, the upstream version is less than 10 characters and the Debian revision is less than 3 characters.

[18] Version strings may be upstream version (version), Debian revision (revision), or version (version-revision). See Section 8.1, “New Debian revision” for how the Debian revision is incremented.

[19] The following text assumes you are using Bash as your login shell. If you use some other login shell such as Z shell, use their corresponding configuration files instead of ~/.bashrc.

[20] If the upstream source provides the debian directory and its contents, run the dh_make command with the extra option --addmissing. The new source 3.0 (quilt) format is robust enough not to break even for these packages. You may need to update the contents provided by the upstream version for your Debian package.

[21] There are several choices here: s for Single binary package, i for arch-Independent package, m for Multiple binary packages, l for Library package, k for Kernel module package, n for kernel patch package, and b for cdbs package. This document focuses on the use of the dh command (from the package debhelper) to create a single binary package, but also touches on how to use it for arch-independent or multiple binary packages. The package cdbs offers an alternative packaging script infrastructure to the dh command and is outside the scope of this document.