Debian packaging

Filip Pytloun

Filesystem Hierarchy Standard

Basic rules


Use term directory instead of folder when you are talking about Unix-like system.

Also there's no command line in Unix-like systems, but shell, console or terminal.




essential command binaries, executables needed in single-user mode


static files for the boot loader


device files which refer to physical devices


host-specific system configuration


users home directories


essential shared libraries and kernel modules, necessary to boot the system


mount points for removable media


mount points for temporarily mounted filesystems


addon packages that contain static files


mount point for proc filesystem which provides informations about running processes and kernel


home directory of root user


similar to /bin but used for executables mostly not used by regular users. Eg. executables that requires root privileges.


site-specific data that are served on the system


temporary files




used to store sharable, read-only data, can be shared by multiple systems, strictly static content


primary directory for executable programs, executable by regular users and not needed for booting or repairing the system


include files for the C compiler


object libraries, including dynamic libraries and some executables which are usually not invoked directly


local programs for specific system, separated root structure


program binaries for system administrators which are not required to boot or repair the system


application data which can be shared among different architectures




variable data, spool, log files, etc.


data cached for programs


variable state information for programs


lock files


log files


user mailboxes


run-time variables files, files holding PIDs, usually cleared when system boots


spooled or queued files for various programs, eg. cron, mail queue, etc.

Example program








Debian packages

Source package


Get and explore source package

Now you have <package>-<version> directory with upstream source and debian directory which is important for us. All the packaging work is done in this directory. You don't need to touch anything else.

Files in debian/


Debian makefile


package changelog, this file defines package version


copyright information for the package


package informations, dependencies, etc.


debhelper compatibility level


file with definition for uscan, used to monitor new upstream versions. See debian/watch for more informations.


format of source packages 3.0 (native) for native packages or 3.0 (quilt) that will apply patches in debian/patches directory. Quilt format build is different from native, and using git-buildpackage. See gbp manual for more details.

debian/install, debian/dirs

list of files and directories, installed by the package

debian/postinst, debian/prerm, ..

installation and removal scripts


modifications of upstream sources


This is probably most important file in debian package. It defines packages that should be build, it's dependencies, architectures, etc.

An example may look like this:

Source: hbsd
Section: net
Priority: extra
Build-Depends: debhelper (>= 7)
Maintainer: Filip Pytloun <>
Standards-Version: 3.9.6

Package: hbsd
Architecture: all
Depends: ${shlibs:Depends}, ${python:Depends}, cinder-volume
Enhances: cinder-volume
Description: Hitachi Block Storage Driver for OpenStack


wget (1.16-1) unstable; urgency=medium

  * new upstream release from 2014-10-27
    - "Poodle" do not use SSLv3 except explicitely requested (CVE-2014-3566)
  * debian/control: Public Suffix List cookie domain checking via libpsl
    Closes: #766780
  * debian/control: updated Standards-Version to 3.9.6 (no changes needed)

 -- Noël Köthe <>  Mon, 27 Oct 2014 11:29:29 +0100

Using dch

Setup environment

dch takes following environment variables to generate changelog entries

export DEBEMAIL=""
export DEBFULLNAME="Filip Pytloun"
Create release for distribution trusty
dch --distribution trusty -l tcp
Simply increment version, based on last changelog entry
dch --distribution trusty -R
New version entry
dch --distribution trusty -v 1.66-0tcp1


#!/usr/bin/make -f

    dh $@

override_dh_auto_configure :
    dh_auto_configure -- -- with - kitchen - sink

override_dh_auto_build :
    make world

Building package

Install build dependencies for given package
apt-get build-dep <package>

# Or if package is not in Debian yet (install devscripts)
mk-build-deps -ir
Build, test with lintian, sign with GPG
Build, no test, no signing
dpkg-buildpackage -uc -us

This will generate *.deb and *.changes files.

It's better to build packages in clean chrooted environment using eg. Pbuilder.

Using git-buildpackage

Building Python module from Pypi

Install requirements
apt-get install build-essential python-stdeb dh-python python-pbr git-buildpackage
Download source from pip
pypi-download jenkins-job-builder --release 1.1.0

pypi-download is not present in trusty so you may need to download it manually from pypi

Generate source package automatically with py2dsc
py2dsc -d . -m 'Filip Pytloun <>' jenkins-job-builder-*.tar.gz

python-stdeb is broken in trusty, install newer from vivid

Initialize git repository and import source package
git init jenkins-job-builder; cd jenkins-job-builder
gbp import-dsc ../jenkins-job-builder_*.dsc

Now you can make a little cleanup and customizations.

Don't forget to tag our build
git tag debian/1.1.0-0tcp1 -f
Finally build the package
gbp buildpackage -uc -us
Now it's in parrent directory, show package info and contents
dpkg --info ../*jenkins-job-builder-*.deb
dpkg -c ../*jenkins-job-builder-*.deb
Cleanup your repository, discarding all uncommited changes
git checkout -f
git clean -xfd

Updating build

If you execute uscan --no-download --verbose, you will find out that there is newer upstream version of our packaged software.

Uscan can download it for you, but we will do it manually.

Download latest upstream version (but keep repository clean)
pypi-download jenkins-job-builder
mv *.tar.gz ../
Import upstream source
gbp import-orig ../jenkins-job-builder-1.2.0.tar.gz
Update changelog and commit changes
dch --distribution trusty -v 1.2.0-0tcp1
git add -u
git commit -m "New upstream release"
Tag new build and build package
git tag debian/1.2.0-0tcp1
gbp buildpackage -uc -us

Patching original sources

Create patch queue of possible existing patches

This will create sort-of feature branch called patch-queue/master.

gbp pq import
Make some changes on original code and commit it
echo "wxmpl" >> requirements.txt
git add -u
git commit -m "Add missing requirement"
When your patching is done, export it
gbp pq export

Have a look at new directory debian/patches Now debuild will automatically apply patches to original source. You don't need to push patch-queue/master branch as anyone can create it again using gbp pq import.

Commit your patches, raise version and build package
dch --distribution trusty -l tcp
git add -u
git commit -m "Fix requirements"
git tag debian/1.2.0-0tcp2
gbp buildpackage -uc -us


Right, Down, Page DownNext slide
Left, Up, Page UpPrevious slide
POpen presenter console
HToggle this help