+Amateur
[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 easy to use as \texttt{pbuilder})
656     \end{itemize}
657     \br
658   \item Generate \texttt{.deb} files and a \texttt{.changes} file
659     \begin{itemize}
660     \item \texttt{.changes}: describes what was built; used to upload the package
661     \end{itemize}
662   \end{itemize}
663 \end{frame}
664 \subsection{Installing and testing packages}
665 \begin{frame}{Installing and testing packages}
666   \begin{itemize}
667   \item Install the package locally: \textttc{debi} (will use \texttt{.changes}
668     to know what to install) \br
669   \item List the content of the package: \texttt{{\color{rouge}debc}
670       ../mypackage<TAB>.changes} \br
671   \item Compare the package with a previous version:\\
672     \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.changes ../mypackage\_2\_*.changes}\\
673     or to compare the sources:\\
674     \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.dsc ../mypackage\_2\_*.dsc}\\
675     \br
676   \item Check the package with \texttt{lintian} (static analyzer):\\
677     \texttt{{\color{rouge}lintian} ../mypackage<TAB>.changes}\\
678     \texttt{lintian -i}: gives more information about the errors \br
679   \item Upload the package to Debian (\textttc{dput}) (needs configuration) \br
680   \item Manage a private Debian archive with \textttc{reprepro}\\
681     Documentation: \url{http://mirrorer.alioth.debian.org/}
682   \end{itemize}
683 \end{frame}
684 \section{Practical session 1: modifying the grep package}
685 \begin{frame}{Practical session 1: modifying the grep package}
686   \begin{enumerate}
687   \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
688     download version 2.6.3-3 of the package
689   \item Look at the files in \texttt{debian/}.
690     \begin{itemize}
691     \item               How many binary packages are generated by this source package?
692     \item               Which packaging helper does this package use?
693     \end{itemize}
694   \item Build the package
695   \item We are now going to modify the package. Add a changelog entry and increase the version number.
696   \item Now disable perl-regexp support (it is a \texttt{./configure} option)
697   \item Rebuild the package
698   \item Compare the original and the new package with debdiff
699   \item Install the newly built package
700   \item Cry if you messed up ;)
701   \end{enumerate}
702 \end{frame}
703
704 \section{Advanced packaging topics}
705 \subsection{Modifying the upstream source}
706 \begin{frame}{Modifying the upstream source}
707   Often needed:
708   \begin{itemize}
709   \item Fix bugs or add customizations that are specific to Debian
710     \hbr
711   \item Backport fixes from a newer upstream release
712   \end{itemize}
713   \br
714   Several methods to do it:
715   \begin{itemize}
716   \item Modifying the files directly
717     \begin{itemize}
718     \item Simple
719     \item But no way to track and document the changes
720     \end{itemize}
721     \hbr
722   \item Using patch systems
723     \begin{itemize}
724     \item Eases contributing your changes to upstream
725     \item Helps sharing the fixes with derivatives
726     \item Gives more exposure to the changes\\
727       \url{http://patch-tracker.debian.org/}
728     \end{itemize}
729   \end{itemize}
730 \end{frame}
731
732 \begin{frame}{Patch systems}
733   \begin{itemize}
734   \item Principle: changes are stored as patches in \texttt{debian/patches/}
735     \br
736   \item Applied and unapplied during build
737     \br
738   \item Past: several implementations -- \textsl{simple-patchsys} (\textsl{cdbs}),
739     \textsl{dpatch}, \textbf{\textsl{quilt}}
740     \begin{itemize}
741   \item Each supports two \texttt{debian/rules} targets:
742     \begin{itemize}
743     \item \texttt{debian/rules patch}: apply all patches
744     \item \texttt{debian/rules unpatch}: de-apply all patches
745     \end{itemize}
746           \hbr
747   \item More documentation: \url{http://wiki.debian.org/debian/patches}
748   \end{itemize}
749   \br
750   \item \textbf{New source package format with built-in patch system: 3.0 (quilt)}
751   \begin{itemize}
752   \item Recommended solution
753           \hbr
754   \item You need to learn \textsl{quilt}\\
755     \url{http://pkg-perl.alioth.debian.org/howto/quilt.html}
756     
757   \end{itemize}
758   \end{itemize}
759 \end{frame}
760
761 \begin{frame}[fragile]{Documentation of patches}
762   \begin{itemize}
763           \item Standard headers at the beginning of the patch
764     \hbr
765   \item Documented in DEP-3 - Patch Tagging Guidelines\\
766     \url{http://dep.debian.net/deps/dep3/}
767   \end{itemize}
768   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
769 Description: Fix widget frobnication speeds
770  Frobnicating widgets too quickly tended to cause explosions.
771 Forwarded: http://lists.example.com/2010/03/1234.html
772 Author: John Doe <johndoe-guest@users.alioth.debian.org>
773 Applied-Upstream: 1.2, http://bzr.foo.com/frobnicator/revision/123
774 Last-Update: 2010-03-29
775
776 --- a/src/widgets.c
777 +++ b/src/widgets.c
778 @@ -101,9 +101,6 @@ struct {
779 \end{lstlisting}
780 \begin{itemize}
781 \item All patches are published on \url{http://patch-tracker.debian.org/}
782 \end{itemize}
783 \end{frame}
784
785 \subsection{Doing things during installation and removal}
786 \begin{frame}{Doing things during installation and removal}
787   \begin{itemize}
788   \item Decompressing the package is sometimes not enough
789     \hbr
790   \item Create/remove system users, start/stop services, manage \textsl{alternatives}
791     \hbr
792   \item Done in \textsl{maintainer scripts}\\
793     \texttt{preinst, postinst, prerm, postrm}
794     \begin{itemize}
795             \item  Snippets for common actions can be generated by debhelper
796     \end{itemize}
797     \hbr
798   \item Documentation:
799     \begin{itemize}
800     \item Debian Policy Manual, chapter 6\\
801       {\footnotesize \url{http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html}}
802       
803       \hbr
804     \item Debian Developer's Reference, chapter 6.4\\
805       {\scriptsize \url{http://www.debian.org/doc/developers-reference/best-pkging-practices.html}}
806       \hbr
807     \item {\footnotesize \url{http://people.debian.org/~srivasta/MaintainerScripts.html}}
808     \end{itemize}
809     \br
810   \item Prompting the user
811     \begin{itemize}
812     \item Must be done with \textbf{debconf}
813       \hbr
814     \item Documentation: \texttt{debconf-devel(7)} (\texttt{debconf-doc} package)
815     \end{itemize}
816   \end{itemize}
817 \end{frame}
818
819 \begin{frame}[fragile]{Monitoring upstream versions}
820   \begin{itemize}
821   \item Specify where to look in \texttt{debian/watch} (see \texttt{uscan(1)})
822     \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
823 version=3
824
825 http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
826   Twisted-([\d\.]*)\.tar\.bz2
827     \end{lstlisting}
828     \br
829   \item Debian infrastructure that makes use of \texttt{debian/watch}:\\
830     \textbf{Debian External Health Status}\\
831     \url{http://dehs.alioth.debian.org/}
832     \br
833   \item Maintainer warned by emails sent to the Package Tracking System\\
834     \url{http://packages.qa.debian.org/}
835     \br
836   \item \texttt{uscan}: run a manual check
837     \br
838   \item \texttt{uupdate}: try to update your package to the latest upstream version
839   \end{itemize}
840 \end{frame}
841
842 \subsection{Packaging with a VCS (SVN, Git \& friends)}
843 \begin{frame}[fragile]{Packaging with a VCS (SVN, Git, etc.)}
844   \begin{itemize}
845   \item Several tools to help manage branches and tags for your packaging work:\\
846     \texttt{svn-buildpackage}, \texttt{git-buildpackage}
847     \hbr
848   \item Example: \texttt{git-buildpackage}
849     \begin{itemize}
850     \item \texttt{upstream} branch to track upstream with \texttt{upstream/\textsl{version}} tags
851     \item \texttt{master} branch tracks the Debian package
852     \item \texttt{debian/\textsl{version}} tags for each upload
853     \item \texttt{pristine-tar} branch to be able to rebuild the upstream tarball
854     \end{itemize}
855     \hbr
856   \item \texttt{Vcs-*} fields in \texttt{debian/control} to locate the repository
857           \begin{itemize}
858                 \item \url{http://wiki.debian.org/Alioth/Git}
859                 \item \url{http://wiki.debian.org/Alioth/Svn}
860         \end{itemize}
861 \end{itemize}
862   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
863 Vcs-Browser: http://git.debian.org/?p=devscripts/devscripts.git
864 Vcs-Git: git://git.debian.org/devscripts/devscripts.git
865   \end{lstlisting}
866   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
867 Vcs-Browser: http://svn.debian.org/viewsvn/pkg-perl/trunk/libwww-perl/
868 Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
869   \end{lstlisting}
870   \begin{itemize}
871   \item VCS-agnostic interface: \texttt{debcheckout}, \texttt{debcommit},
872     \texttt{debrelease}\\
873     \begin{itemize}
874             \item     \texttt{debcheckout grep} $\rightarrow$ checks out the source package
875     from Git
876     \end{itemize}
877 \end{itemize}
878 \end{frame}
879
880 \section{Maintaining packages in Debian}
881 \subsection{Several ways to contribute to Debian}
882 \begin{frame}{Several ways to contribute to Debian}
883   \begin{itemize}
884   \item \textbf{Worst} way to contribute:
885     \begin{enumerate}
886     \item Package your own application
887     \item Get it into Debian
888     \item Disappear
889     \end{enumerate}
890     \br
891   \item Adopt existing unmaintained packages (\textsl{orphaned packages})
892     \begin{itemize}
893     \item Many unmaintained packages in Debian
894     \item Including some that you use daily!
895     \end{itemize}
896     \br
897   \item Get involved in packaging teams
898     \begin{itemize}
899     \item Many teams that focus on set of packages, and need help
900     \item List available at \url{http://wiki.debian.org/Teams}
901     \item An excellent way to learn from more experienced contributors
902     \end{itemize}
903     \br
904   \item Bring new software to Debian
905     \begin{itemize}
906     \item Only if it's interesting/useful enough, please
907     \item Are there alternatives already packaged in Debian?
908     \end{itemize}
909   \end{itemize}
910 \end{frame}
911
912 \subsection{More interested in Ubuntu?}
913 \begin{frame}{More interested in Ubuntu?}
914   \begin{itemize}
915   \item Ubuntu mainly manages the divergence with Debian
916     \br
917   \item No real focus on specific packages\\
918     Instead, collaboration with Debian teams
919     \br
920   \item Usually recommend uploading new packages to Debian first\\
921     \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages}
922     \br
923   \item Possibly a better plan:
924     \begin{itemize}
925     \item Get involved in a Debian team and act as a bridge with Ubuntu
926       \hbr
927     \item Help reduce divergence, triage bugs in Launchpad
928       \hbr
929     \item Many Debian tools can help:
930       \begin{itemize}
931       \item Ubuntu column on the Developer's packages overview
932       \item Ubuntu box on the Package Tracking System
933       \item Receive launchpad bugmail via the PTS
934       \end{itemize}
935     \end{itemize}
936   \end{itemize}
937 \end{frame}
938
939 \subsection{Adopting orphaned packages}
940 \begin{frame}{Adopting orphaned packages}
941   \begin{itemize}
942   \item Full list: \url{http://www.debian.org/devel/wnpp/}
943     \hbr
944   \item Installed on your machine: \texttt{wnpp-alert}
945     \hbr
946   \item Different states:
947     \begin{itemize}
948     \item \textbf{O}rphaned: the package is unmaintained\\
949       Feel free to adopt it
950     \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
951       Maintainer looking for adopter, but continues work in the meantime\\
952       Feel free to adopt it. A mail to the current maintainer is polite
953     \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
954       Someone intends to adopt the package\\
955       You could propose your help!
956     \item \textbf{RFH}: \textbf{R}equest \textbf{F}or \textbf{H}elp\\
957       The maintainer is looking for help
958     \end{itemize}
959     \hbr
960   \item Some unmaintained packages not detected \arr not orphaned yet
961     \hbr
962   \item When in doubt, ask \texttt{debian-qa@lists.debian.org} \\
963     or \texttt{\#debian-qa} on \texttt{irc.debian.org}
964     
965   \end{itemize}
966 \end{frame}
967
968 \section{Resources}
969 \subsection{Where to find help?}
970 \begin{frame}{Where to find help?}
971   Help you will need:
972   \begin{itemize}
973   \item Various advices and answers to your questions, code reviews
974   \item Sponsorship of your uploads, when your package is ready
975   \end{itemize}
976   \br
977   You can get help from:
978   \begin{itemize}
979   \item Other members of a packaging team: the best solution
980     \begin{itemize}
981     \item They know the specifics of your package
982     \item You can become a member of the team
983     \item See \url{http://wiki.debian.org/Teams}
984     \end{itemize}
985     \hbr
986   \item The Debian Mentors group (if your package doesn't fit in a team)
987     \begin{itemize}
988     \item \url{http://wiki.debian.org/DebianMentorsFaq}
989     \item Mailing list: \url{debian-mentors@lists.debian.org}\\
990             {\small (also a good way to learn by accident)}
991     \item IRC: \texttt{\#debian-mentors} on \texttt{irc.debian.org}
992     \item \url{http://mentors.debian.net/}
993     \end{itemize}
994   \end{itemize}
995 \end{frame}
996
997 \subsection{Official documentation}
998 \begin{frame}{Official documentation}
999   \begin{itemize}
1000   \item Debian Developers' Corner\\
1001     \url{http://www.debian.org/devel/}\\
1002     {\small Links to many resources about Debian development}
1003     \br
1004   \item Debian New Maintainers' Guide\\
1005     \url{http://www.debian.org/doc/maint-guide/}\\
1006     {\small An introduction to Debian packaging, but could use an update}
1007     \br
1008   \item Debian Developer's Reference\\
1009     \url{http://www.debian.org/doc/developers-reference/}\\
1010     {\small Mostly about Debian procedures, but also some best packaging practices (part 6)}
1011     \br
1012   \item Debian Policy\\
1013     \url{http://www.debian.org/doc/debian-policy/}\\
1014     
1015     {\small \begin{itemize}
1016       \item \small All the requirements that every package must satisfy
1017       \item \small Specific policies for Perl, Java, Python, \ldots
1018       \end{itemize}}
1019     \br
1020     
1021   \item Ubuntu Packaging Guide\\
1022     \url{https://wiki.ubuntu.com/PackagingGuide}
1023   \end{itemize}
1024 \end{frame}
1025
1026 \begin{frame}{Debian dashboards for maintainers}
1027   \begin{itemize}
1028           \item \textbf{Source package centric}: Package Tracking System (PTS)\\
1029     \url{http://packages.qa.debian.org/dpkg}
1030     \br
1031   \item \textbf{Maintainer/team centric}: Developer's Packages Overview (DDPO)\\
1032     \url{http://qa.debian.org/developer.php?login=pkg-ruby-extras-maintainers@lists.alioth.debian.org}
1033   \end{itemize}
1034 \end{frame}
1035
1036 \section{Conclusion}
1037 \subsection{Conclusion}
1038 \begin{frame}{Conclusion}
1039   \begin{itemize}
1040   \item You now have a full overview of Debian packaging
1041     \br
1042   \item But you will need to read more documentation
1043     \br
1044   \item Best practices have evolved over the years
1045     \begin{itemize}
1046     \item If not sure, use the \textbf{dh} packaging helper, and the \textbf{3.0 (quilt)} format
1047     \end{itemize}
1048     \br
1049   \item Things that were not covered in this tutorial:
1050     \begin{itemize}
1051         \item UCF -- manage user changes to configuration files when upgrading
1052                 \hbr
1053         \item dpkg triggers -- group similar maintainer scripts actions together
1054                 \hbr
1055         \item Debian development organization:
1056                 \begin{itemize}
1057                         \item Bug Tracking System (BTS)
1058                         \item Suites: stable, testing, unstable, experimental, security, *-updates, backports, \ldots
1059                         \item Debian Blends -- subsets of Debian targetting specific groups
1060                 \end{itemize}
1061                 \end{itemize}
1062   \end{itemize}
1063   \vfill
1064   \centerline{\large Feedback: \textbf{lucas@debian.org}}
1065 \end{frame}
1066
1067 \subsection{Legal stuff}
1068 \begin{frame}{Legal stuff}
1069
1070   Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
1071   \br
1072
1073   {\small 
1074     \textbf{This document is free software}: you can redistribute it and/or modify
1075     it under either (at your option):
1076     \hbr
1077     \begin{itemize}
1078     \item The terms of the GNU General Public License as published by the Free
1079       Software Foundation, either version 3 of the License, or
1080       (at your option) any later version.\\
1081       \url{http://www.gnu.org/licenses/gpl.html} \br
1082     \item The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported
1083       License.\\ 
1084       \url{http://creativecommons.org/licenses/by-sa/3.0/}
1085     \end{itemize}
1086   }
1087 \end{frame}
1088
1089 \subsection{Latest version \& source code}
1090 \begin{frame}{Latest version \& source code}
1091   \begin{itemize}
1092   \item Latest version:\\
1093     {\footnotesize \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git;a=blob\_plain;f=packaging-tutorial.pdf;hb=refs/heads/pdf}}
1094   \end{itemize}
1095   
1096   \begin{itemize}
1097   \item Contribute:\\
1098     \texttt{git clone git://git.debian.org/\~{}lucas/packaging-tutorial.git}\\
1099     \hbr
1100     Or over HTTP: \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git}
1101     \br
1102   \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
1103   \end{itemize}
1104 \end{frame}
1105
1106 \section{Practical session 2: packaging GNUjump}
1107 \begin{frame}{Practical session 2: packaging GNUjump}
1108 \begin{enumerate}
1109         \item Download GNUjump 1.0.6 from
1110                 \url{http://ftp.gnu.org/gnu/gnujump/1.0.6/gnujump-1.0.6.tar.gz}
1111                 \br
1112         \item Create a Debian package for it
1113                 \begin{itemize}
1114                         \item Install build-dependencies so that you can build the package
1115                         \item Get a basic working package
1116                         \item Finish filling \texttt{debian/control} and other files
1117                 \end{itemize}
1118                 \br
1119         \item Enjoy
1120 \end{enumerate}
1121 \centerline{\includegraphics[width=5cm]{figs/gnujump.png}}
1122 \end{frame}
1123
1124 \section{Practical session 3: packaging a Java library}
1125 \begin{frame}{Practical session 3: packaging a Java library}
1126 \begin{enumerate}
1127         \item Take a quick look at some documentation about Java packaging:\\
1128                 \begin{itemize}
1129                 \item \url{http://wiki.debian.org/Java}
1130                 \item \url{http://wiki.debian.org/Java/Packaging}
1131                 \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
1132                 \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
1133                 \item Paper and slides from a Debconf10 talk about javahelper:\\
1134                         {\footnotesize
1135                         \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf}\\
1136                         \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-slides.pdf}}
1137                 \end{itemize}
1138                 \br
1139         \item Download IRClib from \url{http://moepii.sourceforge.net/}
1140                 \br
1141         \item Package it
1142 \end{enumerate}
1143 \end{frame}
1144
1145 \backupbegin
1146
1147 \backupend
1148
1149 \end{document}