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