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