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