I have separated the process from going from code (e.g. C++ source files) to installed binaries on a Debian user's system into three groups. These people may be the same, but typically they are distinct individuals or groups:

• Upstream author: the person or people who wrote the original source code
• Debian packager: the person or people who create and maintain the Debian package
• Debian user: the person or people who installs the package on their machines to use.

The graph is colored as follows:

• Orange nodes: tasks that only have to be accomplished once.
• Blue nodes: tasks that will occur multiple times
• Dotted edges: interactions between groups.
• Gray edges: occasional tasks.
• Red edges: path upon failure.
• Green edges: path upon success.

This is primarily a post for the Debian package maintainer, but the upstream authors can do several things to make the life of a Debian packager easier:

• Create a working make install target for all code that follows the Filesystem Hierarchy Standard: http://www.pathname.com/fhs/
• Provide stable releases in a timely manner with sensible monotonically increasing release numbers.
• Provide a way for package maintainers to provide bug reports in a streamlined manner.

The master guide is here: http://www.debian.org/doc/manuals/maint-guide/. I will only attempt to distill the key issues as I have discovered them.

The debian folder is added to the root of the source code repository (e.g. hello-2.7/debian) and contains, at a minimum, the following files (see http://www.debian.org/doc/manuals/maint-guide/dreq.en.html):

• changelog - History of the Debian package maintainer's work (different from the upstream changelog)
• control - Details the binary packages to be built and their dependencies.
• copyright - Copyrights of both the original source and the package.
• rules - A makefile for building the package. I strongly suggest using the CDBS (http://cdbs-doc.duckcorp.org/) for the rules file.

Other files that are needed in some cases are given here: http://www.debian.org/doc/manuals/maint-guide/dother.en.html

I would recommend looking around at various debian folders. You can install any source package (including the debian folder) using:

apt-get source <debian-package-name>

Typically the debian folder is not part of the upstream source, but can reside in a VCS repository of its own.

I'm using Ubuntu 12.04. Newer versions of Ubuntu should work fine as well. Older versions of pbuilder and the ubuntu-dev-tools may not have the same functionality, so make sure you're using a fairly new version of all of these. You can usually safely install ubuntu-dev-tools for a newer distribution (e.g. 12.10) into 12.04. Here we will build packages for a Debian Squeeze (6) i386 machine.

1. Install the required packages:

   sudo apt-get install ubuntu-dev-tools mini-dinstall
   

2. Grab the config files and hooks posted here:

   bzr branch lp:~tes/junk/deb ~/deb
   

   I'm assuming you have the deb folder in $HOME (~). If you put it elsewhere, it's up to you to change all the configuration files and scripts appropriately.

   Let's examine the folders included in this package:

   • dot - contains various configuration files ("." files). Use ls -a to see them all.
   • hook.d - pbuilder hooks. These are extra scripts that are invoked during parts of the pbuilder build process. See man pbuilder for more information.
   • pbuilder - contains the generated root filesystems (.tgz) and built packages (.deb).
   • scripts - various miscellaneous scripts
   • src - folder to put your source code to build.

3. Add to your environmental variables (e.g. .bashrc), obviously changing to your name and email:

   export PBUILDFOLDER=$HOME/deb/pbuilder
   export DEBFULLNAME="Toby Schneider"
   export DEBEMAIL="tes.aubergine@gmail.com"
   

4. Create a secret key matching your name/email for signing packages:

   gpg --gen-key
   

   The name and email in the GPG key must be an exact match to DEBFULLNAME and DEBEMAIL.

5. Link configuration files to the relevant versions in the repository:

   cd /etc
   rm pbuilderrc
   ln -s $HOME/deb/dot/pbuilderrc .
   cd ~/
   ln -s $HOME/deb/dot/.mini-dinstall.conf .
   ln -s $HOME/deb/dot/.dput.cf .
   

6. Create a basic local Debian package archive in /var/cache/archive so we can use this later to build packages that depend on our locally built packages

   sudo mini-dinstall -b
   

   Poke around /var/cache/archive to see what was created.

pbuilder-dist squeeze i386 create

You can use any of the Ubuntu (e.g. precise) or Debian (e.g. wheezy, see http://www.debian.org/releases/) codenames instead of squeeze or any of the architectures (e.g. amd64, armel, see http://www.debian.org/ports/) in place of i386 to build additional chroots so you can build packages for those machines. Non-x86 processors (e.g. ARM) are emulated using qemu.

To build a source package that already has the debian configuration, do the following:

1. Grab some source package that exists already in Ubuntu:

   cd ~/deb/src
   apt-get source hello
   

   or download a release from somewhere, rename it to make the Debian tools happy, and install a debian directory (either one you created or one that already existed). For example, this downloads a release of Goby, untars it and adds the debian BZR repository: :

   wget https://launchpad.net/goby/2.0/2.0.1/+download/goby2-2.0.1~rc4.tar.gz
   mv goby2-2.0.1~rc4.tar.gz goby2_2.0.1~rc4.orig.tar.gz
   tar xfz goby2_2.0.1~rc4.orig.tar.gz
   cd goby2-2.0.1\~rc4
   bzr branch -r36 lp:~goby-dev/goby/debian2 debian
   

   For now, though, we will continue using hello.

2. Update the changelog for your build:

   cd hello-*/debian
   dch -i
   

   Add an entry something like this (it's important to understand how Debian version numbers work: see http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version. In generally, it's alphanumeric, but with ~ counting before anything else.):

   hello (2.7-3) squeeze; urgency=low
   
     * Testing build for wiki entry. No upstream changes.
   
    -- Toby Schneider <tes.aubergine@gmail.com>  Wed, 23 Jan 2013 16:20:08 -0500
   

3. Create the source package in ~/deb/src:

   debuild -S
   

4. Build the source in the chroot:

   cd ~/deb/src
   pbuilder-dist squeeze i386 build hello_2.7-3.dsc
   

At this point, the binary package is created in ~/deb/pbuilder/squeeze-i386_result. You can install it with dpkg -i hello_2.7-3_i386.deb, but normally people want to use apt-get to grab the package from a Debian repository, which is what we'll cover in the next section.

In order to build packages that depend on another package, the dependency needs to be built and available, either locally or in the main Debian repository. Our group has a set of projects (outside of the main Debian repository) with this dependency graph:

Thus moos must be built first, then uploaded (locally), before building goby2 or moos-ivp, which must both be built and uploaded before building lamss and so on.

You can grab the source (and Debian packages) for the subset of these projects that is public:

apt-add-repository ppa:goby-dev/ppa
apt-add-repository ppa:tes/goby-daily
apt-add-repository ppa:tes/lamss-daily
apt-get update
apt-get source moos moos-ivp goby2 lamss

1. Build moos as describe above in Build a package.

2. When this completes, add it to the local archive:

   cd ~/deb/pbuilder/squeeze-i386_result
   dput local moos*.changes
   

3. Repeat for goby2 and moos-ivp, then for lamss, then for lamss-shared, then for lamss-dsop.

You will likely want to sign your packages so that users know they are securely getting the code you built. See http://wiki.debian.org/SecureApt for details. This isn't essential for local testing, though, so get the process of building down before worrying about this.

The Debian user typically adds the appropriate *.list files in the /etc/apt/sources.list.d directory which point the machine to various debian repositories to use. See (out of date, but still useful): http://www.debian.org/doc/manuals/apt-howto/ch-basico.en.html#s-sources.list

After updating the files in /etc/apt/sources.list.d, the user can then simply run

apt-get update
apt-get install <new-package-name>

to install the new package.

Alternatively, *.deb files can be installed manually on the command line using

dpkg -i *.deb

or, often more usefully, with automatic package dependency installation using gdebi: http://packages.debian.org/stable/gdebi

1. ssh-copy-id user@server
2. Add to /root/.ssh/config

Host server-apt
HostName server
User user
Port 22
IdentityFile /home/user/.ssh/id_rsa

1. Add to /etc/apt/sources.list

deb ssh://server-apt/path/to/deb/archive squeeze/
deb-src ssh://server-apt/path/to/deb/archive squeeze/