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