change title, add 'interact with the community'
[packaging-tutorial.git] / packaging-tutorial.tex
1 \documentclass[10pt,final]{beamer}
2 \mode<presentation>
3 \usetheme{lucasdeb}
4 \usepackage{debiantutorial}
5
6 \hypersetup{pdftitle={Debian Packaging Tutorial},bookmarks}
7 \title{Debian Packaging Tutorial}
8 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
9 \institute{\includegraphics[viewport=274 335 360 440,width=1cm]{figs/openlogo-nd.pdf}}
10 \date{}
11
12 \begin{document}
13
14 \frame{\titlepage}
15
16 \begin{frame}{About this tutorial}
17   \begin{itemize}
18   \item Goal: \textbf{tell you what you really need to know about Debian packaging}
19     \begin{itemize}
20       \hbr
21     \item Modify existing packages
22       \hbr
23     \item Create your own packages
24             \hbr
25     \item Interact with the Debian community
26       \hbr
27     \item Become a Debian power-user
28     \end{itemize}
29     \br
30   \item Covers the most important points, but is not complete
31     \begin{itemize}
32     \item You will need to read more documentation
33     \end{itemize}
34     \br
35   \item Most of the content also applies to Debian derivatives distributions
36     \begin{itemize}
37       \hbr
38     \item That includes Ubuntu
39     \end{itemize}
40   \end{itemize}
41 \end{frame}
42
43 \begin{frame}{Outline}
44   \tableofcontents[hideallsubsections]
45 \end{frame}
46
47 \section{Introduction}
48
49 \subsection{Debian}
50
51 \begin{frame}{Debian}
52         \begin{itemize}
53                 \item \textbf{GNU/Linux distribution}
54                         \br
55                 \item 1st major distro developed "openly in the spirit of GNU"
56                         \br
57                 \item \textbf{Non-commercial}, built collaboratively by more than 1000 volunteers
58                         \br
59                 \item 30000 binary packages ; 12 ports (inc. 2 non-Linux) ; 120 derivatives
60                         \br
61                 \item 3 main features:
62                         \begin{itemize}
63                                 \item \textbf{Quality} -- culture of technical excellence\\
64                                         {\small\sl We release when it's ready}
65                                         \hbr
66                                 \item \textbf{Freedom} -- devs and users bound by the \textsl{Social Contract}\\
67                                         Promoting the culture of Free Software since 1993
68                                         \hbr
69                                 \item \textbf{Independence} -- no (single) company babysitting Debian\\
70                                         And open decision-making process (\textsl{do-ocracy} + \textsl{democracy})
71                         \end{itemize}
72         \end{itemize}
73 \end{frame}
74
75
76
77 \subsection{The Deb package format}
78
79 \begin{frame}[fragile]{The Deb package format}
80   \begin{itemize}
81   \item One of the two most common packages format (with RPM)
82   \item A very powerful and convenient way to distribute software to users
83   \item \texttt{.deb} file: an \texttt{ar} archive
84     \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
85 $ ar tv wget_1.12-2.1_i386.deb
86 rw-r--r-- 0/0      4 Sep  5 15:43 2010 debian-binary
87 rw-r--r-- 0/0   2403 Sep  5 15:43 2010 control.tar.gz
88 rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
89     \end{lstlisting} % $
90     \begin{itemize}
91     \item \texttt{debian-binary}: version of the deb file format, \texttt{"2.0\textbackslash{}n"}
92     \item \texttt{control.tar.gz}: metadata about the package\\
93       {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
94     \item \texttt{data.tar.gz}: data files of the package
95     \end{itemize}
96   \item You could create your \texttt{.deb} files manually\\
97     {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
98   \item But most people don't do it that way
99   \end{itemize}
100   \hbr
101   \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
102 \end{frame}
103
104 \subsection{Tools you will need}
105 \begin{frame}{Tools you will need}
106   \begin{itemize}
107   \item A Debian (or Ubuntu) system (with root access)
108     \br
109   \item Some packages:
110     \begin{itemize}
111     \item \textbf{build-essential}: has dependencies on the packages that will
112       be assumed to be available on the developers' machine (no need to specify
113       them in the \texttt{Build-Depends:} control field of your package)
114       \begin{itemize}
115       \item includes a dependency on \textbf{dpkg-dev}, which contains basic
116         Debian-specific tools to create packages
117       \end{itemize}
118       \hbr
119     \item \textbf{devscripts}: contains many useful scripts for Debian
120       maintainers
121     \end{itemize}
122   \end{itemize}
123
124   \br
125   Many other tools will also be mentioned later, such as \textbf{debhelper},
126   \textbf{cdbs}, \textbf{quilt}, \textbf{pbuilder}, \textbf{sbuild},
127   \textbf{lintian}, \textbf{svn-buildpackage}, \textbf{git-buildpackage},
128   \ldots\\
129   Install them when you need them.
130 \end{frame}
131
132 \subsection{General packaging workflow}
133 \begin{frame}{General packaging workflow}
134   \begin{center}
135     \begin{tikzpicture}[
136       node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
137       arr/.style={very thick}, command/.style={text=rouge,font=\ttfamily}, ]
138       
139       \node[node1] (www) at (0, 0) {Web};
140       \node[node1] (us) at (2.5, 0) {upstream source};
141       \node[node1] (da) at (-2.5, 0) {Debian mirror};
142       \node[node1] (sp) at (0, -2) {source package};
143       \draw[arr,<-,dashed,thick] (sp) -- (2.5,-2) node[right=0cm,text width=2.98cm,text centered,font=\small\sl] {where most of the manual work is done};
144       \node[node1] (bin) at (0, -4) {one or several binary packages};
145       \draw[arr,<-,dashed,thick] (bin) -- (3.5,-4) node[right,text centered,font=\small\ttfamily\sl] {.deb\normalfont};
146       \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
147       \draw[arr,->] (da) -- (sp) node[pos=0.5,left,command] {apt-get source};
148       \draw[arr,->] (www) -- (sp) node[pos=0.5,left,command] {dget};
149       \draw[arr,->] (sp) -- (bin) node[pos=0.5,right,text width=6cm] {\textttc{debuild} (build and test with \textttc{lintian}) or \textttc{dpkg-buildpackage}};
150       \draw[arr,->] (bin) -- (1,-6) node[pos=0.5,right] {install (\textttc{debi})};
151       % \draw[arr,->] (bin) -- (-1,-6) node[pos=0.5,left] {upload (\textttc{dput})};
152       \draw[transparent] (bin) -- (-1,-6) node[pos=0.5,left,opaque] {upload (\textttc{dput})};
153       \draw[arr,->,rounded corners] (bin) -- (-1,-6) -- (-4.5,-6) -- (-4.5,0) -- (da);
154       \useasboundingbox (-4,-6) rectangle (6,0); % hack hack hack
155     \end{tikzpicture}
156   \end{center}
157 \end{frame}
158
159 \section{Creating source packages}
160 \subsection{Source packages basics}
161 \begin{frame}{Source package}
162   \begin{itemize}
163   \item One source package can generate several binary packages\\
164     {\small e.g the \texttt{\bfseries libtar} source generates the
165       \texttt{\bfseries libtar} and \texttt{\bfseries libtar-dev} binary
166       packages} \hbr
167   \item Two kinds of packages: (if unsure, use non-native)
168     \begin{itemize}
169       \small
170     \item Native packages: software developed inside Debian (\textsl{dpkg}, \textsl{apt})
171     \item Non-native packages: software developed outside Debian
172     \end{itemize}
173     \hbr
174   \item Main file: \texttt{.dsc} (meta-data)
175     \hbr
176   \item Other files depending on the version of the source format
177     \begin{itemize}
178     \item 1.0 -- native: \texttt{package\_version.tar.gz}
179       \hbr
180     \item 1.0 -- non-native:
181       \begin{itemize}
182       \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
183       \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
184       \end{itemize}
185       \hbr
186     \item 3.0 (quilt):
187       \begin{itemize}
188       \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
189       \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
190       \end{itemize}
191     \end{itemize}
192   \end{itemize}
193   \br
194   (See \texttt{dpkg-source(1)} for exact details)
195 \end{frame}
196
197 \begin{frame}[fragile]{Source package example (wget\_1.12-2.1.dsc)}
198   \begin{lstlisting}[basicstyle=\ttfamily\small]
199 Format: 3.0 (quilt)
200 Source: wget
201 Binary: wget
202 Architecture: any
203 Version: 1.12-2.1
204 Maintainer: Noel Kothe <noel@debian.org>
205 Homepage: http://www.gnu.org/software/wget/
206 Standards-Version: 3.8.4
207 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
208  libssl-dev (>= 0.9.8), dpatch, info2man
209 Checksums-Sha1: 
210  50d4ed2441e67[..]1ee0e94248 2464747 wget_1.12.orig.tar.gz
211  d4c1c8bbe431d[..]dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
212 Checksums-Sha256: 
213  7578ed0974e12[..]dcba65b572 2464747 wget_1.12.orig.tar.gz
214  1e9b0c4c00eae[..]89c402ad78 48308 wget_1.12-2.1.debian.tar.gz
215 Files: 
216  141461b9c04e4[..]9d1f2abf83 2464747 wget_1.12.orig.tar.gz
217  e93123c934e3c[..]2f380278c2 48308 wget_1.12-2.1.debian.tar.gz
218 \end{lstlisting}
219 \end{frame}
220
221 \subsection{Retrieving source packages}
222 \begin{frame}{Retrieving an existing source package}
223   \begin{itemize}
224   \item From the Debian archive:
225     \begin{itemize}
226     \item \texttt{apt-get source \textsl{package}}
227     \item \texttt{apt-get source \textsl{package=version}}
228     \item \texttt{apt-get source \textsl{package/release}}
229     \end{itemize}
230     (You need \texttt{deb-src} lines in \texttt{sources.list})
231     \br
232   \item From the Internet:
233     \begin{itemize}
234     \item \texttt{dget \textsl{url-to.dsc}}
235     \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\
236         wget\_1.4.4-6.dsc}\\ 
237       (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
238     \end{itemize}
239     \br
240   \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
241   \end{itemize}
242 \end{frame}
243
244 \subsection{Creating a basic source package}
245 \begin{frame}{Creating a basic source package}
246   \begin{itemize}
247   \item Download the upstream source\\
248     (\textsl{upstream source} = the one from the software's original developers)
249     \hbr
250   \item Rename to \texttt{<\textsl{source\_package}>\_<\textsl{upstream\_version}>.orig.tar.gz}\\
251     (example: \texttt{simgrid\_3.6.orig.tar.gz})
252     \hbr
253   \item Untar it
254     \hbr
255   \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
256     \hbr
257   \item There are some alternatives to \texttt{dh\_make} for specific sets of
258     packages: \textbf{dh-make-perl}, \textbf{dh-make-php}, \ldots \hbr
259   \item \texttt{debian/} directory created, with a lot of files in it
260   \end{itemize}
261 \end{frame}
262
263 \subsection{Files in debian/}
264 \begin{frame}{Files in debian/}
265   All the packaging work should be made by modifying files in \texttt{debian/}
266   \hbr
267   \begin{itemize}
268   \item Main files:
269     \begin{itemize}
270     \item \textbf{changelog} -- history of the Debian package
271     \item \textbf{copyright} -- copyright information for the package
272     \item \textbf{control} -- meta-data about the package (dependencies, etc)
273     \item \textbf{rules} -- specifies how to build the package
274     \end{itemize}
275     \hbr
276   \item Optional files:
277     \begin{itemize}
278     \item compat
279     \item watch
280     \item dh\_install* targets\\
281       {\small *.dirs, *.docs, *.manpages, \ldots}
282     \item maintainer scripts\\
283       {\small *.postinst, *.prerm, \ldots}
284     \item source/format
285     \item patches -- if you need to modify the upstream sources
286     \end{itemize}
287     \hbr
288   \item Most of the files use a format based on RFC 822 (mail headers)
289   \end{itemize}
290 \end{frame}
291
292 \begin{frame}[fragile]{debian/changelog}
293   \begin{itemize}
294   \item Lists the Debian packaging changes
295   \item Edited manually or with \texttt{dch}
296   \item Special format to automatically close Debian or Ubuntu bugs\\
297     Debian: \texttt{Closes:~\#595268} ; Ubuntu: \texttt{LP:~\#616929}
298   \item Installed as \texttt{/usr/share/doc/\textit{package}/changelog.Debian.gz}
299   \end{itemize}
300   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
301 mpich2 (1.2.1.1-5) unstable; urgency=low
302
303   * Use /usr/bin/python instead of /usr/bin/python2.5. Allow
304     to drop dependency on python2.5.  Closes: #595268
305   * Make /usr/bin/mpdroot setuid. This is the default after
306     the installation of mpich2 from source, too. LP: #616929
307     + Add corresponding lintian override.
308
309  -- Lucas Nussbaum <lucas@debian.org>  Wed, 15 Sep 2010 18:13:44 +0200
310 \end{lstlisting}
311 \end{frame}
312
313 \begin{frame}[fragile]{debian/copyright}
314   \hbr
315   \begin{itemize}
316   \item Copyright and license information for the source and the packaging
317   \item Traditionally written as a text file
318   \item New machine-readable format: \url{http://dep.debian.net/deps/dep5/}
319   \end{itemize}
320   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
321 Format: <VERSIONED_FORMAT_URL>
322 Upstream-Name: X Solitaire
323 Source: ftp://ftp.example.com/pub/games
324
325 Files: *
326 Copyright: Copyright 1998 John Doe <jdoe@example.com>
327 License: GPL-2+
328  This program is free software; you can redistribute it
329  [...]
330  .
331  On Debian systems, the full text of the GNU General Public
332  License version 2 can be found in the file
333  `/usr/share/common-licenses/GPL-2'.
334
335 Files: debian/*
336 Copyright: Copyright 1998 Jane Smith <jsmith@example.net>
337 License:
338  [LICENSE TEXT]
339 \end{lstlisting}
340 \end{frame}
341
342 \begin{frame}[fragile]{debian/control}
343   \hbr
344   \begin{itemize}
345   \item Package metadata
346     \begin{itemize}
347     \item For the source package itself
348     \item For each binary package built from this source
349     \end{itemize}
350     \hbr
351   \item Package name, section, priority, maintainer, uploaders,
352     build-dependencies, dependencies, description, homepage, \ldots \hbr
353   \item Documentation: Debian Policy chapter 5\\
354     \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
355   \end{itemize}
356 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
357 Source: wget
358 Section: web
359 Priority: important
360 Maintainer: Noel Kothe <noel@debian.org>
361 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
362  libssl-dev (>= 0.9.8), dpatch, info2man
363 Standards-Version: 3.8.4
364 Homepage: http://www.gnu.org/software/wget/
365
366 Package: wget
367 Architecture: any
368 Depends: ${shlibs:Depends}, ${misc:Depends}
369 Description: retrieves files from the web
370  Wget is a network utility to retrieve files from the Web
371 \end{lstlisting}
372 \end{frame}
373
374 \begin{frame}{Architecture: all or any}
375   Two kinds of binary packages:
376   \hbr
377   \begin{itemize}
378   \item Packages with a different content on each Debian architecture
379     \begin{itemize}
380     \item Example: C program
381     \item \texttt{Architecture:\ any} in \texttt{debian/control}
382       \begin{itemize}
383       \item Or, if it only works on a subset of architectures:\\
384         \texttt{Architecture:\ amd64 i386 ia64 hurd-i386}
385       \end{itemize}
386     \item Packages for other architectures built by the Debian infrastructure
387     \item Named \texttt{\textsl{package}\_\textsl{version}\_\textsl{architecture}.deb}
388     \end{itemize}
389     \br
390   \item Packages with the same content on all architectures
391     \begin{itemize}
392     \item Example: Perl library
393     \item \texttt{Architecture:\ all} in \texttt{debian/control}
394     \item Named \texttt{\textsl{package}\_\textsl{version}\_\textbf{all}.deb}
395     \end{itemize}
396   \end{itemize}
397 \end{frame}
398
399 \begin{frame}[fragile]{debian/rules}
400   \hbr
401   \begin{itemize}
402   \item Makefile
403     \br
404   \item Interface used to build Debian packages
405     \br
406   \item Documented in Debian Policy, chapter 4.8\\
407     {\small \texttt{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
408     \br
409   \item Five required targets:
410     \begin{itemize}
411     \item \texttt{build}: should perform all the configuration and compilation
412       \hbr
413     \item \texttt{binary, binary-arch, binary-indep}: build the binary packages
414       \begin{itemize}
415       \item \texttt{dpkg-buildpackage} will call \texttt{binary} to build all
416         the packages, or \texttt{binary-arch} to build only the
417         \texttt{Architecture:~any} packages
418       \end{itemize}
419       \hbr
420     \item \texttt{clean}: clean up the source directory
421     \end{itemize}
422   \end{itemize}
423 \end{frame}
424
425 \subsection{Packaging helpers}
426 \begin{frame}{Packaging helpers -- debhelper}
427   \begin{itemize}
428   \item You could write shell code in \texttt{debian/rules} directly
429     \begin{itemize}
430     \item See the \texttt{adduser} package for example
431     \end{itemize}
432     \hbr
433   \item Better practice (used by most packages): use a \textsl{Packaging helper}
434     \hbr
435   \item Most popular one: \textbf{debhelper} (used by 98\% of packages)
436     \hbr
437   \item Goals:
438     \begin{itemize}
439     \item Factor the common tasks in standard tools used by all packages
440     \item Fix some packaging bugs once for all packages
441     \end{itemize}
442     {\footnotesize dh\_installdirs, dh\_installchangelogs, dh\_installdocs,
443       dh\_installexamples, dh\_install, dh\_installdebconf, dh\_installinit,
444       dh\_link, dh\_strip, dh\_compress, dh\_fixperms, dh\_perl,
445       dh\_makeshlibs, dh\_installdeb, dh\_shlibdeps, dh\_gencontrol,
446       dh\_md5sums, dh\_builddeb, \ldots}
447     \begin{itemize}
448     \item Called from \texttt{debian/rules}
449     \item Configurable using command parameters or files in \texttt{debian/}
450     \end{itemize}
451     {\footnotesize \ttfamily dirs, package.docs, package.examples,
452       package.install, package.manpages, \ldots} \hbr
453   \item Third-party helpers for sets of packages: \textbf{python-support},
454     \textbf{dh\_ocaml}, \ldots \hbr
455   \item Gotcha: \texttt{debian/compat}: Debhelper compatibility version (use "7")
456   \end{itemize}
457 \end{frame}
458
459 \begin{frame}[fragile]{debian/rules using debhelper (1/2)}
460   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
461 #!/usr/bin/make -f
462
463 # Uncomment this to turn on verbose mode.
464 #export DH_VERBOSE=1
465
466 build: 
467         $(MAKE)
468         #docbook-to-man debian/packagename.sgml > packagename.1
469
470 clean: 
471         dh_testdir
472         dh_testroot
473         rm -f build-stamp configure-stamp
474         $(MAKE) clean
475         dh_clean 
476
477 install: build
478         dh_testdir
479         dh_testroot
480         dh_clean -k 
481         dh_installdirs
482         # Add here commands to install the package into debian/packagename.
483         $(MAKE) DESTDIR=$(CURDIR)/debian/packagename install
484 \end{lstlisting}
485 \end{frame}
486
487 \begin{frame}[fragile]{debian/rules using debhelper (2/2)}
488   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
489
490 # Build architecture-independent files here.
491 binary-indep: build install
492
493 # Build architecture-dependent files here.
494 binary-arch: build install
495         dh_testdir
496         dh_testroot
497         dh_installchangelogs 
498         dh_installdocs
499         dh_installexamples
500 #       dh_install
501         dh_installman
502         dh_link
503         dh_strip
504         dh_compress
505         dh_fixperms
506         dh_installdeb
507         dh_shlibdeps
508         dh_gencontrol
509         dh_md5sums
510         dh_builddeb
511
512 binary: binary-indep binary-arch
513 .PHONY: build clean binary-indep binary-arch binary install configure
514 \end{lstlisting}
515 \end{frame}
516
517 \begin{frame}[fragile]{CDBS}
518   \hbr
519   \begin{itemize}
520   \item Still a lot of redundancy between packages
521     \hbr
522   \item Second-level helpers that factor common funtionality
523     \begin{itemize}
524     \item Building with \texttt{./configure \&\& make \&\& make install} or CMake
525     \item Support for Perl, Python, Ruby, GNOME, KDE, Java, Haskell, \ldots
526     \end{itemize}
527     \hbr
528   \item CDBS:
529     \begin{itemize}
530     \item Introduced in 2005, based on advanced \textsl{GNU make} magic
531     \item Documentation: \texttt{/usr/share/doc/cdbs/}
532     \item But some people hate it:
533       \begin{itemize}
534       \item Sometimes difficult to customize package builds:\\
535         "\textsl{twisty maze of makefiles, environment vars and black magic}"
536       \item Slower than plain debhelper (many useless calls to \texttt{dh\_*})
537       \end{itemize}
538       \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
539 #!/usr/bin/make -f
540 include /usr/share/cdbs/1/rules/debhelper.mk
541 include /usr/share/cdbs/1/class/autotools.mk
542
543 # add an action after the build
544 build/mypackage::
545     /bin/bash debian/scripts/foo.sh
546       \end{lstlisting}
547     \end{itemize}
548   \end{itemize}
549 \end{frame}
550
551 \begin{frame}[fragile]{Dh (aka Debhelper 7, or dh7)}
552   \begin{itemize}
553   \item Introduced in 2008 as a \textsl{CDBS killer}
554     \hbr
555   \item \textbf{dh} command that calls \texttt{dh\_*}
556     \hbr
557   \item Simple \textsl{debian/rules}, listing only overrides
558     \hbr
559   \item Easier to customize than CDBS
560     \hbr
561   \item Doc: manpages (\texttt{debhelper(7)}, \texttt{dh(1)}) + slides from DebConf'9 talk\\
562     \url{http://kitenet.net/~joey/talks/debhelper/debhelper-slides.pdf}
563     \br
564     \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
565 #!/usr/bin/make -f
566 %:
567     dh $@
568
569 override_dh_auto_configure:
570      dh_auto_configure -- --with-kitchen-sink
571
572 override_dh_auto_build:
573      make world
574
575     \end{lstlisting}
576   \end{itemize} %$
577 \end{frame}
578
579 \begin{frame}{Classic debhelper vs CDBS vs dh}
580   \hbr
581   \begin{itemize}
582   \item Market shares: (feb'11)\\
583     Classic debhelper: 45\% \hskip 1em CDBS: 24\% \hskip 1em  dh: 29\%
584     \hbr
585   \item Which one should I learn?
586     \begin{itemize}
587     \item Probably all of them
588     \item You need to know debhelper to use dh and CDBS
589     \item You might have to modify CDBS packages
590     \end{itemize}
591     \hbr
592   \item Which one should I use for a new package?
593     \begin{itemize}
594     \item \textbf{dh} (only solution with an increasing market share)
595     \end{itemize}
596   \end{itemize}
597   
598   \hbr
599   \begin{center}
600     \begin{tikzpicture}
601 \begin{axis}[small,label style={font=\footnotesize},xlabel={\small Time},ylabel={\small Market share (\%)},
602         date coordinates in=x,height=4.85cm,width=9cm,xticklabel={\month/\year},
603              legend style={font=\footnotesize,at={(1.02,1)},anchor=north west},max space between ticks=82,try min ticks=5,ymin=0]
604         \addplot[mark=none,blue,thick] table[x=date,y=dh] {cdbs-dh7.txt};
605         \addplot[mark=none,red,thick] table[x=date,y=dh7] {cdbs-dh7.txt};
606         \addplot[mark=none,green,thick] table[x=date,y=cdbs] {cdbs-dh7.txt};
607         \legend{debhelper, dh, CDBS}
608 \end{axis}
609 \end{tikzpicture}
610 \end{center}
611
612 \end{frame}
613
614 \section{Building and testing packages}
615 \subsection{Building packages}
616 \begin{frame}{Building packages}
617   \begin{itemize}
618   \item \textttc{apt-get build-dep mypackage}\\
619     Installs the \textsl{build-dependencies} (for a package in the archive)
620     
621     \br
622   \item \textttc{debuild}: build, test with \texttt{lintian}, sign with GPG
623     \br
624   \item Also possible to call \textttc{dpkg-buildpackage} directly
625     \begin{itemize}
626     \item Usually with \texttt{dpkg-buildpackage -us -uc}
627     \end{itemize}
628     \br
629   \item It is better to build packages in a clean \& minimal environment
630     \begin{itemize}
631     \item \textttc{pbuilder} -- helper to build packages in a \textsl{chroot}\\
632       Good documentation: \url{https://wiki.ubuntu.com/PbuilderHowto}
633       \hbr
634     \item \textttc{schroot} and \textttc{sbuild}: used on the Debian build daemons\\
635       (not as easy to use as \texttt{pbuilder})
636     \end{itemize}
637     \br
638   \item Generate \texttt{.deb} files and a \texttt{.changes} file
639     \begin{itemize}
640     \item \texttt{.changes}: describes what was built ; used to upload the package
641     \end{itemize}
642   \end{itemize}
643 \end{frame}
644 \subsection{Installing and testing packages}
645 \begin{frame}{Installing and testing packages}
646   \begin{itemize}
647   \item Install the package locally: \textttc{debi} (will use \texttt{.changes}
648     to know what to install) \br
649   \item List the content of the package: \texttt{{\color{rouge}debc}
650       ../mypackage<TAB>.changes} \br
651   \item Compare the package with a previous version:\\
652     \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.changes ../mypackage\_2\_*.changes}\\
653     or to compare the sources:\\
654     \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.dsc ../mypackage\_2\_*.dsc}\\
655     \br
656   \item Check the package with \texttt{lintian} (static analyzer):\\
657     \texttt{{\color{rouge}lintian} ../mypackage<TAB>.changes}\\
658     \texttt{lintian -i}: gives more information about the errors \br
659   \item Upload the package to Debian (\textttc{dput}) (needs configuration) \br
660   \item Manage a private Debian archive with \textttc{reprepro}\\
661     Documentation: \url{http://mirrorer.alioth.debian.org/}
662   \end{itemize}
663 \end{frame}
664 \section{Practical session 1: modifying the grep package}
665 \begin{frame}{Practical session 1: modifying the grep package}
666   \begin{enumerate}
667   \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
668     download version 2.6.3-3 of the package
669   \item Look at the files in \texttt{debian/}.
670     \begin{itemize}
671     \item               How many binary packages are generated by this source package?
672     \item               Which packaging helper does this package use?
673     \end{itemize}
674   \item Build the package
675   \item We are now going to modify the package. Add a changelog entry and increase the version number.
676   \item Now disable perl-regexp support (it is a \texttt{./configure} option)
677   \item Rebuild the package
678   \item Compare the original and the new package with debdiff
679   \item Install the newly built package
680   \item Cry if you messed up ;)
681   \end{enumerate}
682 \end{frame}
683
684 \section{Advanced packaging topics}
685 \subsection{Modifying the upstream source}
686 \begin{frame}{Modifying the upstream source}
687   Often needed:
688   \begin{itemize}
689   \item Fix bugs or add customizations that are specific to Debian
690     \hbr
691   \item Backport fixes from a newer upstream release
692   \end{itemize}
693   \br
694   Several methods to do it:
695   \begin{itemize}
696   \item Modifying the files directly
697     \begin{itemize}
698     \item Simple
699     \item But no way to track and document the changes
700     \end{itemize}
701     \hbr
702   \item Using patch systems
703     \begin{itemize}
704     \item Eases contributing your changes to upstream
705     \item Helps sharing the fixes with derivatives
706     \item Gives more exposure to the changes\\
707       \url{http://patch-tracker.debian.org/}
708     \end{itemize}
709   \end{itemize}
710 \end{frame}
711
712 \begin{frame}{Patch systems}
713   \begin{itemize}
714   \item Principle: changes are stored as patches in \texttt{debian/patches/}
715     \hbr
716   \item Applied and unapplied during build
717     \hbr
718   \item Several implementations: \textsl{simple-patchsys} (\textsl{cdbs} only),
719     \textsl{dpatch}, \textbf{\textsl{quilt}} \hbr
720   \item Each supports two \texttt{debian/rules} targets:
721     \begin{itemize}
722     \item \texttt{debian/rules patch}: apply all patches
723     \item \texttt{debian/rules unpatch}: de-apply all patches
724     \end{itemize}
725     \hbr
726   \item More documentation: \url{http://wiki.debian.org/debian/patches}
727   \end{itemize}
728   \br
729   Future: new source package format with built-in patch system: \textbf{3.0 (quilt)}
730   \begin{itemize}
731   \item Recommended solution
732   \item You need to learn \textsl{quilt}\\
733     \url{http://pkg-perl.alioth.debian.org/howto/quilt.html}
734     
735   \end{itemize}
736 \end{frame}
737
738 \begin{frame}[fragile]{Documentation of patches}
739   \begin{itemize}
740   \item Standard headers
741     \hbr
742   \item Documented in DEP3 - Patch Tagging Guidelines\\
743     \url{http://dep.debian.net/deps/dep3/}
744   \end{itemize}
745   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
746 Description: Fix widget frobnication speeds
747  Frobnicating widgets too quickly tended to cause explosions.
748 Forwarded: http://lists.example.com/2010/03/1234.html
749 Author: John Doe <johndoe-guest@users.alioth.debian.org>
750 Applied-Upstream: 1.2, http://bzr.foo.com/frobnicator/revision/123
751 Last-Update: 2010-03-29
752 \end{lstlisting}
753 \end{frame}
754
755 \subsection{Doing things during installation and removal}
756 \begin{frame}{Doing things during installation and removal}
757   \begin{itemize}
758   \item Decompressing the package is sometimes not enough
759     \hbr
760   \item Create/remove system users, start/stop services, manage \textsl{alternatives}
761     \hbr
762   \item Done in \textsl{maintainer scripts}\\
763     \texttt{preinst, postinst, prerm, postrm}
764     \hbr
765   \item Documentation:
766     \begin{itemize}
767     \item Debian Policy Manual, chapter 6\\
768       {\footnotesize \url{http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html}}
769       
770       \hbr
771     \item Debian Developer's Reference, chapter 6.4\\
772       {\scriptsize \url{http://www.debian.org/doc/developers-reference/best-pkging-practices.html}}
773       \hbr
774     \item {\footnotesize \url{http://people.debian.org/~srivasta/MaintainerScripts.html}}
775     \end{itemize}
776     \br
777   \item Prompting the user
778     \begin{itemize}
779     \item Must be done with \textbf{debconf}
780       \hbr
781     \item Documentation: \texttt{debconf-devel(7)} (\texttt{debconf-doc} package)
782     \end{itemize}
783   \end{itemize}
784 \end{frame}
785
786 \begin{frame}[fragile]{Monitoring upstream versions}
787   \begin{itemize}
788   \item Specify where to look in \texttt{debian/watch} (see \texttt{uscan(1)})
789     \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
790 version=3
791
792 http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
793   Twisted-([\d\.]*)\.tar\.bz2
794     \end{lstlisting}
795     \br
796   \item Debian infrastructure that makes use of \texttt{debian/watch}:\\
797     \textbf{Debian External Health Status}\\
798     \url{http://dehs.alioth.debian.org/}
799     \br
800   \item Maintainer warned by emails sent to the Packages Tracking System
801     \br
802   \item \texttt{uscan}: run a manual check
803     \br
804   \item \texttt{uupdate}: try to update your package to the latest upstream version
805   \end{itemize}
806 \end{frame}
807
808 \subsection{Packaging with a VCS (SVN, Git \& friends)}
809 \begin{frame}[fragile]{Packaging with a VCS (SVN, Git \& friends)}
810   \begin{itemize}
811   \item Several tools to help manage branches and tags for your packaging work:\\
812     \texttt{svn-buildpackage}, \texttt{git-buildpackage}
813     \hbr
814   \item Example: \texttt{git-buildpackage}
815     \begin{itemize}
816     \item \texttt{upstream} branch to track upstream with \texttt{upstream/\textsl{version}} tags
817     \item \texttt{master} branch tracks the Debian package
818     \item \texttt{debian/\textsl{version}} tags for each upload
819     \item \texttt{pristine-tar} branch to be able to rebuild the upstream tarball
820     \end{itemize}
821     \hbr
822   \item \texttt{Vcs-*} fields in \texttt{debian/control} to locate the repository
823   \end{itemize}
824   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
825 Vcs-Browser: http://git.debian.org/?p=devscripts/devscripts.git
826 Vcs-Git: git://git.debian.org/devscripts/devscripts.git
827
828 Vcs-Browser: http://svn.debian.org/viewsvn/pkg-perl/trunk/libwww-perl/
829 Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
830   \end{lstlisting}
831   \begin{itemize}
832   \item VCS-agnostic interface: \texttt{debcheckout}, \texttt{debcommit},
833     \texttt{debrelease}\\
834     \texttt{debcheckout devscripts} $\rightarrow$ check out the source package
835     from Git
836 \end{itemize}
837 \end{frame}
838
839 \section{Maintaining packages in Debian}
840 \subsection{Several ways to contribute to Debian}
841 \begin{frame}{Several ways to contribute to Debian}
842   \begin{itemize}
843   \item \textbf{Worst} way to contribute:
844     \begin{itemize}
845     \item Package your own application
846     \item Get it into Debian
847     \item Disappear
848     \end{itemize}
849     \br
850   \item Bring new software to Debian
851     \begin{itemize}
852     \item Only if it's interesting/useful enough, please
853     \item Are there alternatives already packaged in Debian?
854     \end{itemize}
855     \br
856   \item Adopt existing unmaintained packages (\textsl{orphaned packages})
857     \begin{itemize}
858     \item Many unmaintained packages in Debian
859     \item Including some that you use daily!
860     \end{itemize}
861     \br
862   \item Get involved in packaging teams
863     \begin{itemize}
864     \item Many teams that focus on set of packages, and need help
865     \item Full list on \url{http://wiki.debian.org/Teams}
866     \item An excellent way to work with more experienced contributors
867     \end{itemize}
868   \end{itemize}
869 \end{frame}
870
871 \subsection{More interested in Ubuntu?}
872 \begin{frame}{More interested in Ubuntu?}
873   \begin{itemize}
874   \item Ubuntu mainly manages the divergence with Debian
875     \br
876   \item No real focus on specific packages\\
877     Instead, collaboration with Debian teams
878     \br
879   \item Usually recommend uploading new packages to Debian first\\
880     \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages}
881     \br
882   \item Possibly a better plan:
883     \begin{itemize}
884     \item Get involved in a Debian team and act as a bridge with Ubuntu
885       \hbr
886     \item Help reduce divergence, triage bugs in Launchpad
887       \hbr
888     \item Many Debian tools can help:
889       \begin{itemize}
890       \item Ubuntu column on the Developer' packages overview
891       \item Ubuntu box on the Packages Tracking System
892       \item Receive launchpad bugmail via the PTS
893       \end{itemize}
894     \end{itemize}
895   \end{itemize}
896 \end{frame}
897
898 \subsection{Adopting orphaned packages}
899 \begin{frame}{Adopting orphaned packages}
900   \begin{itemize}
901   \item Full list: \url{http://www.debian.org/devel/wnpp/}
902     \hbr
903   \item Installed on your machine: \texttt{wnpp-alert}
904     \hbr
905   \item Different states:
906     \begin{itemize}
907     \item \textbf{O}rphaned: the package is unmaintained\\
908       Feel free to adopt it
909     \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
910       Maintainer looking for adopter, but continues work in the meantime\\
911       Feel free to adopt it. A mail to the current maintainer is polite
912     \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
913       Someone intends to adopt the package\\
914       You could propose your help!
915     \item \textbf{RFH}: (\textbf{R}equest \textbf{F}or \textbf{H}elp\\
916       The maintainer is looking for help
917     \end{itemize}
918     \hbr
919   \item Some unmaintained packages not detected \arr not orphaned yet
920     \hbr
921   \item When in doubt, ask \texttt{debian-qa@lists.debian.org} \\
922     or \texttt{\#debian-qa} on \texttt{irc.debian.org}
923     
924   \end{itemize}
925 \end{frame}
926
927 \section{Resources}
928 \subsection{Where to find help?}
929 \begin{frame}{Where to find help?}
930   Help you will need:
931   \begin{itemize}
932   \item Various advices and answers to your questions, code reviews
933   \item Sponsorship of your uploads, when your package is ready
934   \end{itemize}
935   \br
936   You can get help from:
937   \begin{itemize}
938   \item Other members of a packaging team: the best solution
939     \begin{itemize}
940     \item They know the specifics of your package
941     \item You can become a member of the team
942     \item See \url{http://wiki.debian.org/Teams}
943     \end{itemize}
944     \hbr
945   \item The Debian Mentors group (if your package doesn't fit in a team)
946     \begin{itemize}
947     \item \url{http://wiki.debian.org/DebianMentorsFaq}
948     \item Mailing list: \url{debian-mentors@lists.debian.org}\\
949             {\small (also a good way to learn by accident)}
950     \item IRC: \texttt{\#debian-mentors} on \texttt{irc.debian.org}
951     \item \url{http://mentors.debian.net/}
952     \end{itemize}
953   \end{itemize}
954 \end{frame}
955
956 \subsection{Official documentation}
957 \begin{frame}{Official documentation}
958   \begin{itemize}
959   \item Debian Developers' Corner\\
960     \url{http://www.debian.org/devel/}\\
961     {\small Links to many resources about Debian development}
962     \br
963   \item Debian New Maintainers' Guide\\
964     \url{http://www.debian.org/doc/maint-guide/}\\
965     {\small An introduction to Debian packaging, but could use an update}
966     \br
967   \item Debian Developer's Reference\\
968     \url{http://www.debian.org/doc/developers-reference/}\\
969     {\small Mostly about Debian procedures, but also some best packaging practices (part 6)}
970     \br
971   \item Debian Policy\\
972     \url{http://www.debian.org/doc/debian-policy/}\\
973     
974     {\small \begin{itemize}
975       \item \small All the requirements that every package must satisfy
976       \item \small Specific policies for Perl, Java, Python, \ldots
977       \end{itemize}}
978     \br
979     
980   \item Ubuntu Packaging Guide\\
981     \url{https://wiki.ubuntu.com/PackagingGuide}
982   \end{itemize}
983 \end{frame}
984
985 \begin{frame}{Debian dashboards for maintainers}
986   \begin{itemize}
987           \item \textbf{Source package centric}: Packages Tracking System\\
988     \url{http://packages.qa.debian.org/dpkg}
989     \br
990   \item \textbf{Maintainer/team centric}: Developer's Packages Overview\\
991     \url{http://qa.debian.org/developer.php?login=pkg-ruby-extras-maintainers@lists.alioth.debian.org}
992   \end{itemize}
993 \end{frame}
994
995 \section{Conclusion}
996 \subsection{Conclusion}
997 \begin{frame}{Conclusion}
998   \begin{itemize}
999   \item You now have a full overview of Debian packaging
1000     \br
1001   \item But you will need to read more documentation
1002     \br
1003   \item Best practices have evolved over the years
1004     \begin{itemize}
1005     \item If not sure, use the \textbf{dh} packaging helper, and the \textbf{3.0 (quilt)} format
1006     \end{itemize}
1007     \br
1008   \item Things that were not covered in this tutorial:
1009     \begin{itemize}
1010         \item UCF -- manage user changes to configuration files when upgrading
1011                 \hbr
1012         \item Debian development organization:
1013                 \begin{itemize}
1014                         \item Bug Tracking System (BTS)
1015                         \item Suites: stable, testing, unstable, experimental, security, volatile, backports, \ldots
1016                         \item Debian Blends -- subsets of Debian targetting specific groups
1017                 \end{itemize}
1018                 \end{itemize}
1019   \end{itemize}
1020   \vfill
1021   \centerline{\large Feedback: \textbf{lucas@debian.org}}
1022 \end{frame}
1023
1024 \subsection{Legal stuff}
1025 \begin{frame}{Legal stuff}
1026
1027   Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
1028   \br
1029
1030   {\small 
1031     \textbf{This document is free software}: you can redistribute it and/or modify
1032     it under either (at your option):
1033     \hbr
1034     \begin{itemize}
1035     \item The terms of the GNU General Public License as published by the Free
1036       Software Foundation, either version 3 of the License, or
1037       (at your option) any later version.\\
1038       \url{http://www.gnu.org/licenses/gpl.html} \br
1039     \item The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported
1040       License.\\ 
1041       \url{http://creativecommons.org/licenses/by-sa/3.0/}
1042     \end{itemize}
1043   }
1044 \end{frame}
1045
1046 \subsection{Latest version \& source code}
1047 \begin{frame}{Latest version \& source code}
1048   \begin{itemize}
1049   \item Latest version:\\
1050     {\footnotesize \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git;a=blob\_plain;f=packaging-tutorial.pdf;hb=refs/heads/pdf}}
1051   \end{itemize}
1052   
1053   \begin{itemize}
1054   \item Contribute:\\
1055     \texttt{git clone git://git.debian.org/\~{}lucas/packaging-tutorial.git}\\
1056     \hbr
1057     Or over HTTP: \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git}
1058     \br
1059   \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
1060   \end{itemize}
1061 \end{frame}
1062
1063 \section{Practical session 2: packaging GNUjump}
1064 \begin{frame}{Practical session 2: packaging GNUjump}
1065 \begin{enumerate}
1066         \item Download GNUjump 1.0.6 from
1067                 \url{http://ftp.gnu.org/gnu/gnujump/1.0.6/gnujump-1.0.6.tar.gz}
1068                 \br
1069         \item Create a Debian package for it
1070                 \begin{itemize}
1071                         \item Install build-dependencies so that you can build the package
1072                         \item Get a basic working package
1073                         \item Finish filling \texttt{debian/control} and other files
1074                 \end{itemize}
1075                 \br
1076         \item Enjoy
1077 \end{enumerate}
1078 \centerline{\includegraphics[width=5cm]{figs/gnujump.png}}
1079 \end{frame}
1080
1081 \section{Practical session 3: packaging a Java library}
1082 \begin{frame}{Practical session 3: packaging a Java library}
1083 \begin{enumerate}
1084         \item Take a quick look at some documentation about Java packaging:\\
1085                 \begin{itemize}
1086                 \item \url{http://wiki.debian.org/Java}
1087                 \item \url{http://wiki.debian.org/Java/Packaging}
1088                 \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
1089                 \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
1090                 \item Paper and slides from a Debconf10 talk about javahelper:\\
1091                         {\footnotesize
1092                         \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf}\\
1093                         \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-slides.pdf}}
1094                 \end{itemize}
1095                 \br
1096         \item Download IRClib from \url{http://moepii.sourceforge.net/}
1097                 \br
1098         \item Package it
1099 \end{enumerate}
1100 \end{frame}
1101
1102 \backupbegin
1103
1104 \backupend
1105
1106 \end{document}