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