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