Debian Packaging Tutorial

Home , Alioth (Debian), APT (software), Backporting, Debian, Deb (file format), Dpkg

version 0.27 – 2021-01-08

Debian Packaging Tutorial 1 / 89 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 / 89 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 / 89 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 / 89 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 it’s 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 / 89 Debian packages

I .deb ﬁles (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 / 89 The Deb package format

I .deb ﬁle: 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 ﬁle 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 ﬁles of the package

I You could create your .deb ﬁles manually http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/

I But most people don’t do it that way

This tutorial: create Debian packages, the Debian way

Debian Packaging Tutorial 7 / 89 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 developer’s machine (no need to specify them in the Build-Depends: control ﬁeld of your package) I includes a dependency on dpkg-dev, which contains basic Debian-speciﬁc 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 / 89 General packaging workﬂow

Debian mirror Web upstream source

apt-get source dget dh_make

source package where most of the 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 / 89 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 ﬁles in the parent directory

6 Look at the debian/ directory I That’s where the packaging work is done

Debian Packaging Tutorial 10 / 89 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 / 89 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 / 89 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 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: 50d4ed2441e67[..]1ee0e94248 2464747 wget_1.12.orig.tar.gz d4c1c8bbe431d[..]dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz Checksums-Sha256: 7578ed0974e12[..]dcba65b572 2464747 wget_1.12.orig.tar.gz 1e9b0c4c00eae[..]89c402ad78 48308 wget_1.12-2.1.debian.tar.gz Files : 141461b9c04e4[..]9d1f2abf83 2464747 wget_1.12.orig.tar.gz e93123c934e3c[..]2f380278c2 48308 wget_1.12-2.1.debian.tar.gz

Debian Packaging Tutorial 13 / 89 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 / 89 Creating a basic source package

I Download the upstream source (upstream source = the one from the software’s original developers) I Rename to _.orig.tar.gz (example: simgrid_3.6.orig.tar.gz) I Untar it I Rename the directory to - (example: simgrid-3.6) I cd - && dh_make (from the dh-make package) I There are some alternatives to dh_make for speciﬁc sets of packages: dh-make-perl, dh-make-php,... I debian/ directory created, with a lot of ﬁles in it

Debian Packaging Tutorial 15 / 89 Files in debian/ All the packaging work should be made by modifying ﬁles 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 / 89 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 Wed, 15 Sep 2010 18:13:44 +0200

Debian Packaging Tutorial 17 / 89 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 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 / 89 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 / 89 debian/rules

I Makeﬁle

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 conﬁguration 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 / 89 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_ﬁxperms, dh_perl, dh_makeshlibs, dh_installdeb, dh_shlibdeps, dh_gencontrol, dh_md5sums, dh_builddeb, . . .

I Called from debian/rules I Conﬁgurable using command parameters or ﬁles 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 / 89 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/packagename. $(MAKE) DESTDIR=$(CURDIR)/debian/packagename install

Debian Packaging Tutorial 22 / 89 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 / 89 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 difﬁcult to customize package builds: "twisty maze of makeﬁles 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 / 89 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: dh_auto_configure -- --with-kitchen-sink override_dh_auto_build: make world

Debian Packaging Tutorial 25 / 89 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 dh 60 CDBS

20 Market share (%)

0 2005 2007 2010 2013 2016 Time

Debian Packaging Tutorial 26 / 89 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 / 89 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 ﬁles and a .changes ﬁle I .changes: describes what was built; used to upload the package

Debian Packaging Tutorial 28 / 89 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.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.changes lintian -i: gives more information about the errors lintian -EviIL +pedantic: shows more problems

I Upload the package to Debian (dput) (needs conﬁguration)

I Manage a private Debian archive with reprepro or aptly Documentation: https://wiki.debian.org/HowToSetupADebianRepository

Debian Packaging Tutorial 29 / 89 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 / 89 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 ﬁles 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 / 89 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 / 89 debian/copyright

I Copyright and license information for the source and the packaging I Traditionally written as a text ﬁle 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 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’.

Debian Packaging Tutorial 33 / 89 Modifying the upstream source

Often needed: I Fix bugs or add customizations that are speciﬁc to Debian I Backport ﬁxes from a newer upstream release

Several methods to do it: I Modifying the ﬁles 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 ﬁxes with derivatives I Gives more exposure to the changes http://patch-tracker.debian.org/ (down currently)

Debian Packaging Tutorial 34 / 89 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 https://perl-team.pages.debian.net/howto/quilt.html I Patch-system-agnostic tool in devscripts: edit-patch

Debian Packaging Tutorial 35 / 89 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 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 / 89 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 Developer’s 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 / 89 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 / 89 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-* ﬁelds in debian/control to locate the repository I https://wiki.debian.org/Salsa

Vcs-Browser: https://salsa.debian.org/debian/devscripts Vcs-Git: https://salsa.debian.org/debian/devscripts.git

Vcs-Browser: https://salsa.debian.org/perl-team/modules/packages/libwww-perl Vcs-Git: https://salsa.debian.org/perl-team/modules/packages/libwww-perl.git

I VCS-agnostic interface: debcheckout, debcommit, debrelease I debcheckout grep → checks out the source package from Git

Debian Packaging Tutorial 39 / 89 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 ﬁne on Debian stable I Sometimes trivial (no changes needed) I Sometimes difﬁcult 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 / 89 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 / 89 Debian archive and suites

security team developer

experimental unstable

testing-proposed-updates stable-proposed-updates testing preparation of stable next release stable-new release stable management stable release point release security stable-updates stable backports

package uploads oldstable package migrations between suites archive.d.o development test internal production

Based on graph by Antoine Beaupré. https://salsa.debian.org/debian/package-cycle

Debian Packaging Tutorial 42 / 89 Suites for development

I New versions of packages are uploaded to unstable (sid) I Packages migrate from unstable to testing based on several criterias (e.g. has been in unstable for 10 days, and no regressions) I New packages can also be uploaded to: I experimental (for more experimental packages, such as when the new version is not ready to replace the one currently in unstable) I testing-proposed-updates, to update the version in testing without going through unstable (this is rarely used)

Debian Packaging Tutorial 43 / 89 Freezing and releasing

I At some point during the release cycle, the release team decides to freeze testing: automatic migrations from unstable to testing are stopped, and replaced by manual review

I When the release team considers testing to be ready for release: I The testing suite becomes the new stable suite I Similarly, the old stable becomes oldstable I Unsupported releases are moved to archive.debian.org

I See https://release.debian.org/

Debian Packaging Tutorial 44 / 89 Stable release suites and management

I Several suites are used to provide stable release packages: I stable: the main suite I security updates suite provided on security.debian.org, used by the security team. Updates are announced on the debian-security-announce mailing list I stable-updates: updates that are not security related, but that should urgently be installed (without waiting for the next point release): antivirus databases, timezone-related packages, etc. Announced on the debian-stable-announce mailing list I backports: new upstream versions, based on the version in testing I The stable suite is updated every few months by stable point releases (that include only bug ﬁxes) I Packages targetting the next stable point release are uploaded to stable-proposed-updates and reviewed by the release team

I The oldstable release has the same set of suites

Debian Packaging Tutorial 45 / 89 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 it’s interesting/useful enough, please I Are there alternatives already packaged in Debian?

Debian Packaging Tutorial 46 / 89 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 47 / 89 Adopting a package: example

From: You To: [email protected], [email protected] Cc: Francois Marier 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 48 / 89 Getting your package in Debian

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

2 Prepare a source package

3 Find a Debian Developer that will sponsor your package

I Ofﬁcial 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 49 / 89 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 50 / 89 Where to ﬁnd 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 ﬁt 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 51 / 89 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 Developer’s 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 Speciﬁc policies for Perl, Java, Python, . . . I Ubuntu Packaging Guide http://developer.ubuntu.com/resources/tools/packaging/

Debian Packaging Tutorial 52 / 89 Debian dashboards for maintainers

I Source package centric: https://tracker.debian.org/dpkg

I Maintainer/team centric: Developer’s Packages Overview (DDPO) https://qa.debian.org/developer.php?login= pkg-ruby-extras-maintainers@lists.alioth.debian.org

I TODO-list oriented: Debian Maintainer Dashboard (DMD) https://udd.debian.org/dmd/

Debian Packaging Tutorial 53 / 89 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 54 / 89 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 55 / 89 More interested in Ubuntu?

I Ubuntu mainly manages the divergence with Debian

I No real focus on speciﬁc packages Instead, collaboration with Debian teams

I Usually recommend uploading new packages to Debian ﬁrst 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 Developer’s packages overview I Ubuntu box on the Package Tracking System I Receive launchpad bugmail via the PTS

Debian Packaging Tutorial 56 / 89 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 / 89 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

Feedback: [email protected]

Debian Packaging Tutorial 58 / 89 Legal stuff

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 59 / 89 Contribute to this tutorial

I Contribute: I apt-get source packaging-tutorial I debcheckout packaging-tutorial I git clone https://salsa.debian.org/debian/packaging-tutorial.git I https://salsa.debian.org/debian/packaging-tutorial 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 60 / 89 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 61 / 89 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 ﬁlling debian/control and other ﬁles

3 Enjoy

Debian Packaging Tutorial 62 / 89 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 gnujump_LDFLAGS = $(all_libraries) by gnujump_LDFLAGS = -Wl,--as-needed gnujump_LDADD = $(all_libraries) -lm Then run autoreconf -i

Debian Packaging Tutorial 63 / 89 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 /usr/share/doc/javahelper/tutorial.txt.gz

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

3 Package it

Debian Packaging Tutorial 64 / 89 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 65 / 89 Practical session 5: packaging a Perl module

1 Take a quick look at some documentation about Perl packaging: I https://perl-team.pages.debian.net 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 66 / 89 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 67 / 89 Answers to practical sessions

Debian Packaging Tutorial 68 / 89 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 ﬁles 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 69 / 89 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 70 / 89 Looking around and building the package

2 Look at the ﬁles 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 71 / 89 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 ﬁle. 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 deﬁned 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 72 / 89 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 ﬁnd the ./configure line I Add --disable-perl-regexp I Rebuild with debuild or dpkg-buildpackage -us -uc

Debian Packaging Tutorial 73 / 89 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_ 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 74 / 89 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 ﬁlling debian/control and other ﬁles

3 Enjoy

Debian Packaging Tutorial 75 / 89 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 76 / 89 Step by step. . . (2)

I Look at debian/changelog, debian/rules, debian/control (auto-ﬁlled 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 ﬁnd 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 77 / 89 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:

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 gnujump_LDFLAGS = $(all_libraries) by gnujump_LDFLAGS = -Wl,--as-needed gnujump_LDADD = $(all_libraries) -lm I Then run autoreconf -i

Debian Packaging Tutorial 78 / 89 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 gnujump_LDFLAGS = $(all_libraries) by gnujump_LDFLAGS = -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 79 / 89 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 don’t 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 80 / 89 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 81 / 89 Practical session 3: packaging a Java library

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

3 Package it

Debian Packaging Tutorial 82 / 89 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 ﬁx 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 83 / 89 Practical session 4: packaging a Ruby gem

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 84 / 89 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 gem’s 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 85 / 89 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 ﬁle based on the upstream ﬁles I Build the package I Compare your package with the ruby-peach package in the Debian archive

Debian Packaging Tutorial 86 / 89 Practical session 5: packaging a Perl module

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 87 / 89 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 distribution’s metadata I Named libdistname-perl

Debian Packaging Tutorial 88 / 89 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 89 / 89