Debian Packaging Tutorial

Lucas Nussbaum
[email protected]

version 0.21 2017-08-15

Debian Packaging Tutorial 1 / 85

About this tutorial

I Goal: tell you what you really need to know about Debian packaging
I Modify existing packages
I Create your own packages
I Interact with the Debian community
I Become a Debian power-user

I Covers the most important points, but is not complete

I You will need to read more documentation

I Most of the content also applies to Debian derivative distributions

I That includes Ubuntu

Debian Packaging Tutorial 2 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 3 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 4 / 85

Debian

I GNU/Linux distribution

I 1st major distro developed openly in the spirit of GNU

I Non-commercial, built collaboratively by over 1,000 volunteers

I 3 main features:
I Quality culture of technical excellence

We release when its ready

I Freedom devs and users bound by the Social Contract
Promoting the culture of Free Software since 1993
I Independence no (single) company babysitting Debian
And open decision-making process (do-ocracy + democracy )

I Amateur in the best sense: done for the love of it

Debian Packaging Tutorial 5 / 85

Debian packages

I .deb files (binary packages)

I A very powerful and convenient way to distribute software to users

I One of the two most common package formats (with RPM)

I Universal:
I 30,000 binary packages in Debian

most of the available free software is packaged in Debian!

I For 12 ports (architectures), including 2 non-Linux (Hurd; KFreeBSD)
I Also used by 120 Debian derivative distributions

Debian Packaging Tutorial 6 / 85

The Deb package format
I .deb file: an ar archive
$ ar tv wget_1 .12 -2.1 _i386 . deb
rw -r - -r - - 0/0 4 Sep 5 15:43 2010 debian - binary
rw -r - -r - - 0/0 2403 Sep 5 15:43 2010 control . tar . gz
rw -r - -r - - 0/0 751613 Sep 5 15:43 2010 data . tar . gz

I debian-binary: version of the deb file format, "2.0\n"

I control.tar.gz: metadata about the package
control, md5sums, (pre|post)(rm|inst), triggers, shlibs, . . .
I data.tar.gz: data files of the package

I You could create your .deb files manually

http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/

I But most people dont do it that way

This tutorial: create Debian packages, the Debian way

Debian Packaging Tutorial 7 / 85

Tools you will need

I A Debian (or Ubuntu) system (with root access)

I Some packages:
I build-essential: has dependencies on the packages that will be

assumed to be available on the developers machine (no need to

specify them in the Build-Depends: control field of your package)
I includes a dependency on dpkg-dev, which contains basic

Debian-specific tools to create packages

I devscripts: contains many useful scripts for Debian maintainers

Many other tools will also be mentioned later, such as debhelper, cdbs, quilt,
pbuilder, sbuild, lintian, svn-buildpackage, git-buildpackage, . . .
Install them when you need them.

Debian Packaging Tutorial 8 / 85

General packaging workflow

Debian mirror Web upstream source

apt-get source dget dh_make

where most of the

source package
manual work is done
debuild (build and test with lintian)
or dpkg-buildpackage

one or several binary packages .deb

upload (dput) install (debi)

Debian Packaging Tutorial 9 / 85

Example: rebuilding dash
1 Install packages needed to build dash, and devscripts
sudo apt-get build-dep dash
(requires deb-src lines in /etc/apt/sources.list)
sudo apt-get install --no-install-recommends devscripts
fakeroot
2 Create a working directory, and get in it:
mkdir /tmp/debian-tutorial ; cd /tmp/debian-tutorial
3 Grab the dash source package
apt-get source dash
(This needs you to have deb-src lines in your /etc/apt/sources.list)
4 Build the package
cd dash-*
debuild -us -uc (-us -uc disables signing the package with GPG)
5 Check that it worked
I There are some new .deb files in the parent directory

6 Look at the debian/ directory

I Thats where the packaging work is done

Debian Packaging Tutorial 10 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 11 / 85

Source package
I One source package can generate several binary packages
e.g. the libtar source generates the libtar0 and libtar-dev binary packages
I Two kinds of packages: (if unsure, use non-native)
I Native packages: normally for Debian specific software (dpkg, apt)
I Non-native packages: software developed outside Debian
I Main file: .dsc (meta-data)
I Other files depending on the version of the source format
I 1.0 or 3.0 (native): package_version.tar.gz

I 1.0 (non-native):
I pkg_ver.orig.tar.gz: upstream source

I pkg_debver.diff.gz: patch to add Debian-specific changes

I 3.0 (quilt):
I pkg_ver.orig.tar.gz: upstream source

I pkg_debver.debian.tar.gz: tarball with the Debian changes

(See dpkg-source(1) for exact details)

Debian Packaging Tutorial 12 / 85
Source package example (wget_1.12-2.1.dsc)
Format : 3.0 ( quilt )
Source : wget
Binary : wget
Architecture : any
Version : 1.12 -2.1
Maintainer : Noel Kothe < noel@debian . org >
Homepage : http :// www . gnu . org / software / wget /
Standards - Version : 3.8.4
Build - Depends : debhelper ( > > 5.0.0) , gettext , texinfo ,
libssl - dev ( >= 0.9.8) , dpatch , info2man
Checksums - Sha1 :
50 d4ed2441e67 [..]1 ee0e94248 2464747 wget_1 .12. orig . tar . gz
d4c1c8bbe431d [..] dd7cef3611 48308 wget_1 .12 -2.1. debian . tar . gz
Checksums - Sha256 :
7578 ed0974e12 [..] dcba65b572 2464747 wget_1 .12. orig . tar . gz
1 e9b0c4c00eae [..]89 c402ad78 48308 wget_1 .12 -2.1. debian . tar . gz
Files :
141461 b9c04e4 [..]9 d1f2abf83 2464747 wget_1 .12. orig . tar . gz
e93123c934e3c [..]2 f380278c2 48308 wget_1 .12 -2.1. debian . tar . gz

Debian Packaging Tutorial 13 / 85

Retrieving an existing source package
I From the Debian archive:
I apt-get source package

I apt-get source package=version

I apt-get source package/release

(You need deb-src lines in sources.list)

I From the Internet:

I dget url-to.dsc

I dget http://snapshot.debian.org/archive/debian-archive/

20090802T004153Z/debian/dists/bo/main/source/web/
wget_1.4.4-6.dsc
(snapshot.d.o provides all packages from Debian since 2005)

I From the (declared) version control system:

I debcheckout package

I Once downloaded, extract with dpkg-source -x file.dsc

Debian Packaging Tutorial 14 / 85

Creating a basic source package

I Download the upstream source

(upstream source = the one from the softwares original developers)
I Rename to <source_package >_<upstream_version >.orig.tar.gz
(example: simgrid_3.6.orig.tar.gz)
I Untar it
I Rename the directory to <source_package >-<upstream_version >
(example: simgrid-3.6)
I cd <source_package >-<upstream_version > && dh_make
(from the dh-make package)
I There are some alternatives to dh_make for specific sets of packages:
dh-make-perl, dh-make-php, . . .
I debian/ directory created, with a lot of files in it

Debian Packaging Tutorial 15 / 85

Files in debian/
All the packaging work should be made by modifying files in debian/

I Main files:
I control meta-data about the package (dependencies, etc.)

I rules specifies how to build the package

I copyright copyright information for the package

I changelog history of the Debian package

I Other files:
I compat

I watch

I dh_install* targets

*.dirs, *.docs, *.manpages, . . .

I maintainer scripts
*.postinst, *.prerm, . . .
I source/format
I patches/ if you need to modify the upstream sources
I Several files use a format based on RFC 822 (mail headers)

Debian Packaging Tutorial 16 / 85

debian/changelog
I Lists the Debian packaging changes
I Gives the current version of the package
1.2.1.1-5
Upstream Debian
version revision
I Edited manually or with dch
I Create a changelog entry for a new release: dch -i

I Special format to automatically close Debian or Ubuntu bugs

Debian: Closes: #595268; Ubuntu: LP: #616929
I Installed as /usr/share/doc/package /changelog.Debian.gz
mpich2 (1.2.1.1 -5) unstable ; urgency = low

* Use / usr / bin / python instead of / usr / bin / python2 .5. Allow
to drop dependency on python2 .5. Closes : #595268
* Make / usr / bin / mpdroot setuid . This is the default after
the installation of mpich2 from source , too . LP : #616929
+ Add corresponding lintian override .

-- Lucas Nussbaum < lucas@debian . org > Wed , 15 Sep 2010 18:13:44 +0200

Debian Packaging Tutorial 17 / 85

debian/control
I Package metadata
I For the source package itself

I For each binary package built from this source

I Package name, section, priority, maintainer, uploaders,

build-dependencies, dependencies, description, homepage, . . .
I Documentation: Debian Policy chapter 5
https://www.debian.org/doc/debian-policy/ch-controlfields
Source : wget
Section : web
Priority : important
Maintainer : Noel Kothe < noel@debian . org >
Build - Depends : debhelper ( > > 5.0.0) , gettext , texinfo ,
libssl - dev ( >= 0.9.8) , dpatch , info2man
Standards - Version : 3.8.4
Homepage : http :// www . gnu . org / software / wget /

Package : wget
Architecture : any
Depends : $ { shlibs : Depends } , $ { misc : Depends }
Description : retrieves files from the web
Wget is a network utility to retrieve files from the Web
Debian Packaging Tutorial 18 / 85
Architecture: all or any
Two kinds of binary packages:

I Packages with different contents on each Debian architecture

I Example: C program

I Architecture: any in debian/control

I Or, if it only works on a subset of architectures:

Architecture: amd64 i386 ia64 hurd-i386

I buildd.debian.org: builds all the other architectures for you on upload

I Named package _version _architecture.deb

I Packages with the same content on all architectures

I Example: Perl library

I Architecture: all in debian/control

I Named package _version _all.deb

A source package can generate a mix of Architecture: any and

Architecture: all binary packages

Debian Packaging Tutorial 19 / 85

debian/rules

I Makefile

I Interface used to build Debian packages

I Documented in Debian Policy, chapter 4.8

https://www.debian.org/doc/debian-policy/ch-source#s-debianrules

I Required targets:
I build, build-arch, build-indep: should perform all the

configuration and compilation

I binary, binary-arch, binary-indep: build the binary packages
I dpkg-buildpackage will call binary to build all the packages, or

binary-arch to build only the Architecture: any packages

I clean: clean up the source directory

Debian Packaging Tutorial 20 / 85

Packaging helpers debhelper
I You could write shell code in debian/rules directly
I See the rsync package for example

I Better practice (used by most packages): use a Packaging helper

I Most popular one: debhelper (used by 98% of packages)
I Goals:
I Factor the common tasks in standard tools used by all packages

I Fix some packaging bugs once for all packages

dh_installdirs, dh_installchangelogs, dh_installdocs, dh_installexamples, dh_install,

dh_installdebconf, dh_installinit, dh_link, dh_strip, dh_compress, dh_fixperms, dh_perl,
dh_makeshlibs, dh_installdeb, dh_shlibdeps, dh_gencontrol, dh_md5sums, dh_builddeb, . . .

I Called from debian/rules

I Configurable using command parameters or files in debian/
package.docs, package.examples, package.install, package.manpages, ...
I Third-party helpers for sets of packages: python-support, dh_ocaml, . . .
I Gotcha: debian/compat: Debhelper compatibility version (use "7")
Debian Packaging Tutorial 21 / 85
debian/rules using debhelper (1/2)
#!/ usr / bin / make -f

# Uncomment this to turn on verbose mode .

# export DH_VERBOSE =1

build :
$ ( MAKE )
# docbook - to - man debian / packagename . sgml > packagename .1

clean :
dh_testdir
dh_testroot
rm -f build - stamp configure - stamp
$ ( MAKE ) clean
dh_clean

install : build
dh_testdir
dh_testroot
dh_clean -k
dh_installdirs
# Add here commands to install the package into debian / package
$ ( MAKE ) DESTDIR = $ ( CURDIR )/ debian / packagename install

Debian Packaging Tutorial 22 / 85

debian/rules using debhelper (2/2)
# Build architecture - independent files here .
binary - indep : build install

# Build architecture - dependent files here .

binary - arch : build install
dh_testdir
dh_testroot
dh_installchangelogs
dh_installdocs
dh_installexamples
dh_install
dh_installman
dh_link
dh_strip
dh_compress
dh_fixperms
dh_installdeb
dh_shlibdeps
dh_gencontrol
dh_md5sums
dh_builddeb

binary : binary - indep binary - arch

. PHONY : build clean binary - indep binary - arch binary install configure
Debian Packaging Tutorial 23 / 85
CDBS
I With debhelper, still a lot of redundancy between packages
I Second-level helpers that factor common functionality
I E.g. building with ./configure && make && make install or

CMake
I CDBS:
I Introduced in 2005, based on advanced GNU make magic

I Documentation: /usr/share/doc/cdbs/

I Support for Perl, Python, Ruby, GNOME, KDE, Java, Haskell, . . .

I But some people hate it:

I Sometimes difficult to customize package builds:

"twisty maze of makefiles and environment variables"

I Slower than plain debhelper (many useless calls to dh_*)

#!/ usr / bin / make -f

include / usr / share / cdbs /1/ rules / debhelper . mk
include / usr / share / cdbs /1/ class / autotools . mk

# add an action after the build

build / mypackage ::
/ bin / bash debian / scripts / foo . sh

Debian Packaging Tutorial 24 / 85

Dh (aka Debhelper 7, or dh7)

I Introduced in 2008 as a CDBS killer

I dh command that calls dh_*
I Simple debian/rules, listing only overrides
I Easier to customize than CDBS
I Doc: manpages (debhelper(7), dh(1)) + slides from DebConf9 talk
http://kitenet.net/~joey/talks/debhelper/debhelper-slides.pdf

#!/ usr / bin / make -f

%:
dh $@

override_dh_auto_configure :
d h _ a u t o _ c o n f i g u r e -- -- with - kitchen - sink

override_dh_auto_build :
make world

Debian Packaging Tutorial 25 / 85

Classic debhelper vs CDBS vs dh
I Mind shares:
Classic debhelper: 15% CDBS: 15% dh: 68%
I Which one should I learn?
I Probably a bit of all of them

I You need to know debhelper to use dh and CDBS

I You might have to modify CDBS packages

I Which one should I use for a new package?

I dh (only solution with an increasing mind share)

80 debhelper
Market share (%)

dh
60 CDBS

40

20

0
2005 2007 2010 2013 2016
Time
Debian Packaging Tutorial 26 / 85
Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 27 / 85

Building packages
I apt-get build-dep mypackage
Installs the build-dependencies (for a package already in Debian)
Or mk-build-deps -ir (for a package not uploaded yet)

I debuild: build, test with lintian, sign with GPG

I Also possible to call dpkg-buildpackage directly

I Usually with dpkg-buildpackage -us -uc

I It is better to build packages in a clean & minimal environment

I pbuilder helper to build packages in a chroot

Good documentation: https://wiki.ubuntu.com/PbuilderHowto

(optimization: cowbuilder ccache distcc)
I schroot and sbuild: used on the Debian build daemons
(not as simple as pbuilder, but allows LVM snapshots
see: https://help.ubuntu.com/community/SbuildLVMHowto )

I Generates .deb files and a .changes file

I .changes: describes what was built; used to upload the package

Debian Packaging Tutorial 28 / 85

Installing and testing packages
I Install the package locally: debi (will use .changes to know what to install)

I List the content of the package: debc ../mypackage<TAB>.changes

I Compare the package with a previous version:

debdiff ../mypackage_1_*.changes ../mypackage_2_*.changes
or to compare the sources:
debdiff ../mypackage_1_*.dsc ../mypackage_2_*.dsc

I Check the package with lintian (static analyzer):

lintian ../mypackage<TAB>.changes
lintian -i: gives more information about the errors
lintian -EviIL +pedantic: shows more problems

I Upload the package to Debian (dput) (needs configuration)

I Manage a private Debian archive with reprepro or aptly

Documentation:
https://wiki.debian.org/HowToSetupADebianRepository

Debian Packaging Tutorial 29 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 30 / 85

Practical session 1: modifying the grep package
1 Go to http://ftp.debian.org/debian/pool/main/g/grep/ and
download version 2.12-2 of the package
I If the source package is not unpacked automatically, unpack it with

dpkg-source -x grep_*.dsc
2 Look at the files in debian/.
I How many binary packages are generated by this source package?

I Which packaging helper does this package use?

3 Build the package

4 We are now going to modify the package. Add a changelog entry and
increase the version number.
5 Now disable perl-regexp support (it is a ./configure option)
6 Rebuild the package
7 Compare the original and the new package with debdiff
8 Install the newly built package

Debian Packaging Tutorial 31 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 32 / 85

debian/copyright
I Copyright and license information for the source and the packaging
I Traditionally written as a text file
I New machine-readable format:
https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

Format : https :// www . debian . org / doc / packaging - manuals / copyright - format /1.0/
Upstream - Name : X Solitaire
Source : ftp :// ftp . example . com / pub / games

Files : *
Copyright : Copyright 1998 John Doe < jdoe@example . com >
License : GPL -2+
This program is free software ; you can redistribute it
[...]
.
On Debian systems , the full text of the GNU General Public
License version 2 can be found in the file
/ usr / share / common - licenses / GPL -2 .

Files : debian /*
Copyright : Copyright 1998 Jane Smith < jsmith@example . net >
License :
[ LICENSE TEXT ]

Debian Packaging Tutorial 33 / 85

Modifying the upstream source

Often needed:
I Fix bugs or add customizations that are specific to Debian
I Backport fixes from a newer upstream release

Several methods to do it:

I Modifying the files directly
I Simple

I But no way to track and document the changes

I Using patch systems

I Eases contributing your changes to upstream

I Helps sharing the fixes with derivatives

I Gives more exposure to the changes

http://patch-tracker.debian.org/ (down currently)

Debian Packaging Tutorial 34 / 85

Patch systems
I Principle: changes are stored as patches in debian/patches/

I Applied and unapplied during build

I Past: several implementations simple-patchsys (cdbs), dpatch, quilt

I Each supports two debian/rules targets:

I debian/rules patch: apply all patches

I debian/rules unpatch: de-apply all patches

I More documentation: https://wiki.debian.org/debian/patches

I New source package format with built-in patch system: 3.0 (quilt)
I Recommended solution

I You need to learn quilt

http://pkg-perl.alioth.debian.org/howto/quilt.html
I Patch-system-agnostic tool in devscripts: edit-patch

Debian Packaging Tutorial 35 / 85

Documentation of patches

I Standard headers at the beginning of the patch

I Documented in DEP-3 - Patch Tagging Guidelines

http://dep.debian.net/deps/dep3/

Description : Fix widget frobnication speeds

Frobnicating widgets too quickly tended to cause explosions .
Forwarded : http :// lists . example . com /2010/03/1234. html
Author : John Doe < johndoe - guest@users . alioth . debian . org >
Applied - Upstream : 1.2 , http :// bzr . foo . com / frobnicator / revision /123
Last - Update : 2010 -03 -29

--- a / src / widgets . c

+++ b / src / widgets . c
@@ -101 ,9 +101 ,6 @@ struct {

Debian Packaging Tutorial 36 / 85

Doing things during installation and removal
I Decompressing the package is sometimes not enough
I Create/remove system users, start/stop services, manage alternatives
I Done in maintainer scripts
preinst, postinst, prerm, postrm
I Snippets for common actions can be generated by debhelper

I Documentation:
I Debian Policy Manual, chapter 6

https://www.debian.org/doc/debian-policy/ch-maintainerscripts
I Debian Developers Reference, chapter 6.4
https://www.debian.org/doc/developers-reference/best-pkging-practices.html

I https://people.debian.org/~srivasta/MaintainerScripts.html

I Prompting the user

I Must be done with debconf

I Documentation: debconf-devel(7) (debconf-doc package)

Debian Packaging Tutorial 37 / 85

Monitoring upstream versions

I Specify where to look in debian/watch (see uscan(1))

version =3

http :// tmrc . mit . edu / mirror / twisted / Twisted /(\ d \.\ d )/ \
Twisted -([\ d \.]*)\. tar \. bz2

I There are automated trackers of new upstream versions, that notify the
maintainer on various dashboards including
https://tracker.debian.org/ and https://udd.debian.org/dmd/

I uscan: run a manual check

I uupdate: try to update your package to the latest upstream version

Debian Packaging Tutorial 38 / 85

 Packaging with a Version Control System
I Several tools to help manage branches and tags for your packaging work:
svn-buildpackage, git-buildpackage
I Example: git-buildpackage
I upstream branch to track upstream with upstream/version tags

I master branch tracks the Debian package

I debian/version tags for each upload

I pristine-tar branch to be able to rebuild the upstream tarball

Doc: http://honk.sigxcpu.org/projects/git-buildpackage/
manual-html/gbp.html
I Vcs-* fields in debian/control to locate the repository
I https://wiki.debian.org/Alioth/Git

I https://wiki.debian.org/Alioth/Svn

Vcs - Browser : http :// anonscm . debian . org / gitweb /? p = collab - maint / devscripts . git
Vcs - Git : git :// anonscm . debian . org / collab - maint / devscripts . git

Vcs - Browser : http :// svn . debian . org / viewsvn / pkg - perl / trunk / libwww - perl /
Vcs - Svn : svn :// svn . debian . org / pkg - perl / trunk / libwww - perl

I VCS-agnostic interface: debcheckout, debcommit, debrelease

I debcheckout grep checks out the source package from Git

Debian Packaging Tutorial 39 / 85

Backporting packages

I Goal: use a newer version of a package on an older system

e.g. use mutt from Debian unstable on Debian stable

I General idea:
I Take the source package from Debian unstable

I Modify it so that it builds and works fine on Debian stable

I Sometimes trivial (no changes needed)

I Sometimes difficult

I Sometimes impossible (many unavailable dependencies)

I Some backports are provided and supported by the Debian project

http://backports.debian.org/

Debian Packaging Tutorial 40 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 41 / 85

Several ways to contribute to Debian
I Worst way to contribute:
1 Package your own application
2 Get it into Debian
3 Disappear

I Better ways to contribute:

I Get involved in packaging teams

I Many teams that focus on set of packages, and need help

I List available at https://wiki.debian.org/Teams

I An excellent way to learn from more experienced contributors

I Adopt existing unmaintained packages (orphaned packages)

I Bring new software to Debian

I Only if its interesting/useful enough, please

I Are there alternatives already packaged in Debian?

Debian Packaging Tutorial 42 / 85

Adopting orphaned packages
I Many unmaintained packages in Debian
I Full list + process: https://www.debian.org/devel/wnpp/
I Installed on your machine: wnpp-alert
Or better: how-can-i-help
I Different states:
I Orphaned: the package is unmaintained
Feel free to adopt it
I RFA: Request For Adopter
Maintainer looking for adopter, but continues work in the meantime
Feel free to adopt it. A mail to the current maintainer is polite
I ITA: Intent To Adopt
Someone intends to adopt the package
You could propose your help!
I RFH: Request For Help
The maintainer is looking for help
I Some unmaintained packages not detected not orphaned yet
I When in doubt, ask [email protected]
or #debian-qa on irc.debian.org Debian Packaging Tutorial 43 / 85
Adopting a package: example
From : You < you@yourdomain >
To : 640454 @bugs . debian . org , control@bugs . debian . org
Cc : Francois Marier < fran coi s@de bian . org >
Subject : ITA : verbiste -- French conjugator

retitle 640454 ITA : verbiste -- French conjugator

owner 640454 !
thanks

Hi ,

I am using verbiste and I am willing to take care of the package .

Cheers ,

You

I Polite to contact the previous maintainer (especially if the package was

RFAed, not orphaned)
I Very good idea to contact the upstream project

Debian Packaging Tutorial 44 / 85

Getting your package in Debian

I You do not need any official status to get your package into Debian
1 Submit an ITP bug (Intend To Package) using reportbug wnpp

2 Prepare a source package

3 Find a Debian Developer that will sponsor your package

I Official status (when you are an experienced package maintainer):

I Debian Maintainer (DM):

Permission to upload your own packages

See https://wiki.debian.org/DebianMaintainer
I Debian Developer (DD):
Debian project member; can vote and upload any package

Debian Packaging Tutorial 45 / 85

Things to check before asking for sponsorship

I Debian puts a lot of focus on quality

I Generally, sponsors are hard to find and busy
I Make sure your package is ready before asking for sponsorship

I Things to check:
I Avoid missing build-dependencies: make sure that your package

build fine in a clean sid chroot

I Using pbuilder is recommended

I Run lintian -EviIL +pedantic on your package

I Errors must be fixed, all other problems should be fixed

I Do extensive testing of your package, of course

I In doubt, ask for help

Debian Packaging Tutorial 46 / 85

Where to find help?
Help you will need:
I Advice and answers to your questions, code reviews
I Sponsorship for your uploads, once your package is ready

You can get help from:

I Other members of a packaging team
I List of teams: https://wiki.debian.org/Teams

I The Debian Mentors group (if your package does not fit in a team)
I https://wiki.debian.org/DebianMentorsFaq

I Mailing list: [email protected]

(also a good way to learn by accident)

I IRC: #debian-mentors on irc.debian.org
I http://mentors.debian.net/
I Documentation: http://mentors.debian.net/intro-maintainers
I Localized mailing lists (get help in your language)
I debian-devel-{french,italian,portuguese,spanish}@lists.d.o

I Full list: https://lists.debian.org/devel.html

I Or users lists: https://lists.debian.org/users.html

Debian Packaging Tutorial 47 / 85

More documentation
I Debian Developers Corner
https://www.debian.org/devel/
Links to many resources about Debian development
I Guide for Debian Maintainers
https://www.debian.org/doc/manuals/debmake-doc/
I Debian Developers Reference
https://www.debian.org/doc/developers-reference/
Mostly about Debian procedures, but also some best packaging practices (part 6)
I Debian Policy
https://www.debian.org/doc/debian-policy/
I All the requirements that every package must satisfy
I Specific policies for Perl, Java, Python, . . .

I Ubuntu Packaging Guide

http://developer.ubuntu.com/resources/tools/packaging/

Debian Packaging Tutorial 48 / 85

Debian dashboards for maintainers

I Source package centric:

https://tracker.debian.org/dpkg

I Maintainer/team centric: Developers Packages Overview (DDPO)

https://qa.debian.org/developer.php?login=
[email protected]

I TODO-list oriented: Debian Maintainer Dashboard (DMD)

https://udd.debian.org/dmd/

Debian Packaging Tutorial 49 / 85

Using the Debian Bug Tracking System (BTS)
I A quite unique way to manage bugs
I Web interface to view bugs

I Email interface to make changes to bugs

I Adding information to bugs:

I Write to [email protected] (does not include the submitter,

you need to add [email protected])

I Changing bug status:
I Send commands to [email protected]

I Command-line interface: bts command in devscripts

I Documentation: https://www.debian.org/Bugs/server-control

I Reporting bugs: use reportbug

I Normally used with a local mail server: install ssmtp or nullmailer

I Or use reportbug --template, then send (manually) to

[email protected]

Debian Packaging Tutorial 50 / 85

Using the BTS: examples

I Sending an email to the bug and the submitter:

https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=680822#10
I Tagging and changing the severity:
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=680227#10
I Reassigning, changing the severity, retitling . . . :
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=680822#93
I notfound, found, notfixed, fixed are for version-tracking

See https://wiki.debian.org/HowtoUseBTS#Version_tracking
I Using usertags: https:
//bugs.debian.org/cgi-bin/bugreport.cgi?msg=42;bug=642267
See https://wiki.debian.org/bugs.debian.org/usertags
I BTS Documentation:
I https://www.debian.org/Bugs/

I https://wiki.debian.org/HowtoUseBTS

Debian Packaging Tutorial 51 / 85

More interested in Ubuntu?

I Ubuntu mainly manages the divergence with Debian

I No real focus on specific packages

Instead, collaboration with Debian teams

I Usually recommend uploading new packages to Debian first

https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages

I Possibly a better plan:

I Get involved in a Debian team and act as a bridge with Ubuntu

I Help reduce divergence, triage bugs in Launchpad

I Many Debian tools can help:
I Ubuntu column on the Developers packages overview

I Ubuntu box on the Package Tracking System

I Receive launchpad bugmail via the PTS

Debian Packaging Tutorial 52 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 53 / 85

Conclusions
I You now have a full overview of Debian packaging

I But you will need to read more documentation

I Best practices have evolved over the years

I If not sure, use the dh packaging helper, and the 3.0 (quilt) format

I Things that were not covered in this tutorial:

I UCF manage user changes to configuration files when upgrading

I dpkg triggers group similar maintainer scripts actions together

I Debian development organization:
I Suites: stable, testing, unstable, experimental, security,

*-updates, backports, . . .
I Debian Blends subsets of Debian targeting specific groups

Feedback: [email protected]

Debian Packaging Tutorial 54 / 85

 Legal stuff

Copyright 20112016
c Lucas Nussbaum [email protected]

This document is free software: you can redistribute it and/or modify it under either
(at your option):

I The terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later version.
http://www.gnu.org/licenses/gpl.html

I The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported License.

http://creativecommons.org/licenses/by-sa/3.0/

Debian Packaging Tutorial 55 / 85

Contribute to this tutorial

I Contribute:
I apt-get source packaging-tutorial
I debcheckout packaging-tutorial
I git clone
git://git.debian.org/collab-maint/packaging-tutorial.git
I http://git.debian.org/?p=collab-maint/packaging-tutorial.git
I Open bugs: bugs.debian.org/src:packaging-tutorial

I Provide feedback:
I mailto:[email protected]

I What should be added to this tutorial?

I What should be improved?
I reportbug packaging-tutorial

Debian Packaging Tutorial 56 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 57 / 85

Practical session 2: packaging GNUjump
1 Download GNUjump 1.0.8 from
http://ftp.gnu.org/gnu/gnujump/gnujump-1.0.8.tar.gz

2 Create a Debian package for it

I Install build-dependencies so that you can build the package

I Fix bugs

I Get a basic working package

I Finish filling debian/control and other files

3 Enjoy

Debian Packaging Tutorial 58 / 85

Practical session 2: packaging GNUjump (tips)
I To get a basic working package, use dh_make
I To start with, creating a 1.0 source package is easier than 3.0 (quilt)
(change that in debian/source/format)
I To search for missing build-dependencies, find a missing file, and use
apt-file to find the missing package
I If you encounter that error:
/ usr / bin / ld : SDL_rotozoom . o : undefined reference to symbol ceil@@GLIBC_2 .2.5
// lib / x86_64 - linux - gnu / libm . so .6: error adding symbols : DSO missing from command line
collect2 : error : ld returned 1 exit status
Makefile :376: recipe for target gnujump failed

You need to add -lm to the linker command line:

Edit src/Makefile.am and replace
gn ujum p_LD FLAG S = $ ( all_libraries )

by
gn ujum p_LD FLAG S = -Wl , - - as - needed
gnujump_LDADD = $ ( all_libraries ) - lm

Then run autoreconf -i

Debian Packaging Tutorial 59 / 85

Practical session 3: packaging a Java library

1 Take a quick look at some documentation about Java packaging:

I https://wiki.debian.org/Java
I https://wiki.debian.org/Java/Packaging
I https://www.debian.org/doc/packaging-manuals/java-policy/
I http://pkg-java.alioth.debian.org/docs/tutorial.html
I Paper and slides from a Debconf10 talk about javahelper:
http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf
http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-slides.pdf

2 Download IRClib from http://moepii.sourceforge.net/

3 Package it

Debian Packaging Tutorial 60 / 85

Practical session 4: packaging a Ruby gem

1 Take a quick look at some documentation about Ruby packaging:

I https://wiki.debian.org/Ruby
I https://wiki.debian.org/Teams/Ruby
I https://wiki.debian.org/Teams/Ruby/Packaging
I gem2deb(1), dh_ruby(1) (in the gem2deb package)

2 Create a basic Debian source package from the peach gem:

gem2deb peach
3 Improve it so that it becomes a proper Debian package

Debian Packaging Tutorial 61 / 85

Practical session 5: packaging a Perl module

1 Take a quick look at some documentation about Perl packaging:

I http://pkg-perl.alioth.debian.org/
I https://wiki.debian.org/Teams/DebianPerlGroup
I dh-make-perl(1), dpt(1) (in the pkg-perl-tools package)

2 Create a basic Debian source package from the Acme CPAN distribution:
dh-make-perl --cpan Acme
3 Improve it so that it becomes a proper Debian package

Debian Packaging Tutorial 62 / 85

Outline
1 Introduction

2 Creating source packages

3 Building and testing packages

4 Practical session 1: modifying the grep package

5 Advanced packaging topics

6 Maintaining packages in Debian

7 Conclusions

8 Additional practical sessions

9 Answers to practical sessions

Debian Packaging Tutorial 63 / 85

 Answers to
practical sessions

Debian Packaging Tutorial 64 / 85

Practical session 1: modifying the grep package

1 Go to http://ftp.debian.org/debian/pool/main/g/grep/ and
download version 2.12-2 of the package
2 Look at the files in debian/.
I How many binary packages are generated by this source package?

I Which packaging helper does this package use?

3 Build the package

4 We are now going to modify the package. Add a changelog entry and
increase the version number.
5 Now disable perl-regexp support (it is a ./configure option)
6 Rebuild the package
7 Compare the original and the new package with debdiff
8 Install the newly built package

Debian Packaging Tutorial 65 / 85

Fetching the source
1 Go to http://ftp.debian.org/debian/pool/main/g/grep/ and
download version 2.12-2 of the package

I Use dget to download the .dsc file:

dget http://cdn.debian.net/debian/pool/main/g/grep/grep_2.12-2.dsc
I If you have deb-src for a Debian release that has grep version 2.12-2
(find out on https://tracker.debian.org/grep), you can use: apt-get
source grep=2.12-2
or apt-get source grep/release (e.g. grep/stable
or, if you feel lucky: apt-get source grep
I The grep source package is composed of three files:
I grep_2.12-2.dsc

I grep_2.12-2.debian.tar.bz2

I grep_2.12.orig.tar.bz2

This is typical of the "3.0 (quilt)" format.

I If needed, uncompress the source with
dpkg-source -x grep_2.12-2.dsc

Debian Packaging Tutorial 66 / 85

Looking around and building the package

2 Look at the files in debian/.

I How many binary packages are generated by this source package?

I Which packaging helper does this package use?

I According to debian/control, this package only generates one binary

package, named grep.
I According to debian/rules, this package is typical of classic debhelper
packaging, without using CDBS or dh. One can see the various calls to
dh_* commands in debian/rules.

3 Build the package

I Use apt-get build-dep grep to fetch the build-dependencies

I Then debuild or dpkg-buildpackage -us -uc (Takes about 1 min)

Debian Packaging Tutorial 67 / 85

Editing the changelog

4 We are now going to modify the package. Add a changelog entry and
increase the version number.

I debian/changelog is a text file. You could edit it and add a new entry
manually.
I Or you can use dch -i, which will add an entry and open the editor
I The name and email can be defined using the DEBFULLNAME and DEBEMAIL
environment variables
I After that, rebuild the package: a new version of the package is built
I Package versioning is detailed in section 5.6.12 of the Debian policy
https://www.debian.org/doc/debian-policy/ch-controlfields

Debian Packaging Tutorial 68 / 85

Disabling Perl regexp support and rebuilding

5 Now disable perl-regexp support (it is a ./configure option)

6 Rebuild the package

I Check with ./configure --help: the option to disable Perl regexp is

--disable-perl-regexp
I Edit debian/rules and find the ./configure line
I Add --disable-perl-regexp
I Rebuild with debuild or dpkg-buildpackage -us -uc

Debian Packaging Tutorial 69 / 85

Comparing and testing the packages

7 Compare the original and the new package with debdiff

8 Install the newly built package

I Compare the binary packages: debdiff ../*changes

I Compare the source packages: debdiff ../*dsc
I Install the newly built package: debi
Or dpkg -i ../grep_<TAB>
I grep -P foo no longer works!

Reinstall the previous version of the package:

I apt-get install --reinstall grep=2.6.3-3 (= previous version)

Debian Packaging Tutorial 70 / 85

Practical session 2: packaging GNUjump
1 Download GNUjump 1.0.8 from
http://ftp.gnu.org/gnu/gnujump/gnujump-1.0.8.tar.gz

2 Create a Debian package for it

I Install build-dependencies so that you can build the package

I Get a basic working package

I Finish filling debian/control and other files

3 Enjoy

Debian Packaging Tutorial 71 / 85

Step by step. . .
I wget http://ftp.gnu.org/gnu/gnujump/gnujump-1.0.8.tar.gz
I mv gnujump-1.0.8.tar.gz gnujump_1.0.8.orig.tar.gz
I tar xf gnujump_1.0.8.orig.tar.gz
I cd gnujump-1.0.8/
I dh_make -f ../gnujump-1.0.8.tar.gz
I Type of package: single binary (for now)

gnujump -1.0.8 $ ls debian /

changelog gnujump . default . ex preinst . ex
compat gnujump . doc - base . EX prerm . ex
control init . d . ex README . Debian
copyright manpage .1. ex README . source
docs manpage . sgml . ex rules
emacsen - install . ex manpage . xml . ex source
emacsen - remove . ex menu . ex watch . ex
emacsen - startup . ex postinst . ex
gnujump . cron . d . ex postrm . ex

Debian Packaging Tutorial 72 / 85

Step by step. . . (2)
I Look at debian/changelog, debian/rules, debian/control
(auto-filled by dh_make)
I In debian/control:
Build-Depends: debhelper (>= 7.0.50 ), autotools-dev
Lists the build-dependencies = packages needed to build the package
I Try to build the package as-is with debuild (thanks to dh magic)
I And add build-dependencies, until it builds

I Hint: use apt-cache search and apt-file to find the packages

I Example:

checking for sdl - config ... no

checking for SDL - version >= 1.2.0... no
[...]
configure : error : *** SDL version 1.2.0 not found !

Add libsdl1.2-dev to Build-Depends and install it.

I Better: use pbuilder to build in a clean environment

Debian Packaging Tutorial 73 / 85

Step by step. . . (3)
I Required build-dependencies are libsdl1.2-dev,
libsdl-image1.2-dev, libsdl-mixer1.2-dev
I Then, you will probably run into another error:
/ usr / bin / ld : SDL_rotozoom . o : undefined reference to symbol ceil@@GLIBC_2 .2.5
// lib / x86_64 - linux - gnu / libm . so .6: error adding symbols : DSO missing from command line
collect2 : error : ld returned 1 exit status
Makefile :376: recipe for target gnujump failed

I This problem is caused by bitrot: gnujump has not been adjusted following
linker changes.
I If you are using source format version 1.0, you can directly change
upstream sources.
I Edit src/Makefile.am and replace

gn ujum p_LD FLAG S = $ ( all_libraries )

by
gn ujum p_LD FLAG S = -Wl , - - as - needed
gnujump_LDADD = $ ( all_libraries ) - lm

I Then run autoreconf -i

Debian Packaging Tutorial 74 / 85
Step by step. . . (4)
I If you are using source format version 3.0 (quilt), use quilt to prepare a
patch. (see https://wiki.debian.org/UsingQuilt)
I export QUILT_PATCHES=debian/patches

I mkdir debian/patches

quilt new linker-fixes.patch

quilt add src/Makefile.am
I Edit src/Makefile.am and replace
gn ujum p_LD FLAG S = $ ( all_libraries )

by
gn ujum p_LD FLAG S = -Wl , - - as - needed
gnujump_LDADD = $ ( all_libraries ) - lm

I quilt refresh
I Since src/Makefile.am was changed, autoreconf must be called
during the build. To do that automatically with dh, change the dh call
in debian/rules from: dh $ --with autotools-dev
to: dh $ --with autotools-dev --with autoreconf
Debian Packaging Tutorial 75 / 85
Step by step. . . (5)
I The package should now build fine.
I Use debc to list the content of the generated package, and debi to install
it and test it.
I Test the package with lintian
I While not a strict requirement, it is recommended that packages

uploaded to Debian are lintian-clean

I More problems can be listed using lintian -EviIL +pedantic
I Some hints:
I Remove the files that you dont need in debian/

I Fill in debian/control
I Install the executable to /usr/games by overriding
dh_auto_configure
I Use hardening compiler flags to increase security.
See https://wiki.debian.org/Hardening

Debian Packaging Tutorial 76 / 85

Step by step. . . (6)

I Compare your package with the one already packaged in Debian:

I It splits the data files to a second package, that is the same across all

architectures ( saves space in the Debian archive)

I It installs a .desktop file (for the GNOME/KDE menus) and also
integrates into the Debian menu
I It fixes a few minor problems using patches

Debian Packaging Tutorial 77 / 85

Practical session 3: packaging a Java library

1 Take a quick look at some documentation about Java packaging:

I https://wiki.debian.org/Java
I https://wiki.debian.org/Java/Packaging
I https://www.debian.org/doc/packaging-manuals/java-policy/
I http://pkg-java.alioth.debian.org/docs/tutorial.html
I Paper and slides from a Debconf10 talk about javahelper:
http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf
http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-slides.pdf

2 Download IRClib from http://moepii.sourceforge.net/

3 Package it

Debian Packaging Tutorial 78 / 85

Step by step. . .

I apt-get install javahelper

I Create a basic source package: jh_makepkg
I Library

I None

I Default Free compiler/runtime

I Look at and fix debian/*

I dpkg-buildpackage -us -uc or debuild
I lintian, debc, etc.
I Compare your result with the libirclib-java source package

Debian Packaging Tutorial 79 / 85

Practical session 4: packaging a Ruby gem

1 Take a quick look at some documentation about Ruby packaging:

I https://wiki.debian.org/Ruby
I https://wiki.debian.org/Teams/Ruby
I https://wiki.debian.org/Teams/Ruby/Packaging
I gem2deb(1), dh_ruby(1) (in the gem2deb package)

2 Create a basic Debian source package from the peach gem:

gem2deb peach
3 Improve it so that it becomes a proper Debian package

Debian Packaging Tutorial 80 / 85

Step by step. . .

gem2deb peach:
I Downloads the gem from rubygems.org
I Creates a suitable .orig.tar.gz archive, and untar it
I Initializes a Debian source package based on the gems metadata
I Named ruby-gemname

I Tries to build the Debian binary package (this might fail)

dh_ruby (included in gem2deb) does the Ruby-specific tasks:

I Build C extensions for each Ruby version
I Copy files to their destination directory
I Update shebangs in executable scripts
I Run tests defined in debian/ruby-tests.rb, debian/ruby-tests.rake,
or debian/ruby-test-files.yaml, as well as various other checks

Debian Packaging Tutorial 81 / 85

Step by step. . . (2)

Improve the generated package:

I Run debclean to clean the source tree. Look at debian/.
I changelog and compat should be correct
I Edit debian/control: improve Description
I Write a proper copyright file based on the upstream files
I Build the package
I Compare your package with the ruby-peach package in the Debian
archive

Debian Packaging Tutorial 82 / 85

Practical session 5: packaging a Perl module

1 Take a quick look at some documentation about Perl packaging:

I http://pkg-perl.alioth.debian.org/
I https://wiki.debian.org/Teams/DebianPerlGroup
I dh-make-perl(1), dpt(1) (in the pkg-perl-tools package)

2 Create a basic Debian source package from the Acme CPAN distribution:
dh-make-perl --cpan Acme
3 Improve it so that it becomes a proper Debian package

Debian Packaging Tutorial 83 / 85

Step by step. . .

dh-make-perl --cpan Acme:

I Downloads the tarball from the CPAN
I Creates a suitable .orig.tar.gz archive, and untars it
I Initializes a Debian source package based on the distributions metadata
I Named libdistname -perl

Debian Packaging Tutorial 84 / 85

Step by step. . . (2)

Improve the generated package:

I debian/changelog, debian/compat, debian/libacme-perl.docs, and
debian/watch should be correct
I Edit debian/control: improve Description, and remove boilerplate at
the bottom
I Edit debian/copyright: remove boilerplate paragraph at the top, add
years of copyright to the Files: * stanza

Debian Packaging Tutorial 85 / 85