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