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