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