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