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