Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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 installtarget 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.
Create debian folder
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.
Create pbuilder chroot(s)
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.
Install the required packages:
sudo apt-get install ubuntu-dev-tools mini-dinstall
Grab the config files and hooks posted here:
bzr branch lp:~tes/junk/deb ~/deb
I'm assuming you have the
~). 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 -ato 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 (
scripts- various miscellaneous scripts
src- folder to put your source code to build.
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="firstname.lastname@example.org"
Create a secret key matching your name/email for signing packages:
The name and email in the GPG key must be an exact match to DEBFULLNAME and DEBEMAIL.
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 .
Create a basic local Debian package archive in
/var/cache/archiveso we can use this later to build packages that depend on our locally built packages
sudo mini-dinstall -b
/var/cache/archiveto see what was created.
Create a chroot
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.
Build a Package
To build a source package that already has the
debian configuration, do the following:
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
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 <email@example.com> Wed, 23 Jan 2013 16:20:08 -0500
Create the source package in
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:
moos must be built first, then uploaded (locally), before building
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
moosas describe above in Build a package.
When this completes, add it to the local archive:
cd ~/deb/pbuilder/squeeze-i386_result dput local moos*.changes
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.
*.deb files can be installed manually on the command line using
dpkg -i *.deb
or, often more usefully, with automatic package dependency installation using
Configure APT over SSH
- Add to
Host server-apt HostName server User user Port 22 IdentityFile /home/user/.ssh/id_rsa
- Add to
deb ssh://server-apt/path/to/deb/archive squeeze/ deb-src ssh://server-apt/path/to/deb/archive squeeze/