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