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