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