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