Debian packaging

Filip Pytloun

Filesystem Hierarchy Standard

Basic rules

Sidenote

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.

Directory

Description

/bin

essential command binaries, executables needed in single-user mode

/boot

static files for the boot loader

/dev

device files which refer to physical devices

/etc

host-specific system configuration

/home

users home directories

/lib

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

/media

mount points for removable media

/mnt

mount points for temporarily mounted filesystems

/opt

addon packages that contain static files

/proc

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

/root

home directory of root user

/sbin

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

/srv

site-specific data that are served on the system

/tmp

temporary files

Directory

Description

/usr

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

/usr/bin

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

/usr/include

include files for the C compiler

/usr/lib

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

/usr/local

local programs for specific system, separated root structure

/usr/sbin

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

/usr/share

application data which can be shared among different architectures

Directory

Description

/var

variable data, spool, log files, etc.

/var/cache

data cached for programs

/var/lib

variable state information for programs

/var/lock

lock files

/var/log

log files

/var/mail

user mailboxes

/var/run

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

/var/spool

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

Example program

/usr/share/doc/hello-debian/
/usr/share/doc/hello-debian/changelog.gz

/usr/share/hello-debian/templates/
/usr/share/hello-debian/templates/base.html

/etc/hello-debian/
/etc/hello-debian/hello.ini

/var/log/hello-debian/
/var/log/hello-debian/access.log
/var/log/hello-debian/error.log

/var/lib/hello-debian/
/var/lib/hello-debian/data

/usr/lib/python2.7/dist-packages/hello_debian/
/usr/lib/python2.7/dist-packages/hello_debian/__init__.py
/usr/lib/python2.7/dist-packages/hello_debian-1.0.egg-info/
/usr/lib/python2.7/dist-packages/hello_debian-1.0.egg-info/{PKG-INFO,..}

/usr/bin/hello-debian

Debian packages

Source package

Format

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/rules

Debian makefile

debian/changelog

package changelog, this file defines package version

debian/copyright

copyright information for the package

debian/control

package informations, dependencies, etc.

debian/compat

debhelper compatibility level

debian/watch

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

debian/source/format

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

debian/patches/

modifications of upstream sources

debian/control

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 <filip.pytloun@tcpcloud.eu>
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

debian/changelog

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 <noel@debian.org>  Mon, 27 Oct 2014 11:29:29 +0100

Using dch

Setup environment

dch takes following environment variables to generate changelog entries

export DEBEMAIL="filip.pytloun@tcpcloud.eu"
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

debian/rules

#!/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
debuild
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

wget http://pypi.debian.net/jenkins-job-builder/jenkins-job-builder-1.1.0.tar.gz
Generate source package automatically with py2dsc
py2dsc -d . -m 'Filip Pytloun <filip.pytloun@tcpcloud.eu>' 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

Reference

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