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