1 \documentclass[10pt,final]{beamer}
4 \usepackage{debiantutorial}
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}}
16 \begin{frame}{About this tutorial}
18 \item Goal: \textbf{tell you what you really need to know about Debian packaging}
21 \item Modify existing packages
23 \item Create your own packages
25 \item Become a Debian power-user
28 \item Covers the most important points, but is not complete
30 \item You will need to read more documentation
33 \item Most of the content also applies to Debian derivatives distributions
36 \item That includes Ubuntu
41 \begin{frame}{Outline}
42 \tableofcontents[hideallsubsections]
45 \section{Introduction}
51 \item \textbf{GNU/Linux distribution}
53 \item 1st major distro developed "openly in the spirit of GNU"
55 \item \textbf{Non-commercial}, built collaboratively by more than 1000 volunteers
57 \item 30000 binary packages ; 12 ports (inc. 2 non-Linux) ; 120 derivatives
59 \item 3 main features:
61 \item \textbf{Quality} -- culture of technical excellence\\
62 {\small\sl We release when it's ready}
64 \item \textbf{Freedom} -- devs and users bound by the \textsl{Social Contract}\\
65 Promoting the culture of Free Software since 1993
67 \item \textbf{Independence} -- no (single) company babysitting Debian\\
68 And open decision-making process (\textsl{do-ocracy} + \textsl{democracy})
75 \subsection{The Deb package format}
77 \begin{frame}[fragile]{The Deb package format}
79 \item One of the two most common packages format (with RPM)
80 \item A very powerful and convenient way to distribute software to users
81 \item \texttt{.deb} file: an \texttt{ar} archive
82 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
83 $ ar tv wget_1.12-2.1_i386.deb
84 rw-r--r-- 0/0 4 Sep 5 15:43 2010 debian-binary
85 rw-r--r-- 0/0 2403 Sep 5 15:43 2010 control.tar.gz
86 rw-r--r-- 0/0 751613 Sep 5 15:43 2010 data.tar.gz
89 \item \texttt{debian-binary}: version of the deb file format, \texttt{"2.0\textbackslash{}n"}
90 \item \texttt{control.tar.gz}: metadata about the package\\
91 {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
92 \item \texttt{data.tar.gz}: data files of the package
94 \item You could create your \texttt{.deb} files manually\\
95 {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
96 \item But most people don't do it that way
99 \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
102 \subsection{Tools you will need}
103 \begin{frame}{Tools you will need}
105 \item A Debian (or Ubuntu) system (with root access)
109 \item \textbf{build-essential}: has dependencies on the packages that will
110 be assumed to be available on the developers' machine (no need to specify
111 them in the \texttt{Build-Depends:} control field of your package)
113 \item includes a dependency on \textbf{dpkg-dev}, which contains basic
114 Debian-specific tools to create packages
117 \item \textbf{devscripts}: contains many useful scripts for Debian
123 Many other tools will also be mentioned later, such as \textbf{debhelper},
124 \textbf{cdbs}, \textbf{quilt}, \textbf{pbuilder}, \textbf{sbuild},
125 \textbf{lintian}, \textbf{svn-buildpackage}, \textbf{git-buildpackage},
127 Install them when you need them.
130 \subsection{General packaging workflow}
131 \begin{frame}{General packaging workflow}
134 node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
135 arr/.style={very thick}, command/.style={text=rouge,font=\ttfamily}, ]
137 \node[node1] (www) at (0, 0) {Web};
138 \node[node1] (us) at (2.5, 0) {upstream source};
139 \node[node1] (da) at (-2.5, 0) {Debian mirror};
140 \node[node1] (sp) at (0, -2) {source package};
141 \draw[arr,<-,dashed,thick] (sp) -- (2.5,-2) node[right=0cm,text width=2.98cm,text centered,font=\small\sl] {where most of the manual work is done};
142 \node[node1] (bin) at (0, -4) {one or several binary packages};
143 \draw[arr,<-,dashed,thick] (bin) -- (3.5,-4) node[right,text centered,font=\small\ttfamily\sl] {.deb\normalfont};
144 \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
145 \draw[arr,->] (da) -- (sp) node[pos=0.5,left,command] {apt-get source};
146 \draw[arr,->] (www) -- (sp) node[pos=0.5,left,command] {dget};
147 \draw[arr,->] (sp) -- (bin) node[pos=0.5,right,text width=6cm] {\textttc{debuild} (build and test with \textttc{lintian}) or \textttc{dpkg-buildpackage}};
148 \draw[arr,->] (bin) -- (1,-6) node[pos=0.5,right] {install (\textttc{debi})};
149 % \draw[arr,->] (bin) -- (-1,-6) node[pos=0.5,left] {upload (\textttc{dput})};
150 \draw[transparent] (bin) -- (-1,-6) node[pos=0.5,left,opaque] {upload (\textttc{dput})};
151 \draw[arr,->,rounded corners] (bin) -- (-1,-6) -- (-4.5,-6) -- (-4.5,0) -- (da);
152 \useasboundingbox (-4,-6) rectangle (6,0); % hack hack hack
157 \section{Creating source packages}
158 \subsection{Source packages basics}
159 \begin{frame}{Source package}
161 \item One source package can generate several binary packages\\
162 {\small e.g the \texttt{\bfseries libtar} source generates the
163 \texttt{\bfseries libtar} and \texttt{\bfseries libtar-dev} binary
165 \item Two kinds of packages: (if unsure, use non-native)
168 \item Native packages: software developed inside Debian (\textsl{dpkg}, \textsl{apt})
169 \item Non-native packages: software developed outside Debian
172 \item Main file: \texttt{.dsc} (meta-data)
174 \item Other files depending on the version of the source format
176 \item 1.0 -- native: \texttt{package\_version.tar.gz}
178 \item 1.0 -- non-native:
180 \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
181 \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
186 \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
187 \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
192 (See \texttt{dpkg-source(1)} for exact details)
195 \begin{frame}[fragile]{Source package example (wget\_1.12-2.1.dsc)}
196 \begin{lstlisting}[basicstyle=\ttfamily\small]
202 Maintainer: Noel Kothe <noel@debian.org>
203 Homepage: http://www.gnu.org/software/wget/
204 Standards-Version: 3.8.4
205 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
206 libssl-dev (>= 0.9.8), dpatch, info2man
208 50d4ed2441e67[..]1ee0e94248 2464747 wget_1.12.orig.tar.gz
209 d4c1c8bbe431d[..]dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
211 7578ed0974e12[..]dcba65b572 2464747 wget_1.12.orig.tar.gz
212 1e9b0c4c00eae[..]89c402ad78 48308 wget_1.12-2.1.debian.tar.gz
214 141461b9c04e4[..]9d1f2abf83 2464747 wget_1.12.orig.tar.gz
215 e93123c934e3c[..]2f380278c2 48308 wget_1.12-2.1.debian.tar.gz
219 \subsection{Retrieving source packages}
220 \begin{frame}{Retrieving an existing source package}
222 \item From the Debian archive:
224 \item \texttt{apt-get source \textsl{package}}
225 \item \texttt{apt-get source \textsl{package=version}}
226 \item \texttt{apt-get source \textsl{package/release}}
228 (You need \texttt{deb-src} lines in \texttt{sources.list})
230 \item From the Internet:
232 \item \texttt{dget \textsl{url-to.dsc}}
233 \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\
235 (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
238 \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
242 \subsection{Creating a basic source package}
243 \begin{frame}{Creating a basic source package}
245 \item Download the upstream source\\
246 (\textsl{upstream source} = the one from the software's original developers)
248 \item Rename to \texttt{<\textsl{source\_package}>\_<\textsl{upstream\_version}>.orig.tar.gz}\\
249 (example: \texttt{simgrid\_3.6.orig.tar.gz})
253 \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
255 \item There are some alternatives to \texttt{dh\_make} for specific sets of
256 packages: \textbf{dh-make-perl}, \textbf{dh-make-php}, \ldots \hbr
257 \item \texttt{debian/} directory created, with a lot of files in it
261 \subsection{Files in debian/}
262 \begin{frame}{Files in debian/}
263 All the packaging work should be made by modifying files in \texttt{debian/}
268 \item \textbf{changelog} -- history of the Debian package
269 \item \textbf{copyright} -- copyright information for the package
270 \item \textbf{control} -- meta-data about the package (dependencies, etc)
271 \item \textbf{rules} -- specifies how to build the package
274 \item Optional files:
278 \item dh\_install* targets\\
279 {\small *.dirs, *.docs, *.manpages, \ldots}
280 \item maintainer scripts\\
281 {\small *.postinst, *.prerm, \ldots}
283 \item patches -- if you need to modify the upstream sources
286 \item Most of the files use a format based on RFC 822 (mail headers)
290 \begin{frame}[fragile]{debian/changelog}
292 \item Lists the Debian packaging changes
293 \item Edited manually or with \texttt{dch}
294 \item Special format to automatically close Debian or Ubuntu bugs\\
295 Debian: \texttt{Closes:~\#595268} ; Ubuntu: \texttt{LP:~\#616929}
296 \item Installed as \texttt{/usr/share/doc/\textit{package}/changelog.Debian.gz}
298 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
299 mpich2 (1.2.1.1-5) unstable; urgency=low
301 * Use /usr/bin/python instead of /usr/bin/python2.5. Allow
302 to drop dependency on python2.5. Closes: #595268
303 * Make /usr/bin/mpdroot setuid. This is the default after
304 the installation of mpich2 from source, too. LP: #616929
305 + Add corresponding lintian override.
307 -- Lucas Nussbaum <lucas@debian.org> Wed, 15 Sep 2010 18:13:44 +0200
311 \begin{frame}[fragile]{debian/copyright}
314 \item Copyright and license information for the source and the packaging
315 \item Traditionally written as a text file
316 \item New machine-readable format: \url{http://dep.debian.net/deps/dep5/}
318 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
319 Format: <VERSIONED_FORMAT_URL>
320 Upstream-Name: X Solitaire
321 Source: ftp://ftp.example.com/pub/games
324 Copyright: Copyright 1998 John Doe <jdoe@example.com>
326 This program is free software; you can redistribute it
329 On Debian systems, the full text of the GNU General Public
330 License version 2 can be found in the file
331 `/usr/share/common-licenses/GPL-2'.
334 Copyright: Copyright 1998 Jane Smith <jsmith@example.net>
340 \begin{frame}[fragile]{debian/control}
343 \item Package metadata
345 \item For the source package itself
346 \item For each binary package built from this source
349 \item Package name, section, priority, maintainer, uploaders,
350 build-dependencies, dependencies, description, homepage, \ldots \hbr
351 \item Documentation: Debian Policy chapter 5\\
352 \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
354 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
358 Maintainer: Noel Kothe <noel@debian.org>
359 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
360 libssl-dev (>= 0.9.8), dpatch, info2man
361 Standards-Version: 3.8.4
362 Homepage: http://www.gnu.org/software/wget/
366 Depends: ${shlibs:Depends}, ${misc:Depends}
367 Description: retrieves files from the web
368 Wget is a network utility to retrieve files from the Web
372 \begin{frame}{Architecture: all or any}
373 Two kinds of binary packages:
376 \item Packages with a different content on each Debian architecture
378 \item Example: C program
379 \item \texttt{Architecture:\ any} in \texttt{debian/control}
381 \item Or, if it only works on a subset of architectures:\\
382 \texttt{Architecture:\ amd64 i386 ia64 hurd-i386}
384 \item Packages for other architectures built by the Debian infrastructure
385 \item Named \texttt{\textsl{package}\_\textsl{version}\_\textsl{architecture}.deb}
388 \item Packages with the same content on all architectures
390 \item Example: Perl library
391 \item \texttt{Architecture:\ all} in \texttt{debian/control}
392 \item Named \texttt{\textsl{package}\_\textsl{version}\_\textbf{all}.deb}
397 \begin{frame}[fragile]{debian/rules}
402 \item Interface used to build Debian packages
404 \item Documented in Debian Policy, chapter 4.8\\
405 {\small \texttt{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
407 \item Five required targets:
409 \item \texttt{build}: should perform all the configuration and compilation
411 \item \texttt{binary, binary-arch, binary-indep}: build the binary packages
413 \item \texttt{dpkg-buildpackage} will call \texttt{binary} to build all
414 the packages, or \texttt{binary-arch} to build only the
415 \texttt{Architecture:~any} packages
418 \item \texttt{clean}: clean up the source directory
423 \subsection{Packaging helpers}
424 \begin{frame}{Packaging helpers -- debhelper}
426 \item You could write shell code in \texttt{debian/rules} directly
428 \item See the \texttt{adduser} package for example
431 \item Better practice (used by most packages): use a \textsl{Packaging helper}
433 \item Most popular one: \textbf{debhelper} (used by 98\% of packages)
437 \item Factor the common tasks in standard tools used by all packages
438 \item Fix some packaging bugs once for all packages
440 {\footnotesize dh\_installdirs, dh\_installchangelogs, dh\_installdocs,
441 dh\_installexamples, dh\_install, dh\_installdebconf, dh\_installinit,
442 dh\_link, dh\_strip, dh\_compress, dh\_fixperms, dh\_perl,
443 dh\_makeshlibs, dh\_installdeb, dh\_shlibdeps, dh\_gencontrol,
444 dh\_md5sums, dh\_builddeb, \ldots}
446 \item Called from \texttt{debian/rules}
447 \item Configurable using command parameters or files in \texttt{debian/}
449 {\footnotesize \ttfamily dirs, package.docs, package.examples,
450 package.install, package.manpages, \ldots} \hbr
451 \item Third-party helpers for sets of packages: \textbf{python-support},
452 \textbf{dh\_ocaml}, \ldots \hbr
453 \item Gotcha: \texttt{debian/compat}: Debhelper compatibility version (use "7")
457 \begin{frame}[fragile]{debian/rules using debhelper (1/2)}
458 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
461 # Uncomment this to turn on verbose mode.
466 #docbook-to-man debian/packagename.sgml > packagename.1
471 rm -f build-stamp configure-stamp
480 # Add here commands to install the package into debian/packagename.
481 $(MAKE) DESTDIR=$(CURDIR)/debian/packagename install
485 \begin{frame}[fragile]{debian/rules using debhelper (2/2)}
486 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
488 # Build architecture-independent files here.
489 binary-indep: build install
491 # Build architecture-dependent files here.
492 binary-arch: build install
510 binary: binary-indep binary-arch
511 .PHONY: build clean binary-indep binary-arch binary install configure
515 \begin{frame}[fragile]{CDBS}
518 \item Still a lot of redundancy between packages
520 \item Second-level helpers that factor common funtionality
522 \item Building with \texttt{./configure \&\& make \&\& make install} or CMake
523 \item Support for Perl, Python, Ruby, GNOME, KDE, Java, Haskell, \ldots
528 \item Introduced in 2005, based on advanced \textsl{GNU make} magic
529 \item Documentation: \texttt{/usr/share/doc/cdbs/}
530 \item But some people hate it:
532 \item Sometimes difficult to customize package builds:\\
533 "\textsl{twisty maze of makefiles, environment vars and black magic}"
534 \item Slower than plain debhelper (many useless calls to \texttt{dh\_*})
536 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
538 include /usr/share/cdbs/1/rules/debhelper.mk
539 include /usr/share/cdbs/1/class/autotools.mk
541 # add an action after the build
543 /bin/bash debian/scripts/foo.sh
549 \begin{frame}[fragile]{Dh (aka Debhelper 7, or dh7)}
551 \item Introduced in 2008 as a \textsl{CDBS killer}
553 \item \textbf{dh} command that calls \texttt{dh\_*}
555 \item Simple \textsl{debian/rules}, listing only overrides
557 \item Easier to customize than CDBS
559 \item Doc: manpages (\texttt{debhelper(7)}, \texttt{dh(1)}) + slides from DebConf'9 talk\\
560 \url{http://kitenet.net/~joey/talks/debhelper/debhelper-slides.pdf}
562 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
567 override_dh_auto_configure:
568 dh_auto_configure -- --with-kitchen-sink
570 override_dh_auto_build:
577 \begin{frame}{Classic debhelper vs CDBS vs dh}
580 \item Market shares: (feb'11)\\
581 Classic debhelper: 45\% \hskip 1em CDBS: 24\% \hskip 1em dh: 29\%
583 \item Which one should I learn?
585 \item Probably all of them
586 \item You need to know debhelper to use dh and CDBS
587 \item You might have to modify CDBS packages
590 \item Which one should I use for a new package?
592 \item \textbf{dh} (only solution with an increasing market share)
599 \begin{axis}[small,label style={font=\footnotesize},xlabel={\small Time},ylabel={\small Market share (\%)},
600 date coordinates in=x,height=4.85cm,width=9cm,xticklabel={\month/\year},
601 legend style={font=\footnotesize,at={(1.02,1)},anchor=north west},max space between ticks=82,try min ticks=5,ymin=0]
602 \addplot[mark=none,blue,thick] table[x=date,y=dh] {cdbs-dh7.txt};
603 \addplot[mark=none,red,thick] table[x=date,y=dh7] {cdbs-dh7.txt};
604 \addplot[mark=none,green,thick] table[x=date,y=cdbs] {cdbs-dh7.txt};
605 \legend{debhelper, dh, CDBS}
612 \section{Building and testing packages}
613 \subsection{Building packages}
614 \begin{frame}{Building packages}
616 \item \textttc{apt-get build-dep mypackage}\\
617 Installs the \textsl{build-dependencies} (for a package in the archive)
620 \item \textttc{debuild}: build, test with \texttt{lintian}, sign with GPG
622 \item Also possible to call \textttc{dpkg-buildpackage} directly
624 \item Usually with \texttt{dpkg-buildpackage -us -uc}
627 \item It is better to build packages in a clean \& minimal environment
629 \item \textttc{pbuilder} -- helper to build packages in a \textsl{chroot}\\
630 Good documentation: \url{https://wiki.ubuntu.com/PbuilderHowto}
632 \item \textttc{schroot} and \textttc{sbuild}: used on the Debian build daemons\\
633 (not as easy to use as \texttt{pbuilder})
636 \item Generate \texttt{.deb} files and a \texttt{.changes} file
638 \item \texttt{.changes}: describes what was built ; used to upload the package
642 \subsection{Installing and testing packages}
643 \begin{frame}{Installing and testing packages}
645 \item Install the package locally: \textttc{debi} (will use \texttt{.changes}
646 to know what to install) \br
647 \item List the content of the package: \texttt{{\color{rouge}debc}
648 ../mypackage<TAB>.changes} \br
649 \item Compare the package with a previous version:\\
650 \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.changes ../mypackage\_2\_*.changes}\\
651 or to compare the sources:\\
652 \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.dsc ../mypackage\_2\_*.dsc}\\
654 \item Check the package with \texttt{lintian} (static analyzer):\\
655 \texttt{{\color{rouge}lintian} ../mypackage<TAB>.changes}\\
656 \texttt{lintian -i}: gives more information about the errors \br
657 \item Upload the package to Debian (\textttc{dput}) (needs configuration) \br
658 \item Manage a private Debian archive with \textttc{reprepro}\\
659 Documentation: \url{http://mirrorer.alioth.debian.org/}
662 \section{Practical session 1: modifying the grep package}
663 \begin{frame}{Practical session 1: modifying the grep package}
665 \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
666 download version 2.6.3-3 of the package
667 \item Look at the files in \texttt{debian/}.
669 \item How many binary packages are generated by this source package?
670 \item Which packaging helper does this package use?
672 \item Build the package
673 \item We are now going to modify the package. Add a changelog entry and increase the version number.
674 \item Now disable perl-regexp support (it is a \texttt{./configure} option)
675 \item Rebuild the package
676 \item Compare the original and the new package with debdiff
677 \item Install the newly built package
678 \item Cry if you messed up ;)
682 \section{Advanced packaging topics}
683 \subsection{Modifying the upstream source}
684 \begin{frame}{Modifying the upstream source}
687 \item Fix bugs or add customizations that are specific to Debian
689 \item Backport fixes from a newer upstream release
692 Several methods to do it:
694 \item Modifying the files directly
697 \item But no way to track and document the changes
700 \item Using patch systems
702 \item Eases contributing your changes to upstream
703 \item Helps sharing the fixes with derivatives
704 \item Gives more exposure to the changes\\
705 \url{http://patch-tracker.debian.org/}
710 \begin{frame}{Patch systems}
712 \item Principle: changes are stored as patches in \texttt{debian/patches/}
714 \item Applied and unapplied during build
716 \item Several implementations: \textsl{simple-patchsys} (\textsl{cdbs} only),
717 \textsl{dpatch}, \textbf{\textsl{quilt}} \hbr
718 \item Each supports two \texttt{debian/rules} targets:
720 \item \texttt{debian/rules patch}: apply all patches
721 \item \texttt{debian/rules unpatch}: de-apply all patches
724 \item More documentation: \url{http://wiki.debian.org/debian/patches}
727 Future: new source package format with built-in patch system: \textbf{3.0 (quilt)}
729 \item Recommended solution
730 \item You need to learn \textsl{quilt}\\
731 \url{http://pkg-perl.alioth.debian.org/howto/quilt.html}
736 \begin{frame}[fragile]{Documentation of patches}
738 \item Standard headers
740 \item Documented in DEP3 - Patch Tagging Guidelines\\
741 \url{http://dep.debian.net/deps/dep3/}
743 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
744 Description: Fix widget frobnication speeds
745 Frobnicating widgets too quickly tended to cause explosions.
746 Forwarded: http://lists.example.com/2010/03/1234.html
747 Author: John Doe <johndoe-guest@users.alioth.debian.org>
748 Applied-Upstream: 1.2, http://bzr.foo.com/frobnicator/revision/123
749 Last-Update: 2010-03-29
753 \subsection{Doing things during installation and removal}
754 \begin{frame}{Doing things during installation and removal}
756 \item Decompressing the package is sometimes not enough
758 \item Create/remove system users, start/stop services, manage \textsl{alternatives}
760 \item Done in \textsl{maintainer scripts}\\
761 \texttt{preinst, postinst, prerm, postrm}
765 \item Debian Policy Manual, chapter 6\\
766 {\footnotesize \url{http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html}}
769 \item Debian Developer's Reference, chapter 6.4\\
770 {\scriptsize \url{http://www.debian.org/doc/developers-reference/best-pkging-practices.html}}
772 \item {\footnotesize \url{http://people.debian.org/~srivasta/MaintainerScripts.html}}
775 \item Prompting the user
777 \item Must be done with \textbf{debconf}
779 \item Documentation: \texttt{debconf-devel(7)} (\texttt{debconf-doc} package)
784 \begin{frame}[fragile]{Monitoring upstream versions}
786 \item Specify where to look in \texttt{debian/watch} (see \texttt{uscan(1)})
787 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
790 http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
791 Twisted-([\d\.]*)\.tar\.bz2
794 \item Debian infrastructure that makes use of \texttt{debian/watch}:\\
795 \textbf{Debian External Health Status}\\
796 \url{http://dehs.alioth.debian.org/}
798 \item Maintainer warned by emails sent to the Packages Tracking System
800 \item \texttt{uscan}: run a manual check
802 \item \texttt{uupdate}: try to update your package to the latest upstream version
806 \subsection{Packaging with a VCS (SVN, Git \& friends)}
807 \begin{frame}[fragile]{Packaging with a VCS (SVN, Git \& friends)}
809 \item Several tools to help manage branches and tags for your packaging work:\\
810 \texttt{svn-buildpackage}, \texttt{git-buildpackage}
812 \item Example: \texttt{git-buildpackage}
814 \item \texttt{upstream} branch to track upstream with \texttt{upstream/\textsl{version}} tags
815 \item \texttt{master} branch tracks the Debian package
816 \item \texttt{debian/\textsl{version}} tags for each upload
817 \item \texttt{pristine-tar} branch to be able to rebuild the upstream tarball
820 \item \texttt{Vcs-*} fields in \texttt{debian/control} to locate the repository
822 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
823 Vcs-Browser: http://git.debian.org/?p=devscripts/devscripts.git
824 Vcs-Git: git://git.debian.org/devscripts/devscripts.git
826 Vcs-Browser: http://svn.debian.org/viewsvn/pkg-perl/trunk/libwww-perl/
827 Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
830 \item VCS-agnostic interface: \texttt{debcheckout}, \texttt{debcommit},
831 \texttt{debrelease}\\
832 \texttt{debcheckout devscripts} $\rightarrow$ check out the source package
837 \section{Maintaining packages in Debian}
838 \subsection{Several ways to contribute to Debian}
839 \begin{frame}{Several ways to contribute to Debian}
841 \item \textbf{Worst} way to contribute:
843 \item Package your own application
844 \item Get it into Debian
848 \item Bring new software to Debian
850 \item Only if it's interesting/useful enough, please
851 \item Are there alternatives already packaged in Debian?
854 \item Adopt existing unmaintained packages (\textsl{orphaned packages})
856 \item Many unmaintained packages in Debian
857 \item Including some that you use daily!
860 \item Get involved in packaging teams
862 \item Many teams that focus on set of packages, and need help
863 \item Full list on \url{http://wiki.debian.org/Teams}
864 \item An excellent way to work with more experienced contributors
869 \subsection{More interested in Ubuntu?}
870 \begin{frame}{More interested in Ubuntu?}
872 \item Ubuntu mainly manages the divergence with Debian
874 \item No real focus on specific packages\\
875 Instead, collaboration with Debian teams
877 \item Usually recommend uploading new packages to Debian first\\
878 \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages}
880 \item Possibly a better plan:
882 \item Get involved in a Debian team and act as a bridge with Ubuntu
884 \item Help reduce divergence, triage bugs in Launchpad
886 \item Many Debian tools can help:
888 \item Ubuntu column on the Developer' packages overview
889 \item Ubuntu box on the Packages Tracking System
890 \item Receive launchpad bugmail via the PTS
896 \subsection{Adopting orphaned packages}
897 \begin{frame}{Adopting orphaned packages}
899 \item Full list: \url{http://www.debian.org/devel/wnpp/}
901 \item Installed on your machine: \texttt{wnpp-alert}
903 \item Different states:
905 \item \textbf{O}rphaned: the package is unmaintained\\
906 Feel free to adopt it
907 \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
908 Maintainer looking for adopter, but continues work in the meantime\\
909 Feel free to adopt it. A mail to the current maintainer is polite
910 \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
911 Someone intends to adopt the package\\
912 You could propose your help!
913 \item \textbf{RFH}: (\textbf{R}equest \textbf{F}or \textbf{H}elp\\
914 The maintainer is looking for help
917 \item Some unmaintained packages not detected \arr not orphaned yet
919 \item When in doubt, ask \texttt{debian-qa@lists.debian.org} \\
920 or \texttt{\#debian-qa} on \texttt{irc.debian.org}
926 \subsection{Where to find help?}
927 \begin{frame}{Where to find help?}
930 \item Various advices and answers to your questions, code reviews
931 \item Sponsorship of your uploads, when your package is ready
934 You can get help from:
936 \item Other members of a packaging team: the best solution
938 \item They know the specifics of your package
939 \item You can become a member of the team
940 \item See \url{http://wiki.debian.org/Teams}
943 \item The Debian Mentors group (if your package doesn't fit in a team)
945 \item \url{http://wiki.debian.org/DebianMentorsFaq}
946 \item Mailing list: \url{debian-mentors@lists.debian.org}\\
947 {\small (also a good way to learn by accident)}
948 \item IRC: \texttt{\#debian-mentors} on \texttt{irc.debian.org}
949 \item \url{http://mentors.debian.net/}
954 \subsection{Official documentation}
955 \begin{frame}{Official documentation}
957 \item Debian Developers' Corner\\
958 \url{http://www.debian.org/devel/}\\
959 {\small Links to many resources about Debian development}
961 \item Debian New Maintainers' Guide\\
962 \url{http://www.debian.org/doc/maint-guide/}\\
963 {\small An introduction to Debian packaging, but could use an update}
965 \item Debian Developer's Reference\\
966 \url{http://www.debian.org/doc/developers-reference/}\\
967 {\small Mostly about Debian procedures, but also some best packaging practices (part 6)}
969 \item Debian Policy\\
970 \url{http://www.debian.org/doc/debian-policy/}\\
972 {\small \begin{itemize}
973 \item \small All the requirements that every package must satisfy
974 \item \small Specific policies for Perl, Java, Python, \ldots
978 \item Ubuntu Packaging Guide\\
979 \url{https://wiki.ubuntu.com/PackagingGuide}
983 \begin{frame}{Debian dashboards for maintainers}
985 \item \textbf{Source package centric}: Packages Tracking System\\
986 \url{http://packages.qa.debian.org/dpkg}
988 \item \textbf{Maintainer/team centric}: Developer's Packages Overview\\
989 \url{http://qa.debian.org/developer.php?login=pkg-ruby-extras-maintainers@lists.alioth.debian.org}
994 \subsection{Conclusion}
995 \begin{frame}{Conclusion}
997 \item You now have a full overview of Debian packaging
999 \item But you will need to read more documentation
1001 \item Best practices have evolved over the years
1003 \item If not sure, use the \textbf{dh} packaging helper, and the \textbf{3.0 (quilt)} format
1006 \item Debian is not only a technical project, it's also a community
1009 \centerline{\large Feedback: \textbf{lucas@debian.org}}
1012 \centerline{\includegraphics[height=2.8cm]{figs/debconf10}}
1015 \subsection{Legal stuff}
1016 \begin{frame}{Legal stuff}
1018 Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
1022 \textbf{This document is free software}: you can redistribute it and/or modify
1023 it under either (at your option):
1026 \item The terms of the GNU General Public License as published by the Free
1027 Software Foundation, either version 3 of the License, or
1028 (at your option) any later version.\\
1029 \url{http://www.gnu.org/licenses/gpl.html} \br
1030 \item The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported
1032 \url{http://creativecommons.org/licenses/by-sa/3.0/}
1037 \subsection{Latest version \& source code}
1038 \begin{frame}{Latest version \& source code}
1040 \item Latest version:\\
1041 {\footnotesize \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git;a=blob\_plain;f=packaging-tutorial.pdf;hb=refs/heads/pdf}}
1046 \texttt{git clone git://git.debian.org/\~{}lucas/packaging-tutorial.git}\\
1048 Or over HTTP: \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git}
1050 \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
1054 \section{Practical session 2: packaging GNUjump}
1055 \begin{frame}{Practical session 2: packaging GNUjump}
1057 \item Download GNUjump 1.0.6 from
1058 \url{http://ftp.gnu.org/gnu/gnujump/1.0.6/gnujump-1.0.6.tar.gz}
1060 \item Create a Debian package for it
1062 \item Install build-dependencies so that you can build the package
1063 \item Get a basic working package
1064 \item Finish filling \texttt{debian/control} and other files
1069 \centerline{\includegraphics[width=5cm]{gnujump.png}}
1072 \section{Practical session 3: packaging a Java library}
1073 \begin{frame}{Practical session 3: packaging a Java library}
1075 \item Take a quick look at some documentation about Java packaging:\\
1077 \item \url{http://wiki.debian.org/Java}
1078 \item \url{http://wiki.debian.org/Java/Packaging}
1079 \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
1080 \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
1081 \item Paper and slides from a Debconf10 talk about javahelper:\\
1083 \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf}\\
1084 \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-slides.pdf}}
1087 \item Download IRClib from \url{http://moepii.sourceforge.net/}
1097 \centerline{\Huge Bonus slides}
1101 \begin{frame}{Debian branches (or \textsl{suites}, \textsl{components})}
1103 \item \textbf{stable} (currently codenamed \textbf{squeeze}): stable and
1104 supported. Only important bug fixes. \br
1105 \item \textbf{testing} (currently codenamed \textbf{wheezy}): the future
1107 \item \textbf{unstable} (always codenamed \textbf{sid}): where most of the
1108 work occurs, and where packages are uploaded. Packages migrate
1109 automatically from \textsl{unstable} to \textsl{testing} according to some
1110 rules (no new critical bug, at least 10 days spent in \textsl{unstable}, etc.) \br
1111 \item \textbf{experimental}: for experimental packages that are not suited
1112 for a stable release.
1115 Developers mostly run \textsl{unstable} or \textsl{testing} (with
1116 \textsl{APT pinning}) \hbr
1118 Packages can be \textbf{backported} from \textsl{testing/unstable} to
1119 \textsl{stable}. See \url{http://backports.debian.org/}