review everything, change intro
[packaging-tutorial.git] / packaging-tutorial.tex
1 \documentclass[10pt,final]{beamer}
2 \mode<presentation>
3 \usetheme{lucasdeb}
4 \usepackage{wasysym}
5 \definecolor{darkgreen}{rgb}{0,.7,0}
6 \definecolor{darkred}{rgb}{.7,0,0}
7 \newcommand{\Smiley}{{\color{darkgreen}\smiley}}
8 \newcommand{\Frownie}{{\color{darkred}\frownie}}
9 \usepackage[utf8]{inputenc}
10 \usepackage{helvet}
11 \usepackage[OT1]{fontenc}
12 \usepackage{xspace}
13 \usepackage{verbatim}
14 \usepackage{comment}
15 \usepackage{tabularx}
16 \usepackage{listings}
17 \lstset{basicstyle=\ttfamily}
18 \beamertemplatetransparentcovereddynamic
19 \setbeamercovered{invisible}
20 \newcommand{\br}{\vskip 1em}
21 \newcommand{\hbr}{\vskip 0.5em}
22 \newcommand{\hhbr}{\vskip 0.25em}
23 \newcommand{\Arr}{\textbf{$\Rightarrow$}\xspace}
24 \newcommand{\arr}{\textbf{$\rightarrow$}\xspace}
25 \newcommand{\fixme}[1]{ {\color{red}\footnotesize\bf #1}}
26 \usepackage{listings}
27 \usepackage{tikz}
28 \usepackage{pgfplots}
29 \usetikzlibrary{dateplot}
30
31 \renewcommand{\ttdefault}{aett}
32 \usepackage{aecompl}
33
34 \newcommand{\pedp}{\NoAutoSpaceBeforeFDP}
35
36 \usebackgroundtemplate{\includegraphics[width=\paperwidth]{figs/dslide8.pdf}}
37 \logo{\includegraphics[viewport=274 335 360 440,width=0.5cm]{figs/openlogo-nd.pdf}}
38 \hypersetup{pdftitle={An Introduction to Debian Packaging},bookmarks}
39 \title{An Introduction to Debian Packaging}
40 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
41 \institute{\includegraphics[viewport=274 335 360 440,width=1cm]{figs/openlogo-nd.pdf}}
42 \date{}
43
44 \newcommand{\nospace}[1]{{\NoAutoSpaceBeforeFDP{}#1}}%
45
46 \AtBeginSection[]
47 {
48   \begin{frame}
49     \frametitle{Outline}
50     \tableofcontents[hideothersubsections]
51   \end{frame}
52 }
53
54 \begin{document}
55
56 \frame{\titlepage}
57
58 \section{Introduction}
59 \subsection{Legal stuff}
60 \begin{frame}
61 \frametitle{Legal stuff}
62
63 Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
64 \br
65
66 {\small 
67 \textbf{This document is free software}: you can redistribute it and/or modify
68 it under either (at your option):
69 \hbr
70 \begin{itemize}
71 \item The terms of the GNU General Public License as published by
72     the Free Software Foundation, either version 3 of the License, or
73     (at your option) any later version.\\
74     \url{http://www.gnu.org/licenses/gpl.html}
75     \br
76 \item The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported License.\\
77         \url{http://creativecommons.org/licenses/by-sa/3.0/}
78 \end{itemize}
79 }
80 \end{frame}
81
82 \subsection{Latest version \& source code}
83 \begin{frame}
84 \frametitle{Latest version \& source code}
85 \begin{itemize}
86 \item Latest version:\\
87         {\footnotesize \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git;a=blob\_plain;f=packaging-tutorial.pdf;hb=refs/heads/pdf}}
88 \end{itemize}
89
90 \begin{itemize}
91 \item Contribute:\\
92         \texttt{git clone git://git.debian.org/\~{}lucas/packaging-tutorial.git}\\
93         \hbr
94         Or over HTTP: \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git}
95         \br
96 \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
97 \end{itemize}
98 \end{frame}
99
100 \subsection{About this tutorial}
101 \begin{frame}{About this tutorial}
102 \begin{itemize}
103 \item Goal: tell you what you really need to know about Debian packaging
104 \begin{itemize}
105                         \hbr
106 \item To modify existing packages
107                         \hbr
108 \item To create your own packages
109                         \hbr
110 \item To become a Debian power-user
111 \end{itemize}
112 \br
113 \item Tries to keep a reasonable size
114         \begin{itemize}
115                         \hbr
116                 \item No attempt to be complete
117                         \hbr
118                 \item You will need to read more documentation
119         \end{itemize}
120 \br
121 \item Most of the content also applies to Debian derivatives distributions
122         \begin{itemize}
123                         \hbr
124                 \item That includes Ubuntu
125         \end{itemize}
126 \end{itemize}
127 \end{frame}
128
129 \subsection{The Deb package format}
130 \begin{frame}[fragile]
131         \frametitle{Introduction: the Deb package format}
132 \begin{itemize}
133         \item One of the two most common packages format (with RPM)
134         \item A very powerful and convenient way to distribute software to users
135         \item \texttt{.deb} file: an \texttt{ar} archive
136 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
137 $ ar tv wget_1.12-2.1_i386.deb
138 rw-r--r-- 0/0      4 Sep  5 15:43 2010 debian-binary
139 rw-r--r-- 0/0   2403 Sep  5 15:43 2010 control.tar.gz
140 rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
141 \end{lstlisting}
142 \begin{itemize}
143         \item \texttt{debian-binary}: version of the deb file format, \texttt{"2.0\textbackslash{}n"}
144         \item \texttt{control.tar.gz}: metadata about the package\\
145                 {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
146         \item \texttt{data.tar.gz}: data files of the package
147 \end{itemize}
148 \item You could create your \texttt{.deb} files manually\\
149         {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
150 \item But most people don't do it that way
151 \end{itemize}
152 \hbr
153 \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
154 \end{frame}
155
156 \subsection{Tools you will need}
157 \begin{frame}{Tools you will need}
158         \begin{itemize}
159                 \item A Debian (or Ubuntu) system
160                         \br
161                 \item Some packages:
162         \begin{itemize}
163                 \item \textbf{build-essential}: has dependencies on the packages that will be assumed to be available on the developers' machine (no need to specify them in the \texttt{Build-Depends:} control field of your package)
164                 \begin{itemize}
165                         \item includes a dependency on \textbf{dpkg-dev}, which contains basic Debian-specific tools to create packages
166                 \end{itemize}
167                 \hbr
168         \item \textbf{devscripts}: contains many useful scripts for Debian maintainers
169                 \hbr
170         \item \textbf{lintian}: package checker (static analyzer)
171         \end{itemize}
172         \end{itemize}
173
174         \br
175         Many other tools will also be mentioned later, such as \textbf{debhelper}, \textbf{cdbs}, \textbf{quilt}, \textbf{pbuilder}, \textbf{sbuild}, \textbf{lintian}, \textbf{svn-buildpackage}, \textbf{git-buildpackage}, \ldots
176 \end{frame}
177
178 \subsection{General packaging workflow}
179 \begin{frame}{General packaging workflow}
180 \begin{center}
181 \begin{tikzpicture}[
182         node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
183         arr/.style={very thick},
184         command/.style={text=rouge,font=\ttfamily},
185 ]
186         \node[node1] (us) at (1.5, 0) {upstream source};
187         \node[node1] (da) at (-1.5, 0) {Debian mirror};
188         \node[node1] (sp) at (0, -2) {source package};
189         \draw[arr,<-,dashed] (sp) -- (2.5,-2) node[right=0cm,text width=2.98cm,text centered,font=\small] {where most of the manual work is done};
190         \node[node1] (bin) at (0, -4) {one or several binary packages};
191         \draw[arr,<-,dashed] (bin) -- (3.5,-4) node[right,text centered,font=\ttfamily] {.deb\normalfont};
192         \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
193         \draw[arr,->] (da) -- (sp) node[pos=0.5,left,command] {apt-get source};
194         \draw[arr,->] (sp) -- (bin) node[pos=0.5,right] {\texttt{\color{rouge}debuild} (build and test with \texttt{\color{rouge}lintian})};
195         \draw[arr,->] (bin) -- (-1,-6) node[pos=0.5,left] {install (\texttt{\color{rouge}debi})};
196         \draw[arr,->] (bin) -- (1,-6) node[pos=0.5,right] {upload (\texttt{\color{rouge}dput})};
197         \useasboundingbox (-4,-6) rectangle (6,0); % hack hack hack
198 \end{tikzpicture}
199 \end{center}
200 \end{frame}
201
202 \section{Creating source packages}
203 \subsection{Source packages basics}
204 \begin{frame}
205 \frametitle{Source package}
206 \begin{itemize}
207         \item One source package can generate several binary packages\\
208                 {\small e.g the \texttt{\bfseries libtar} source generates the \texttt{\bfseries libtar} and \texttt{\bfseries libtar-dev} binary packages}
209                 \hbr
210         \item Two kinds of packages: (if unsure, use non-native)
211                 \begin{itemize}
212                                 \small
213                         \item Native packages: software developed inside Debian (\textsl{dpkg}, \textsl{apt})
214                         \item Non-native packages: software developed outside Debian
215                 \end{itemize}
216                 \hbr
217         \item Main file: \texttt{.dsc} (metadata)
218                 \hbr
219         \item Other files depending on the version of the source format
220         \begin{itemize}
221                 \item 1.0 -- native: \texttt{package\_version.tar.gz}
222                 \hbr
223                 \item 1.0 -- non-native:
224                 \begin{itemize}
225                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
226                         \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
227                 \end{itemize}
228                 \hbr
229                 \item 3.0 (quilt):
230                 \begin{itemize}
231                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
232                         \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
233                 \end{itemize}
234         \end{itemize}
235 \end{itemize}
236 \br
237 (See \texttt{dpkg-source(1)} for exact details)
238 \end{frame}
239
240 \begin{frame}[fragile]
241         \frametitle{Source package example (wget\_1.12-2.1.dsc)}
242 \begin{lstlisting}[basicstyle=\ttfamily\small]
243 Format: 3.0 (quilt)
244 Source: wget
245 Binary: wget
246 Architecture: any
247 Version: 1.12-2.1
248 Maintainer: Noel Kothe <noel@debian.org>
249 Homepage: http://www.gnu.org/software/wget/
250 Standards-Version: 3.8.4
251 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo, libssl-dev (>= 0.9.8), dpatch, info2man
252 Checksums-Sha1: 
253  50d4ed2441e67db7aa5061d8a4dde41ee0e94248 2464747 wget_1.12.orig.tar.gz
254  d4c1c8bbe431d6131cbd7ed2e4fc37dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
255 Checksums-Sha256: 
256  7578ed0974e12caa71120581fa3962ee5a69f7175ddc3d6a6db0ecdcba65b572 2464747 wget_1.12.orig.tar.gz
257  1e9b0c4c00eae6b4172baae219a14857f4002382b9d7a289de7ab789c402ad78 48308 wget_1.12-2.1.debian.tar.gz
258 Files: 
259  141461b9c04e454dc8933c9d1f2abf83 2464747 wget_1.12.orig.tar.gz
260  e93123c934e3c141916f472f380278c2 48308 wget_1.12-2.1.debian.tar.gz
261 \end{lstlisting}
262 \end{frame}
263
264 \subsection{Retrieving source packages}
265 \begin{frame}
266 \frametitle{Retrieving an existing source package}
267 \begin{itemize}
268 \item From the Debian archive:
269         \begin{itemize}
270                 \item \texttt{apt-get source \textsl{package}}
271                 \item \texttt{apt-get source \textsl{package=version}}
272                 \item \texttt{apt-get source \textsl{package/release}}
273         \end{itemize}
274         (You need \texttt{deb-src} lines in \texttt{sources.list})
275         \br
276 \item From the Internet:
277         \begin{itemize}
278                 \item \texttt{dget \textsl{url-to.dsc}}
279                 \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\wget\_1.4.4-6.dsc}\\
280                         (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
281         \end{itemize}
282 \br
283 \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
284 \end{itemize}
285 \end{frame}
286
287 \subsection{Creating a basic source package}
288 \begin{frame}
289 \frametitle{Creating a basic source package}
290 \begin{itemize}
291         \item Download the upstream source
292                 \hbr
293         \item Rename to \texttt{\textsl{source\_package}\_\textsl{upstream\_version}.orig.tar.gz}
294                 \hbr
295         \item Untar it
296                 \hbr
297         \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
298                 \hbr
299         \item There are some alternatives to \texttt{dh\_make} for specific sets of packages: \textbf{dh-make-perl}, \textbf{dh-make-php}, \ldots
300                 \hbr
301         \item \texttt{debian/} directory created, with a lot of files in it
302 \end{itemize}
303 \end{frame}
304
305 \subsection{Files in debian/}
306 \begin{frame}{Files in debian/}
307         All the packaging work should usually be made by modifying files in \texttt{debian/}
308 \hbr
309 \begin{itemize}
310         \item Main files:
311         \begin{itemize}
312                 \item changelog
313                 \item copyright
314                 \item control
315                 \item rules
316         \end{itemize}
317         \hbr
318         \item Optional files:
319         \begin{itemize}
320                 \item compat
321                 \item watch
322                 \item dh\_install* targets\\
323                         {\small *.dirs, *.docs, *.manpages, \ldots}
324                 \item maintainer scripts\\
325                         {\small *.postinst, *.prerm, \ldots}
326                 \item source/format
327                 \item patches
328         \end{itemize}
329 \end{itemize}
330 \end{frame}
331
332 \begin{frame}[fragile]{debian/changelog}
333         \begin{itemize}
334                 \item Lists the Debian packaging changes
335                 \item Edited manually or with \texttt{dch}
336                 \item Special format to automatically close Debian or Ubuntu bugs\\
337                         Debian: \texttt{Closes:~\#595268} ; Ubuntu: \texttt{LP:~\#616929}
338                 \item Installed as \texttt{/usr/share/doc/\textit{package}/changelog.Debian.gz} in your package
339         \end{itemize}
340 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
341 mpich2 (1.2.1.1-5) unstable; urgency=low
342
343   * Use /usr/bin/python instead of /usr/bin/python2.5. Allow
344     to drop dependency on python2.5.  Closes: #595268
345   * Make /usr/bin/mpdroot setuid. This is the default after
346     the installation of mpich2 from source, too. LP: #616929
347     + Add corresponding lintian override.
348
349  -- Lucas Nussbaum <lucas@debian.org>  Wed, 15 Sep 2010 18:13:44 +0200
350 \end{lstlisting}
351 \end{frame}
352
353 \begin{frame}[fragile]{debian/copyright}
354         \hbr
355         \begin{itemize}
356                 \item Copyright and license information for the source and the packaging
357                 \item Traditionally written as a text file
358                 \item New machine-readable format: \url{http://dep.debian.net/deps/dep5/}
359         \end{itemize}
360 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
361 Format: <VERSIONED_FORMAT_URL>
362 Upstream-Name: X Solitaire
363 Source: ftp://ftp.example.com/pub/games
364
365 Files: *
366 Copyright: Copyright 1998 John Doe <jdoe@example.com>
367 License: GPL-2+
368  This program is free software; you can redistribute it
369  [...]
370  .
371  On Debian systems, the full text of the GNU General Public
372  License version 2 can be found in the file
373  `/usr/share/common-licenses/GPL-2'.
374
375 Files: debian/*
376 Copyright: Copyright 1998 Jane Smith <jsmith@example.net>
377 License:
378  [LICENSE TEXT]
379 \end{lstlisting}
380 \end{frame}
381
382 \begin{frame}[fragile]{debian/control}
383         \hbr
384         \begin{itemize}
385                 \item Package metadata
386                         \begin{itemize}
387                                 \item For the source package itself
388                                 \item For each binary package built from this source
389                         \end{itemize}
390                         \hbr
391                 \item Package name, section, priority, maintainer, uploaders, build-dependencies, dependencies, description, homepage, \ldots
392                         \hbr
393                 \item Documentation: Debian Policy chapter 5\\
394                         \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
395         \end{itemize}
396 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
397 Source: wget
398 Section: web
399 Priority: important
400 Maintainer: Noel Kothe <noel@debian.org>
401 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
402  libssl-dev (>= 0.9.8), dpatch, info2man
403 Standards-Version: 3.8.4
404 Homepage: http://www.gnu.org/software/wget/
405
406 Package: wget
407 Architecture: any
408 Depends: ${shlibs:Depends}, ${misc:Depends}
409 Description: retrieves files from the web
410  Wget is a network utility to retrieve files from the Web
411 \end{lstlisting}
412 \end{frame}
413
414 \begin{frame}{Architecture: all or any}
415 Two kinds of binary packages:
416 \hbr
417 \begin{itemize}
418         \item Packages with a different content on each Debian architecture
419         \begin{itemize}
420         \item Example: C program
421         \item \texttt{Architecture:\ any} in \texttt{debian/control}
422                 \begin{itemize}
423                         \item Or, if it only works on a subset of architectures:\\
424                                 \texttt{Architecture:\ amd64 i386 ia64 hurd-i386}
425                 \end{itemize}
426         \item Packages for other architectures built by the Debian infrastructure
427         \item Named \texttt{\textsl{package}\_\textsl{version}\_\textsl{architecture}.deb}
428         \end{itemize}
429 \br
430         \item Packages with the same content on all architectures
431         \begin{itemize}
432         \item Example: Perl library
433         \item \texttt{Architecture:\ all} in \texttt{debian/control}
434         \item Named \texttt{\textsl{package}\_\textsl{version}\_\textbf{all}.deb}
435 \end{itemize}
436 \end{itemize}
437 \end{frame}
438
439 \begin{frame}[fragile]{debian/rules}
440         \hbr
441         \begin{itemize}
442                 \item Makefile
443                         \br
444                 \item Interface used to build Debian packages
445                         \br
446                 \item Documented in Debian Policy, chapter 4.8\\
447                         {\small \texttt{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
448                         \br
449                 \item Five required targets:
450                 \begin{itemize}
451                         \item \texttt{build}: should perform all the configuration and compilation of the package
452                                 \hbr
453                         \item \texttt{binary, binary-arch, binary-indep}: build the binary packages produced by this source package
454                                 \begin{itemize}
455                                         \item \texttt{dpkg-buildpackage} will call \texttt{binary} to build all the packages, or \texttt{binary-arch} to build only the \texttt{Architecture:~any} packages
456                                 \end{itemize}
457                                 \hbr
458                         \item \texttt{clean}: clean up the source directory
459                 \end{itemize}
460         \end{itemize}
461 \end{frame}
462
463 \subsection{Packaging helpers}
464 \begin{frame}{Packaging helpers -- debhelper}
465 \begin{itemize}
466         \item You could write shell code in \texttt{debian/rules} directly
467         \begin{itemize}
468                 \item See the \texttt{adduser} package for example
469         \end{itemize}
470         \hbr
471         \item But most packages in Debian use a \textsl{Packaging helper}
472         \hbr
473         \item Most popular one: \textbf{debhelper} (used by 98\% of packages)
474         \hbr
475         \item Goal: factor the common tasks in external tools used by all packages\\
476                 {\footnotesize dh\_installdirs, dh\_installchangelogs, dh\_installdocs, dh\_installexamples, dh\_install, dh\_installdebconf, dh\_installinit, dh\_link, dh\_strip, dh\_compress, dh\_fixperms, dh\_perl, dh\_makeshlibs, dh\_installdeb, dh\_shlibdeps, dh\_gencontrol, dh\_md5sums, dh\_builddeb, \ldots}
477                 \begin{itemize}
478                         \item Called from \texttt{debian/rules}
479                         \item Behaviour changed using command parameters or files in \texttt{debian/}\\
480                                 {\footnotesize \ttfamily dirs, package.docs, package.examples, package.install, package.menu, package.logrotate, package.manpages, \ldots}
481                 \end{itemize}
482         \hbr
483 \item Third-party helpers for sets of packages: \textbf{python-support}, \textbf{dh\_ocaml}, \ldots
484         \hbr
485 \item Gotcha: \texttt{debian/compat}: Debhelper compatibility version (use "7")
486 \end{itemize}
487 \end{frame}
488
489 \begin{frame}[fragile]{debian/rules using debhelper (1/2)}
490 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
491 #!/usr/bin/make -f
492
493 # Uncomment this to turn on verbose mode.
494 #export DH_VERBOSE=1
495
496 build: 
497         $(MAKE)
498         #docbook-to-man debian/packagename.sgml > packagename.1
499
500 clean: 
501         dh_testdir
502         dh_testroot
503         rm -f build-stamp configure-stamp
504         $(MAKE) clean
505         dh_clean 
506
507 install: build
508         dh_testdir
509         dh_testroot
510         dh_clean -k 
511         dh_installdirs
512         # Add here commands to install the package into debian/packagename.
513         $(MAKE) DESTDIR=$(CURDIR)/debian/packagename install
514 \end{lstlisting}
515 \end{frame}
516
517 \begin{frame}[fragile]{debian/rules using debhelper (2/2)}
518 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
519
520 # Build architecture-independent files here.
521 binary-indep: build install
522
523 # Build architecture-dependent files here.
524 binary-arch: build install
525         dh_testdir
526         dh_testroot
527         dh_installchangelogs 
528         dh_installdocs
529         dh_installexamples
530 #       dh_install
531         dh_installman
532         dh_link
533         dh_strip
534         dh_compress
535         dh_fixperms
536         dh_installdeb
537         dh_shlibdeps
538         dh_gencontrol
539         dh_md5sums
540         dh_builddeb
541
542 binary: binary-indep binary-arch
543 .PHONY: build clean binary-indep binary-arch binary install configure
544 \end{lstlisting}
545 \end{frame}
546
547 \begin{frame}[fragile]{CDBS}
548 \hbr
549 \begin{itemize}
550 \item Still a lot of redundancy between packages
551 \hbr
552 \item Second-level helpers that factor common funtionality
553         \begin{itemize}
554         \item Building with \texttt{./configure \&\& make \&\& make install} or CMake
555         \item Support for Perl, Python, Ruby, GNOME, KDE, Java, Haskell, \ldots
556         \end{itemize}
557 \hbr
558 \item CDBS:
559         \begin{itemize}
560                 \item Introduced in 2005, based on advanced \textsl{GNU make} magic
561                 \item Documentation: \texttt{/usr/share/doc/cdbs/}
562                 \item But some people hate it:
563                         \begin{itemize}
564                                 \item Sometimes difficult to customize package builds:\\
565                                 "\textsl{twisty maze of makefiles, environment vars and black magic}"
566                         \item Slower than plain debhelper (many useless calls to \texttt{dh\_*})
567                         \end{itemize}
568 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
569 #!/usr/bin/make -f
570 include /usr/share/cdbs/1/rules/debhelper.mk
571 include /usr/share/cdbs/1/class/autotools.mk
572
573 # add an action after the build
574 build/mypackage::
575     /bin/bash debian/scripts/foo.sh
576 \end{lstlisting}
577         \end{itemize}
578 \end{itemize}
579 \end{frame}
580
581 \begin{frame}[fragile]{Debhelper 7 (aka dh7, or just dh)}
582 \begin{itemize}
583 \item Introduced in 2008 as a \textsl{CDBS killer}
584 \hbr
585 \item \textbf{dh} command that calls \texttt{dh\_*}
586 \hbr
587 \item Simple \textsl{debian/rules}, listing only overrides
588 \hbr
589 \item Easier to customize than CDBS
590 \hbr
591 \item Doc: slides from Joey Hess' Debconf9 talk\\\
592         \url{http://kitenet.net/~joey/talks/debhelper/debhelper-slides.pdf}
593         \br
594 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
595 #!/usr/bin/make -f
596 %:
597     dh $@
598
599 override_dh_auto_configure:
600      dh_auto_configure -- --with-kitchen-sink
601
602 override_dh_auto_build:
603      make world
604
605 \end{lstlisting}
606 \end{itemize}
607 \end{frame}
608
609 \begin{frame}{Plain debhelper vs CDBS vs debhelper 7}
610         \hbr
611 \begin{itemize}
612 \item Market shares: (feb'11)\\
613 Plain debhelper: 45\% \hskip 1em CDBS: 24\% \hskip 1em  debhelper7: 29\%
614 \hbr
615 \item Which one should I learn?
616 \begin{itemize}
617         \item Probably all of them
618         \item You need to know debhelper to use CDBS and dh7
619         \item You might have to modify CDBS packages
620 \end{itemize}
621 \hbr
622 \item Which one should I use for a new package?
623 \begin{itemize}
624         \item Debhelper 7 (only solution with an increasing market share)
625 \end{itemize}
626 \end{itemize}
627
628 \hbr
629 \begin{center}
630 \begin{tikzpicture}
631 \begin{axis}[small,label style={font=\footnotesize},xlabel={\small Time},ylabel={\small Market share (\%)},
632         date coordinates in=x,height=4.85cm,width=9cm,xticklabel={\month/\year},
633              legend style={font=\footnotesize,at={(1.02,1)},anchor=north west},max space between ticks=82,try min ticks=5,ymin=0]
634         \addplot[mark=none,blue,thick] table[x=date,y=dh] {cdbs-dh7.txt};
635         \addplot[mark=none,red,thick] table[x=date,y=dh7] {cdbs-dh7.txt};
636         \addplot[mark=none,green,thick] table[x=date,y=cdbs] {cdbs-dh7.txt};
637         \legend{debhelper, dh7, CDBS}
638 \end{axis}
639 \end{tikzpicture}
640 \end{center}
641
642 \end{frame}
643
644 \section{Building and testing packages}
645 \subsection{Building packages}
646 \subsection{Testing packages}
647
648 \section{Practical session 1 : modifying the wget package}
649 \begin{frame}{Practical session 1: modifying the wget package}
650 \begin{enumerate}
651         \item Go to \url{http://ftp.debian.org/debian/pool/main/w/wget/} and
652                 download version 1.12-2.1 of the package
653         \item Look at the files in \texttt{debian/}.
654                 \begin{itemize}
655                         \item           How many binary packages are generated by this source package?
656                         \item           Which packaging helper does this package use?
657                 \end{itemize}
658         \item Build the package
659         \item We are now going to modify the package. Add a changelog entry and increase the version number.
660         \item The lintian warning \textsl{more-than-one-patch-system} is caused by the build-dependency on \texttt{dpatch}. Remove it, and add an appropriate changelog entry.
661         \item Now disable IPv6 support (it is a \texttt{./configure} option)
662         \item Rebuild the package
663         \item Install the newly built package
664         \item Compare the original and the new package with debdiff
665 \end{enumerate}
666 \end{frame}
667
668 \section{Maintaining packages in Debian}
669 \subsection{Becoming a Debian contributor}
670 \begin{frame}
671 \frametitle{Becoming a Debian contributor}
672 Several ways to contribute:
673 \hbr
674 \begin{itemize}
675 \item Bring new software to Debian
676 \begin{itemize}
677 \item Is that new software interesting/useful enough?
678 \item Are there alternatives already packaged in Debian?
679 \end{itemize}
680 \br
681 \item Adopt existing unmaintained packages (\textsl{orphaned packages})
682 \begin{itemize}
683         \item Many unmaintained packages in Debian
684         \item Including some that you rely on, probably
685 \end{itemize}
686 \br
687 \item Get involved in packaging teams
688 \begin{itemize}
689 \item Many teams that focus on set of packages, and need help
690 \item Full list on \url{http://wiki.debian.org/Teams}
691 \item An excellent way to work with more experienced contributors
692 \end{itemize}
693 \end{itemize}
694 \end{frame}
695
696 \subsection{More interested in Ubuntu?}
697 \begin{frame}
698 \frametitle{More interested in Ubuntu?}
699 \begin{itemize}
700         \item Ubuntu mainly manages the divergence with Debian
701         \br
702         \item Do not really focus on specific packages\\
703                 Instead, collaborate with Debian teams
704         \br
705         \item Usually recommend uploading new packages to Debian first\\
706                 \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages/}
707         \br
708         \item Possibly a better plan:
709         \begin{itemize}
710                 \item Get involved in a Debian team and act as a bridge with Ubuntu
711                         \hbr
712                 \item Help reduce divergence, triage bugs in Launchpad
713                         \hbr
714                 \item Many Debian tools can help:
715                 \begin{itemize}
716                 \item Ubuntu column on the Developer' packages overview
717                 \item Ubuntu box on the Packages Tracking System
718                 \item Receive launchpad bugmail via the PTS
719                 \end{itemize}
720         \end{itemize}
721 \end{itemize}
722 \end{frame}
723
724 \subsection{Adopting orphaned packages}
725 \begin{frame}{Adopting orphaned packages}
726 \begin{itemize}
727         \item Full list: \url{http://www.debian.org/devel/wnpp/}
728         \item Installed on your machine: \texttt{wnpp-alert}
729         \item Different states:
730         \begin{itemize}
731                 \item \textbf{O}rphaned: the package is unmaintained\\
732                         Feel free to adopt it
733                 \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
734                         Maintainer looking for adopter, but continues work in the meantime\\
735                         Feel free to adopt it. A mail to the current maintainer is polite
736                 \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
737                         Someone intends to adopt the package\\
738                         You could propose your help!
739                 \item \textbf{RFH} (\textbf{R}equest \textbf{F}or \textbf{H}elp\\
740                         The maintainer is looking for help
741         \end{itemize}
742         \item Some unmaintained packages not detected \arr not orphaned yet
743         \item When in doubt, ask \texttt{debian-qa@lists.debian.org}
744         \end{itemize}
745 \end{frame}
746
747
748 \section{Resources}
749 \subsection{Where to find help?}
750 \begin{frame}
751 \frametitle{Where to find help?}
752 Help you will need:
753 \begin{itemize}
754         \item Various advices and answers to your questions, code reviews
755         \item Sponsorship of your uploads, when your package is ready
756 \end{itemize}
757 \br
758 You can get help from:
759 \begin{itemize}
760         \item Other members of a packaging team $\leftarrow$ the best solution
761                 \begin{itemize}
762                         \item They know the specifics of your package
763                         \item You can become a member of the team
764                         \item See \url{http://wiki.debian.org/Teams}
765                 \end{itemize}
766         \hbr
767         \item The Debian Mentors group (if your package doesn't fit in a team)
768                 \begin{itemize}
769                         \item \url{http://wiki.debian.org/DebianMentorsFaq}
770                         \item Mailing list: \url{debian-mentors@lists.debian.org}
771                         \item IRC: \texttt{\#debian-mentors} on \texttt{irc.debian.org}
772                         \item \url{http://mentors.debian.net/}
773                 \end{itemize}
774 \end{itemize}
775 \end{frame}
776
777 \subsection{Official documentation}
778 \begin{frame}{Official documentation}
779         \begin{itemize}
780                 \item Debian Developers' Corner\\
781                         \url{http://www.debian.org/devel/}\\
782                         {\small Links to many resources about Debian development}
783                         \hbr
784                 \item Debian New Maintainers' Guide\\
785                         \url{http://www.debian.org/doc/maint-guide/}\\
786                         {\small An introduction to Debian packaging, but could use an update}
787                         \hbr
788                 \item Debian Developer's Reference\\
789                       \url{http://www.debian.org/doc/developers-reference/}\\
790                       {\small Mostly about Debian procedures, but also some best packaging practices (part 6)}
791                         \hbr
792
793               \item Debian Policy\\
794                     \url{http://www.debian.org/doc/debian-policy/}\\
795                     {\small All the requirements that every package must satisfy}
796                         \hbr
797
798                 \item Ubuntu Packaging Guide\\
799                         \url{https://wiki.ubuntu.com/PackagingGuide}
800         \end{itemize}
801 \end{frame}
802
803 \section{TODO}
804 \begin{frame}
805         \frametitle{Things not covered (yet)}
806 Packaging:
807 \begin{itemize}
808 \item Example: removing IPv6 support from wget
809 \item New source formats
810 \item Modifying the upstream source + patch systems
811 \item Maintainer scripts
812 \item Debconf
813 \item watch + uupdate
814 \end{itemize}
815 Processes:
816 \begin{itemize}
817 \item Building packages -- dpkg-buildpackage pbuilder sbuild debi lintian debdiff debc
818 \item Uploading debsign / dput -- private archive -- reprepro
819 \item Packaging with VCSes debcheckout debcommit debrelease git-buildpackage svn-buildpackage
820 \end{itemize}
821 \end{frame}
822
823
824 \end{document}