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