Chapter 2. First steps

# Chapter 2. First steps

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).

## 2.1. Debian package building workflow

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:

- Get a copy of the upstream software, usually in a compressed tar format.

  - ``package`-`version`.tar.gz`

- Add Debian-specific packaging modifications to the upstream program under the `debian` directory, and create a non-native source package (that is, the set of input files used for Debian package building) in `3.0 (quilt)` format.

  - ``package`_`version`.orig.tar.gz`
  - ``package`_`version`-`revision`.debian.tar.gz` [4]
  - ``package`_`version`-`revision`.dsc`

- Build Debian binary packages, which are ordinary installable package files in `.deb` format (or `.udeb` format, used by the Debian Installer) from the Debian source package.

  - ``package`_`version`-`revision`_`arch`.deb`

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.

## 2.2. Choose your program

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:

- the aptitude command

- the Debian packages web page

- the Debian Package Tracker web page

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:

- The wnpp-alert command from the `devscripts` package

- Work-Needing and Prospective Packages

- Debian Bug report logs: Bugs in pseudo-package `wnpp` in `unstable`

- Debian Packages that Need Lovin'

- Browse `wnpp` bugs based on debtags

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:

- taking over orphaned, yet actively used, packages

- joining packaging teams

- triaging bugs of very popular packages

- preparing QA or NMU uploads

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:

- Perl policy

- Python policy

- Java policy

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

## 2.3. Get the program, and try it out

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.

## 2.4. Simple build systems

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.

## 2.5. Popular portable build systems

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.

## 2.6. Package name and version

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`.

## 2.7. Setting up dh_make

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

## 2.8. Initial non-native Debian package

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.

[6] See Debian Developer's Reference 5.9.5 "Adopting a package".

[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.

Chapter 1. Getting started The Right Way |  | Chapter 3. Modifying the source