Debian packaging howto

How to make a package
Copyright: (c) 2010, Thomas Goirand <zigo@debian.org>, Debian Developer
License: BSD (feel free to reuse this material and do what you want with it, but please keep my name attached)

DEBIAN PACKAGING TUTORIAL
2
Overview of today's talk
● Who I am
● Why do we use packages
● Contributing to Debian: why?
● Components of a package
● Inside the debian/ folder
● Debian rules!
● Dpatch, maintainer scripts
● Debconf
● Share your work: releasing

3
Who am I?
● Founder and CEO of GPLHost
● Involved in hosting since 1999
● Maintaining Debian packages since 2006
● Debian Developer since June 2010
● Maintaining hosting related packages:
http://qa.debian.org/developer.php?login=zigo@debian.org
● WARNING: This talk is NOT authoritative:
– Read the Debian Policy Manual !!!

4
Contributing to Debian: why?
● Best and completely free OS
● Easy to install packaged software
● Dependencies, security, license checked
● Standard checked by others
● Contributions, BTS
● Ubuntu lovers: Debian is your upstream!

5
A package: the basic stuff
● Result: one or more .deb binaries
● Source format 1.0 or 3.0 (“quilt”)
● Source package:
– .dsc
– .orig.tar.gz / .orig.tar.bz2
– .diff.gz / .debian.tar.gz
● A file for uploading: .changes

6
Inside a source package
● Everything is in the debian folder
● Do not touch the upstream files:
– Use dpatch or quilt
● Upstream sources should be:
– shlug_<VERSION>.orig.tar.gz
– Extracted as shlug-<VERSION>
– Repacking a new orig.tar.gz is ok

7
Overview of the debian/ folder
● debian/copyright
● debian/control
● debian/changelog
● debian/rules
● debian/watch
● debian/source/format
● Eventually, others...

8
debian/copyright overview
● Of the importance of freeness: make sure
you check the upstream license
● List absolutely ALL authors and copyright
holders: it's mandatory!
● License in full, except those in
/usr/share/common-licenses (referenced
with a copyright notice)
● Don't trust upstream: check all files!
● The machine readable draft vs free format

9
debian/copyright example
This package was first debianized by Thomas Goirand <zigo@debian.org>
on the: on Fri, 25 Sep 2009 12:02:18 +0100
It was downloaded from: http://www.example.org/example-package/
Upstream authors: Some Guy <some-guy@example.org>
Files: debian/*
Copyright: (c) 2010, Thomas Goirand <zigo@debian.org>
License: LGPL-2.1
<LGPL-2.1 COPYRIGHT NOTICE GOES HERE>
On Debian systems, the complete text of the Lesser General Public
License may be found in: /usr/share/common-licenses/LGPL
Files: *
Copyright: (c) Some Guy <some-guy@example.org>
License: BSD-style
This comes with no warranty, bla bla bla...

10
debian/control example
Source: shlug
Section: mail
Priority: optional
Maintainers: Thomas Goirand <zigo@debian.org>
Build-Depends: debhelper (>= 7), adduser
Build-Depends-Indep: gettext
Standards-Version: 3.9.1
Homepage: http://www.shlug.org/shlug/
Package: shlug-client
Architecture: all
Depends: ${misc:Depends}, curl, gettext
Description: a client for the shlug community
This is a long description
that has to be at least 3 lines
and wrapped for 80 cols.

11
Dependencies in debian/control
● Check what is build-esential
● Depends: Mandatory need
● Pre-Depends: Setup before installing
● Recommends: Automatically pulled
● Suggests: Displayed to the user
● Conflicts: Same file in different deb
● Breaks: Conflicts, but not at file level
● Replaces: Forcing removal of others
● Provides: Virtual package
http://www.debian.org/docs/debian-policy/ch-relationships.html

12
debian/changelog example
shlug (1.5.3-1) unstable; urgency=low
* New upstream release.
* Do not ship COPYING file (Closes: #789012).
-- Thomas Goirand <zigo@debian.org> Sun, 26 Sep 2010 20:17:07 +0800
shlug (1.2.3-1) unstable; urgency=low
* Initial package (Closes: #123456).
-- Thomas Goirand <zigo@debian.org> Sun, 5 Sep 2004 05:29:57 +0000
● Dont edit by hand: use devscripts
– debchange --create
– debchange -i

13
debian/watch example
Version=3
Http://www.shlug.org/shlug/ shlug-client-(d).tar.gz
● Many examples in man uscan
● Check with: uscan --verbose –report
● Do not be too specific in your regexp

14
Debian RULES
● It's a Makefile: #!/usr/bin/make -f
● No requirement to use any (deb)helper
● dh_helpers vs CDBS as helpers
● 6 mandatory targets:
– Build:, install:, binary-indep:,
binary-arch:, binary:, clean:
● Goal: install everything in:
– $(CURDIR)/debian/shlug

15
debian/rules in details 1/3
#!/usr/bin/make -f
DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE)
DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE)
configure: configure-stamp
configure-stamp:
./configure --prefix=/usr
--build=$(DEB_HOST_GNU_TYPE --host=$(DEB_HOST_GNU_TYPE)
[ other options … ]
touch $@
build: build-stamp
build-stamp: configure-stamp
dh_testdir
$(MAKE)
touch $@
clean:
dh_testdir
dh_testroot
dh_clean
$(MAKE) clean
rm -f configure-stamp build-stamp

16
install: build
dh_testdir
dh_testroot
dh_prep
$(MAKE) DESTDIR=$(CURDIR)/debian/shlug install
mkdir -p $(CURDIR)/debian/shlug/usr/bin
mv $(CURDIR)/debian/shlug/usr/local/bin/*
$(CURDIR)/debian/shlug/usr/bin
binary-indep:
dh_testdir
dh_testroot
dh_installchangelogs
dh_installdeb
dh_gencontrol
dh_md5sums
dh_builddeb

17
binary-arch: build install
dh_testdir
dh_testroot
dh_installchangelogs doc/changelogs
dh_installdocs debian/README.Debian
dh_fixperms
dh_shlibdeps
dh_gencontrol
dh_md5sums
dh_builddeb
binary: binary-indep binary-arch
.PHONY: build install binary binary-arch binary-indep

18
Patch system: dpatch 1/2
● Set Depends: dpatch
● Add in your debian/rules:
– include /usr/share/dpatch/dpatch.make
– patch-stamp:
– configure-stamp: patch-stamp
– clean: unpatch
● Everything else is automated
● Manually: dpatch apply-all / deapply-all

19
Patch system: dpatch 2/2
● Put dpatch files in debian/patches
● List patch files in debian/patches/00list
● dpatch header example:
#!/bin/sh /usr/share/dpatch/dpatch-run
## 02_install_path.dpatch by Thomas Goirand <zigo@debian.org>
## DP: Upstream installs in /usr/local/bin, this patch fixes it
@DPATCH@
diff -u shlug-1.2.3.orig shlug-1.2.3
--- shlug-1.2.3.orig/Makefile
--- shlug-1.2.3/Makefile

20
Maintainer scripts
● postinst / preinst / prerm / postrm
● postinst example:
#!/bin/sh
set -e
if ! getent passwd shlug >/dev/null ; then
useradd -m -s /bin/false -g nogroup shlug -r -b /var/lib
fi
touch /var/log/shlug.log
chown shlug.shlug /var/log/shlug.log
#DEBHELPER#
exit 0

21
Other dh_* scripts
● dh_install and debian/install
● dh_installmanpages debian/manpages
● dh_installdocs debian/docs
● dh_link and debian/links
● dh_installinit debian/init
● Many, many more...

22
Debconf 1/5
● A standardized API for configuring debs
● Many back-ends (wiptail, X-Window, etc.)
● Has default values and levels of verbosity
● Understand translations (gettext po files)
● Warning:
– can run in non-interactive mode
– shouldn't overwrite config file values
– Do not abuse it

23
Debconf 2/5
● Build-Depends: po-debconf
● Depends: debconf
● In your debian/rules:
Clean:
dh_testdir
dh_testroot
. . .
debconf-updatepodebconf-updatepo

24
Debconf 3/5
● debian/shlug.template example:
# These templates have been reviewed by the debian-i10n-english
# team
#
# If modifications/additions/rewording are needed, please ask
# for advice to debian-i10n-english@lists.debian.org
Template: shlug/max_user
Type: string
Default: 100
Description: Shlug max user
The shlug proccess N messages at once. If this number is bigger,
shlug will process messages faster, but also will use more
memory: approximately 1MB per user.

25
Debconf 4/5
● debian/shlug.config example:
#!/bin/sh
set -e
. /usr/share/debconf/confmodule
if [ -f /etc/shlug/shlug.conf ] ; then
. /etc/shlug/shlug.conf
fi
if [ ! -z ${shl_max_user} ] ; then
db_set shlug/shl_max_user ${shl_max_user}
fi
db_input high shlug/shl_max_user || true
db_go
#DEBHELPER#
exit 0

26
Debconf 5/5
● debian/shlug.postinst example:
#!/bin/sh
set -e
. /usr/share/debconf/confmodule
db_version 2.0
db_get shlug/shlug_my_config
new_shlug_config=$RET
echo “# Enter your config value here:
shl_max_user=${new_shlug_config}” >/etc/shlug/shlug.conf
#DEBHELPER#
exit 0

27
More to learn, not in these slides
● Debconf package configuration
● Init script building
● Menu items
● db-config-common
● Language specifics (python, php, perl...)
● Web apps
● ...

28
Before building
● Check your env:
– export DEBFULLNAME="Thomas Goirand"
– export DEBEMAIL="zigo@debian.org"
– export EDITOR=vim
● Check that your GPG key is ok
– gpg --list-keys

29
Building and checking
● You HAVE to build in SID
● dpkg-buildpackage
● lintian -Ii shlug_1.2.3-2_amd64.changes
● Install it on your own system and check
● Building in a chroot for checking depends,
build-depends and build-depends-indep

30
Bonus: use Git
● Multiple branches:
– debian-sid
– upstream-sid
– …
● Build with:
git-buildpackage --git-upstream-branch=upstream-sid
--git-debian-branch=debian-sid

31
Your package in debian main!
● Only DD can upload
● Anyone can maintain packages!
● Have your gpg key signed
● New binary packages goes in NEW queue
for checking by ftp-masters
● Find sponsors:
– mentors.debian.net
– Ask me!!!

32
Sponsoree tips
● Make sure your package is lintian clean
● Really do what your sponsor advices you:
– Carefully change what has been advised
– Do not fear to ask: 4 days limit in -mentors
● pbuilder / sbuilder / virtual machines /
puiparts
● Don't use dh_make ! (only my opinion...)
● Look at other packages as example

33
Maintainership never ends
● Don't package and forget: brings hate
● You will be responsible for YEARS
● BTS (bug tracking system)
● Relation with upstream author
● Fixing bugs is better than packaging new

34
Working with others: Alioth
● alioth.debian.org
● collab-maint
● pkg-* groups, lists, and git.debian.org
● Use the BTS, reportbug and reporbug-ng

35
Becoming DD / DM
● Maintaining packages
● DM is often the first step
● Understand the DFSG / Social contract
● Patience (months, maybe years)
● Somebody vouching for you
● Pass the DAM(ned) tests

36
Resources on the net
● Absolutely everything is on *.debian.org
● Debian New Maintainer Guide
● Debian Policy Manual
● Debian Developer Reference
● Specific policies and drafts
● irc.debian.org: #mentors
● debian-mentors@lists.debian.org

37
More?
Q&A

Debian packaging howto

More Related Content

What's hot

Viewers also liked

Similar to Debian packaging howto

Debian packaging howto