1 \documentclass[10pt,final]{beamer}
6 %change debiantutorial to debiantutorial.$lang to use translated file, and
7 %append to this string all commands to load localisation packages, e.g.:
8 %\\usepackage{debiantutorial.fr} \\usepackage[french]{babel} \\frenchsetup{...}
9 \usepackage{debiantutorial}
11 \hypersetup{bookmarks}
12 \title{Debian Packaging Tutorial}
13 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
16 %leave \\version unchanged: this will a variable containing the actual version
17 %To translate the date, use \\today or a string containing \\year, \\month, \\day
19 \date{\footnotesize version 0.5 -- 2012-01-14} % DATE - use debian/rules update-version-date
26 \begin{frame}{About this tutorial}
28 \item Goal: \textbf{tell you what you really need to know about Debian packaging}
31 \item Modify existing packages
33 \item Create your own packages
35 \item Interact with the Debian community
37 \item Become a Debian power-user
40 \item Covers the most important points, but is not complete
42 \item You will need to read more documentation
45 \item Most of the content also applies to Debian derivatives distributions
48 \item That includes Ubuntu
53 \begin{frame}{Outline}
54 \tableofcontents[hideallsubsections]
57 \section{Introduction}
63 \item \textbf{GNU/Linux distribution}
65 \item 1st major distro developed ``openly in the spirit of GNU''
67 \item \textbf{Non-commercial}, built collaboratively by over 1,000 volunteers
69 \item 3 main features:
71 \item \textbf{Quality} -- culture of technical excellence\\
72 {\small\sl We release when it's ready}
74 \item \textbf{Freedom} -- devs and users bound by the \textsl{Social Contract}\\
75 Promoting the culture of Free Software since 1993
77 \item \textbf{Independence} -- no (single) company babysitting Debian\\
78 And open decision-making process (\textsl{do-ocracy} + \textsl{democracy})
81 \item \textbf{Amateur} in the best sense: done for the love of it
85 \subsection{Debian packages}
86 \begin{frame}{Debian packages}
88 \item \textbf{.deb} files (binary packages)
90 \item A very powerful and convenient way to distribute software to users
92 \item One of the two most common packages format (with RPM)
96 \item 30,000 binary packages in Debian\\
97 $\rightarrow$ most of the available free software is packaged in Debian!
99 \item For 12 ports (architectures), including 2 non-Linux (Hurd; KFreeBSD)
101 \item Also used by 120 Debian derivatives distributions
107 \subsection{The Deb package format}
109 \begin{frame}[fragile]{The Deb package format}
111 \item \texttt{.deb} file: an \texttt{ar} archive
112 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
113 $ ar tv wget_1.12-2.1_i386.deb
114 rw-r--r-- 0/0 4 Sep 5 15:43 2010 debian-binary
115 rw-r--r-- 0/0 2403 Sep 5 15:43 2010 control.tar.gz
116 rw-r--r-- 0/0 751613 Sep 5 15:43 2010 data.tar.gz
119 \item \texttt{debian-binary}: version of the deb file format, \texttt{"2.0\textbackslash{}n"}
120 \item \texttt{control.tar.gz}: metadata about the package\\
121 {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
122 \item \texttt{data.tar.gz}: data files of the package
125 \item You could create your \texttt{.deb} files manually\\
126 {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
128 \item But most people don't do it that way
131 \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
134 \subsection{Tools you will need}
135 \begin{frame}{Tools you will need}
137 \item A Debian (or Ubuntu) system (with root access)
141 \item \textbf{build-essential}: has dependencies on the packages that will
142 be assumed to be available on the developers' machine (no need to specify
143 them in the \texttt{Build-Depends:} control field of your package)
145 \item includes a dependency on \textbf{dpkg-dev}, which contains basic
146 Debian-specific tools to create packages
149 \item \textbf{devscripts}: contains many useful scripts for Debian
155 Many other tools will also be mentioned later, such as \textbf{debhelper},
156 \textbf{cdbs}, \textbf{quilt}, \textbf{pbuilder}, \textbf{sbuild},
157 \textbf{lintian}, \textbf{svn-buildpackage}, \textbf{git-buildpackage},
159 Install them when you need them.
162 \subsection{General packaging workflow}
163 \begin{frame}{General packaging workflow}
166 node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
167 arr/.style={very thick}, command/.style={text=rouge,font=\ttfamily}, ]
169 \node[node1] (www) at (0, 0) {Web};
170 \node[node1] (us) at (2.5, 0) {upstream source};
171 \node[node1] (da) at (-2.5, 0) {Debian mirror};
172 \node[node1] (sp) at (0, -2) {source package};
173 \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};
174 \node[node1] (bin) at (0, -4) {one or several binary packages};
175 \draw[arr,<-,dashed,thick] (bin) -- (3.5,-4) node[right,text centered,font=\small\ttfamily\sl] {.deb\normalfont};
176 \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
177 \draw[arr,->] (da) -- (sp) node[pos=0.5,left,command] {apt-get source};
178 \draw[arr,->] (www) -- (sp) node[pos=0.5,left,command] {dget};
179 \draw[arr,->] (sp) -- (bin) node[pos=0.5,right,text width=6cm] {\textttc{debuild} (build and test with \textttc{lintian}) or \textttc{dpkg-buildpackage}};
180 \draw[arr,->] (bin) -- (1,-6) node[pos=0.5,right] {install (\textttc{debi})};
181 % \draw[arr,->] (bin) -- (-1,-6) node[pos=0.5,left] {upload (\textttc{dput})};
182 \draw[transparent] (bin) -- (-1,-6) node[pos=0.5,left,opaque] {upload (\textttc{dput})};
183 \draw[arr,->,rounded corners] (bin) -- (-1,-6) -- (-4.5,-6) -- (-4.5,0) -- (da);
184 \useasboundingbox (-4,-6) rectangle (6,0); % hack hack hack
189 \subsection{Rebuilding dash}
190 \begin{frame}{Example: rebuilding dash}
192 \item Install packages needed to build dash, and devscripts\\
193 {\texttt{sudo apt-get build-dep dash}\\ (requires \texttt{deb-src} lines in \texttt{/etc/apt/sources.list})}\\
194 {\texttt{sudo apt-get install -{}-no-install-recommends devscripts}}
196 \item Create a working directory, and get in it:\\
197 \texttt{mkdir /tmp/debian-tutorial ; cd /tmp/debian-tutorial}
199 \item Grab the \texttt{dash} source package\\
200 \texttt{apt-get source dash}\\
201 {\small (This needs you to have \texttt{deb-src} lines in your \texttt{/etc/apt/sources.list})}
203 \item Build the package\\
204 {\texttt{cd dash-*\\ debuild -us -uc}} ~~~(\texttt{-us -uc} disables signing the package with GPG)
207 \item Check that it worked
209 \item There are some new \texttt{.deb} files in the parent directory
212 \item Look at the \texttt{debian/} directory
214 \item That's where the packaging work is done
219 \section{Creating source packages}
220 \subsection{Source packages basics}
221 \begin{frame}{Source package}
223 \item One source package can generate several binary packages\\
224 {\small e.g the \texttt{\bfseries libtar} source generates the
225 \texttt{\bfseries libtar0} and \texttt{\bfseries libtar-dev} binary
227 \item Two kinds of packages: (if unsure, use non-native)
230 \item Native packages: normally for Debian specific software (\textsl{dpkg}, \textsl{apt})
231 \item Non-native packages: software developed outside Debian
234 \item Main file: \texttt{.dsc} (meta-data)
236 \item Other files depending on the version of the source format
238 \item 1.0 -- native: \texttt{package\_version.tar.gz}
240 \item 1.0 -- non-native:
242 \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
243 \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
248 \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
249 \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
254 (See \texttt{dpkg-source(1)} for exact details)
257 \begin{frame}[fragile]{Source package example (wget\_1.12-2.1.dsc)}
258 \begin{lstlisting}[basicstyle=\ttfamily\small]
264 Maintainer: Noel Kothe <noel@debian.org>
265 Homepage: http://www.gnu.org/software/wget/
266 Standards-Version: 3.8.4
267 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
268 libssl-dev (>= 0.9.8), dpatch, info2man
270 50d4ed2441e67[..]1ee0e94248 2464747 wget_1.12.orig.tar.gz
271 d4c1c8bbe431d[..]dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
273 7578ed0974e12[..]dcba65b572 2464747 wget_1.12.orig.tar.gz
274 1e9b0c4c00eae[..]89c402ad78 48308 wget_1.12-2.1.debian.tar.gz
276 141461b9c04e4[..]9d1f2abf83 2464747 wget_1.12.orig.tar.gz
277 e93123c934e3c[..]2f380278c2 48308 wget_1.12-2.1.debian.tar.gz
281 \subsection{Retrieving source packages}
282 \begin{frame}{Retrieving an existing source package}
284 \item From the Debian archive:
286 \item \texttt{apt-get source \textsl{package}}
287 \item \texttt{apt-get source \textsl{package=version}}
288 \item \texttt{apt-get source \textsl{package/release}}
290 (You need \texttt{deb-src} lines in \texttt{sources.list})
292 \item From the Internet:
294 \item \texttt{dget \textsl{url-to.dsc}}
295 \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\
297 (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
300 \item From the (declared) version control system:
302 \item \texttt{debcheckout \textsl{package}}
305 \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
309 \subsection{Creating a basic source package}
310 \begin{frame}{Creating a basic source package}
312 \item Download the upstream source\\
313 (\textsl{upstream source} = the one from the software's original developers)
315 \item Rename to \texttt{<\textsl{source\_package}>\_<\textsl{upstream\_version}>.orig.tar.gz}\\
316 (example: \texttt{simgrid\_3.6.orig.tar.gz})
320 \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
322 \item There are some alternatives to \texttt{dh\_make} for specific sets of
323 packages: \textbf{dh-make-perl}, \textbf{dh-make-php}, \ldots \hbr
324 \item \texttt{debian/} directory created, with a lot of files in it
328 \subsection{Files in debian/}
329 \begin{frame}{Files in debian/}
330 All the packaging work should be made by modifying files in \texttt{debian/}
335 \item \textbf{control} -- meta-data about the package (dependencies, etc)
336 \item \textbf{rules} -- specifies how to build the package
337 \item \textbf{copyright} -- copyright information for the package
338 \item \textbf{changelog} -- history of the Debian package
345 \item dh\_install* targets\\
346 {\small *.dirs, *.docs, *.manpages, \ldots}
347 \item maintainer scripts\\
348 {\small *.postinst, *.prerm, \ldots}
350 \item patches/ -- if you need to modify the upstream sources
353 \item Several files use a format based on RFC 822 (mail headers)
357 \begin{frame}[fragile]{debian/changelog}
359 \item Lists the Debian packaging changes
360 \item Gives the current version of the package
363 \draw (0,0) node[above right] {\large 1.2.1.1-5};
364 \draw [decorate,decoration={brace}] (2,0) -- (1.45,0) node[at start,below,text width=1.6cm,text centered] {\small Debian revision};
365 \draw [decorate,decoration={brace}] (1.4,0) -- (0,0) node[midway,below,text width=1.6cm,text centered] { \small Upstream version};
371 \item Edited manually or with \texttt{dch}
372 \item Special format to automatically close Debian or Ubuntu bugs\\
373 Debian: \texttt{Closes:~\#595268}; Ubuntu: \texttt{LP:~\#616929}
374 \item Installed as \texttt{/usr/share/doc/\textit{package}/changelog.Debian.gz}
377 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
378 mpich2 (1.2.1.1-5) unstable; urgency=low
380 * Use /usr/bin/python instead of /usr/bin/python2.5. Allow
381 to drop dependency on python2.5. Closes: #595268
382 * Make /usr/bin/mpdroot setuid. This is the default after
383 the installation of mpich2 from source, too. LP: #616929
384 + Add corresponding lintian override.
386 -- Lucas Nussbaum <lucas@debian.org> Wed, 15 Sep 2010 18:13:44 +0200
390 \begin{frame}[fragile]{debian/control}
393 \item Package metadata
395 \item For the source package itself
396 \item For each binary package built from this source
399 \item Package name, section, priority, maintainer, uploaders,
400 build-dependencies, dependencies, description, homepage, \ldots \hbr
401 \item Documentation: Debian Policy chapter 5\\
402 \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
405 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
409 Maintainer: Noel Kothe <noel@debian.org>
410 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
411 libssl-dev (>= 0.9.8), dpatch, info2man
412 Standards-Version: 3.8.4
413 Homepage: http://www.gnu.org/software/wget/
417 Depends: ${shlibs:Depends}, ${misc:Depends}
418 Description: retrieves files from the web
419 Wget is a network utility to retrieve files from the Web
423 \begin{frame}{Architecture: all or any}
424 Two kinds of binary packages:
427 \item Packages with different contents on each Debian architecture
429 \item Example: C program
430 \item \texttt{Architecture:\ any} in \texttt{debian/control}
432 \item Or, if it only works on a subset of architectures:\\
433 \texttt{Architecture:\ amd64 i386 ia64 hurd-i386}
435 \item buildd.debian.org: builds all the other architectures for you on upload
436 \item Named \texttt{\textsl{package}\_\textsl{version}\_\textsl{architecture}.deb}
439 \item Packages with the same content on all architectures
441 \item Example: Perl library
442 \item \texttt{Architecture:\ all} in \texttt{debian/control}
443 \item Named \texttt{\textsl{package}\_\textsl{version}\_\textbf{all}.deb}
447 A source package can generate a mix of \texttt{Architecture:\ any} and \texttt{Architecture:\ all} binary packages
450 \begin{frame}[fragile]{debian/rules}
455 \item Interface used to build Debian packages
457 \item Documented in Debian Policy, chapter 4.8\\
458 {\small \texttt{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
460 \item Five required targets:
462 \item \texttt{build}: should perform all the configuration and compilation
464 \item \texttt{binary, binary-arch, binary-indep}: build the binary packages
466 \item \texttt{dpkg-buildpackage} will call \texttt{binary} to build all
467 the packages, or \texttt{binary-arch} to build only the
468 \texttt{Architecture:~any} packages
471 \item \texttt{clean}: clean up the source directory
476 \subsection{Packaging helpers}
477 \begin{frame}{Packaging helpers -- debhelper}
479 \item You could write shell code in \texttt{debian/rules} directly
481 \item See the \texttt{adduser} package for example
484 \item Better practice (used by most packages): use a \textsl{Packaging helper}
486 \item Most popular one: \textbf{debhelper} (used by 98\% of packages)
490 \item Factor the common tasks in standard tools used by all packages
491 \item Fix some packaging bugs once for all packages
493 {\footnotesize dh\_installdirs, dh\_installchangelogs, dh\_installdocs,
494 dh\_installexamples, dh\_install, dh\_installdebconf, dh\_installinit,
495 dh\_link, dh\_strip, dh\_compress, dh\_fixperms, dh\_perl,
496 dh\_makeshlibs, dh\_installdeb, dh\_shlibdeps, dh\_gencontrol,
497 dh\_md5sums, dh\_builddeb, \ldots}
499 \item Called from \texttt{debian/rules}
500 \item Configurable using command parameters or files in \texttt{debian/}
502 {\footnotesize \ttfamily \textsl{package}.docs, \textsl{package}.examples,
503 \textsl{package}.install, \textsl{package}.manpages, \ldots} \hbr
504 \item Third-party helpers for sets of packages: \textbf{python-support},
505 \textbf{dh\_ocaml}, \ldots \hbr
506 \item Gotcha: \texttt{debian/compat}: Debhelper compatibility version (use "7")
510 \begin{frame}[fragile]{debian/rules using debhelper (1/2)}
511 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize,escapeinside=\{\}]
514 # Uncomment this to turn on verbose mode.
519 #docbook-to-man debian/packagename.sgml > packagename.1
524 rm -f build-stamp configure-stamp
533 # Add here commands to install the package into debian/packagename.
534 $(MAKE) DESTDIR=$(CURDIR)/debian/packagename install
538 \begin{frame}[fragile]{debian/rules using debhelper (2/2)}
539 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize,escapeinside=\{\}]
541 # Build architecture-independent files here.
542 binary-indep: build install
544 # Build architecture-dependent files here.
545 binary-arch: build install
563 binary: binary-indep binary-arch
564 .PHONY: build clean binary-indep binary-arch binary install configure
568 \begin{frame}[fragile]{CDBS}
571 \item With debhelper, still a lot of redundancy between packages
573 \item Second-level helpers that factor common functionality
575 \item E.g building with \texttt{./configure \&\& make \&\& make install} or CMake
580 \item Introduced in 2005, based on advanced \textsl{GNU make} magic
581 \item Documentation: \texttt{/usr/share/doc/cdbs/}
582 \item Support for Perl, Python, Ruby, GNOME, KDE, Java, Haskell, \ldots
583 \item But some people hate it:
585 \item Sometimes difficult to customize package builds:\\
586 "\textsl{twisty maze of makefiles and environment variables}"
587 \item Slower than plain debhelper (many useless calls to \texttt{dh\_*})
592 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize,escapeinside=\{\}]
594 include /usr/share/cdbs/1/rules/debhelper.mk
595 include /usr/share/cdbs/1/class/autotools.mk
597 # add an action after the build
599 /bin/bash debian/scripts/foo.sh
603 \begin{frame}[fragile]{Dh (aka Debhelper 7, or dh7)}
605 \item Introduced in 2008 as a \textsl{CDBS killer}
607 \item \textbf{dh} command that calls \texttt{dh\_*}
609 \item Simple \textsl{debian/rules}, listing only overrides
611 \item Easier to customize than CDBS
613 \item Doc: manpages (\texttt{debhelper(7)}, \texttt{dh(1)}) + slides from DebConf9 talk\\
614 \url{http://kitenet.net/~joey/talks/debhelper/debhelper-slides.pdf}
617 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
622 override_dh_auto_configure:
623 dh_auto_configure -- --with-kitchen-sink
625 override_dh_auto_build:
631 \begin{frame}{Classic debhelper vs CDBS vs dh}
635 Classic debhelper: 36\% \hskip 1em CDBS: 21\% \hskip 1em dh: 41\%
637 \item Which one should I learn?
639 \item Probably a bit of all of them
640 \item You need to know debhelper to use dh and CDBS
641 \item You might have to modify CDBS packages
644 \item Which one should I use for a new package?
646 \item \textbf{dh} (only solution with an increasing mind share)
653 \begin{axis}[small,label style={font=\footnotesize},xlabel={\small Time},ylabel={\small Market share (\%)},
654 date coordinates in=x,height=4.85cm,width=9cm,xticklabel={\month/\year},
655 legend style={font=\footnotesize,at={(1.02,1)},anchor=north west},max space between ticks=82,try min ticks=5,ymin=0]
656 \addplot[mark=none,blue,thick,style=densely dotted] table[x=date,y=dh] {cdbs-dh7.txt};
657 \addplot[mark=none,red,thick,style=dashed] table[x=date,y=dh7] {cdbs-dh7.txt};
658 \addplot[mark=none,green,thick] table[x=date,y=cdbs] {cdbs-dh7.txt};
659 \legend{debhelper, dh, CDBS}
666 \section{Building and testing packages}
667 \subsection{Building packages}
668 \begin{frame}{Building packages}
670 \item \textttc{apt-get build-dep mypackage}\\
671 Installs the \textsl{build-dependencies} (for a package in the archive)
674 \item \textttc{debuild}: build, test with \texttt{lintian}, sign with GPG
676 \item Also possible to call \textttc{dpkg-buildpackage} directly
678 \item Usually with \texttt{dpkg-buildpackage -us -uc}
681 \item It is better to build packages in a clean \& minimal environment
683 \item \textttc{pbuilder} -- helper to build packages in a \textsl{chroot}\\
684 Good documentation: \url{https://wiki.ubuntu.com/PbuilderHowto}\\
685 (optimization: \textttc{cowbuilder} \textttc{ccache} \textttc{distcc})
687 \item \textttc{schroot} and \textttc{sbuild}: used on the Debian build daemons\\
688 (not as simple as \texttt{pbuilder}, but allows LVM snapshots\\
689 see: \url{https://help.ubuntu.com/community/SbuildLVMHowto} )
692 \item Generates \texttt{.deb} files and a \texttt{.changes} file
694 \item \texttt{.changes}: describes what was built; used to upload the package
698 \subsection{Installing and testing packages}
699 \begin{frame}{Installing and testing packages}
701 \item Install the package locally: \textttc{debi} (will use \texttt{.changes}
702 to know what to install) \br
703 \item List the content of the package: \texttt{{\color{rouge}debc}
704 ../mypackage<TAB>.changes} \br
705 \item Compare the package with a previous version:\\
706 \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.changes ../mypackage\_2\_*.changes}\\
707 or to compare the sources:\\
708 \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.dsc ../mypackage\_2\_*.dsc}\\
710 \item Check the package with \texttt{lintian} (static analyzer):\\
711 \texttt{{\color{rouge}lintian} ../mypackage<TAB>.changes}\\
712 \texttt{lintian -i}: gives more information about the errors \br
713 \item Upload the package to Debian (\textttc{dput}) (needs configuration) \br
714 \item Manage a private Debian archive with \textttc{reprepro}\\
715 Documentation: \url{http://mirrorer.alioth.debian.org/}
718 \section{Practical session 1: modifying the grep package}
719 \begin{frame}{Practical session 1: modifying the grep package}
721 \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
722 download version 2.6.3-3 of the package (if you use Ubuntu 11.10 or
723 later, or Debian testing or unstable, use version 2.9-1 or 2.9-2 instead)
725 \item Look at the files in \texttt{debian/}.
727 \item How many binary packages are generated by this source package?
728 \item Which packaging helper does this package use?
731 \item Build the package
733 \item We are now going to modify the package. Add a changelog entry and increase the version number.
735 \item Now disable perl-regexp support (it is a \texttt{./configure} option)
737 \item Rebuild the package
739 \item Compare the original and the new package with debdiff
741 \item Install the newly built package
743 \item Cry if you messed up ;)
747 \section{Advanced packaging topics}
748 \subsection{debian/copyright}
749 \begin{frame}[fragile]{debian/copyright}
752 \item Copyright and license information for the source and the packaging
753 \item Traditionally written as a text file
754 \item New machine-readable format: \url{http://dep.debian.net/deps/dep5/}
757 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
758 Format: <VERSIONED_FORMAT_URL>
759 Upstream-Name: X Solitaire
760 Source: ftp://ftp.example.com/pub/games
763 Copyright: Copyright 1998 John Doe <jdoe@example.com>
765 This program is free software; you can redistribute it
768 On Debian systems, the full text of the GNU General Public
769 License version 2 can be found in the file
770 `/usr/share/common-licenses/GPL-2'.
773 Copyright: Copyright 1998 Jane Smith <jsmith@example.net>
781 \subsection{Modifying the upstream source}
782 \begin{frame}{Modifying the upstream source}
785 \item Fix bugs or add customizations that are specific to Debian
787 \item Backport fixes from a newer upstream release
790 Several methods to do it:
792 \item Modifying the files directly
795 \item But no way to track and document the changes
798 \item Using patch systems
800 \item Eases contributing your changes to upstream
801 \item Helps sharing the fixes with derivatives
802 \item Gives more exposure to the changes\\
803 \url{http://patch-tracker.debian.org/}
808 \begin{frame}{Patch systems}
810 \item Principle: changes are stored as patches in \texttt{debian/patches/}
812 \item Applied and unapplied during build
814 \item Past: several implementations -- \textsl{simple-patchsys} (\textsl{cdbs}),
815 \textsl{dpatch}, \textbf{\textsl{quilt}}
817 \item Each supports two \texttt{debian/rules} targets:
819 \item \texttt{debian/rules patch}: apply all patches
820 \item \texttt{debian/rules unpatch}: de-apply all patches
823 \item More documentation: \url{http://wiki.debian.org/debian/patches}
826 \item \textbf{New source package format with built-in patch system: 3.0 (quilt)}
828 \item Recommended solution
830 \item You need to learn \textsl{quilt}\\
831 \url{http://pkg-perl.alioth.debian.org/howto/quilt.html}
833 \item Patch-system-agnostic tool in \texttt{devscripts}: \texttt{edit-patch}
838 \begin{frame}[fragile]{Documentation of patches}
840 \item Standard headers at the beginning of the patch
842 \item Documented in DEP-3 - Patch Tagging Guidelines\\
843 \url{http://dep.debian.net/deps/dep3/}
847 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
848 Description: Fix widget frobnication speeds
849 Frobnicating widgets too quickly tended to cause explosions.
850 Forwarded: http://lists.example.com/2010/03/1234.html
851 Author: John Doe <johndoe-guest@users.alioth.debian.org>
852 Applied-Upstream: 1.2, http://bzr.foo.com/frobnicator/revision/123
853 Last-Update: 2010-03-29
857 @@ -101,9 +101,6 @@ struct {
861 \subsection{Doing things during installation and removal}
862 \begin{frame}{Doing things during installation and removal}
864 \item Decompressing the package is sometimes not enough
866 \item Create/remove system users, start/stop services, manage \textsl{alternatives}
868 \item Done in \textsl{maintainer scripts}\\
869 \texttt{preinst, postinst, prerm, postrm}
871 \item Snippets for common actions can be generated by debhelper
876 \item Debian Policy Manual, chapter 6\\
877 {\footnotesize \url{http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html}}
880 \item Debian Developer's Reference, chapter 6.4\\
881 {\scriptsize \url{http://www.debian.org/doc/developers-reference/best-pkging-practices.html}}
883 \item {\footnotesize \url{http://people.debian.org/~srivasta/MaintainerScripts.html}}
886 \item Prompting the user
888 \item Must be done with \textbf{debconf}
890 \item Documentation: \texttt{debconf-devel(7)} (\texttt{debconf-doc} package)
895 \begin{frame}[fragile]{Monitoring upstream versions}
897 \item Specify where to look in \texttt{debian/watch} (see \texttt{uscan(1)})
898 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
901 http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
902 Twisted-([\d\.]*)\.tar\.bz2
905 \item Debian infrastructure that makes use of \texttt{debian/watch}:\\
906 \textbf{Debian External Health Status}\\
907 \url{http://dehs.alioth.debian.org/}
909 \item Maintainer warned by emails sent to the Package Tracking System\\
910 \url{http://packages.qa.debian.org/}
912 \item \texttt{uscan}: run a manual check
914 \item \texttt{uupdate}: try to update your package to the latest upstream version
918 \subsection{Packaging with a VCS (SVN, Git \& friends)}
919 \begin{frame}[fragile]{Packaging with a VCS (SVN, Git, etc.)}
921 \item Several tools to help manage branches and tags for your packaging work:\\
922 \texttt{svn-buildpackage}, \texttt{git-buildpackage}
924 \item Example: \texttt{git-buildpackage}
926 \item \texttt{upstream} branch to track upstream with \texttt{upstream/\textsl{version}} tags
927 \item \texttt{master} branch tracks the Debian package
928 \item \texttt{debian/\textsl{version}} tags for each upload
929 \item \texttt{pristine-tar} branch to be able to rebuild the upstream tarball
932 \item \texttt{Vcs-*} fields in \texttt{debian/control} to locate the repository
934 \item \url{http://wiki.debian.org/Alioth/Git}
935 \item \url{http://wiki.debian.org/Alioth/Svn}
938 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
939 Vcs-Browser: http://git.debian.org/?p=devscripts/devscripts.git
940 Vcs-Git: git://git.debian.org/devscripts/devscripts.git
942 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
943 Vcs-Browser: http://svn.debian.org/viewsvn/pkg-perl/trunk/libwww-perl/
944 Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
947 \item VCS-agnostic interface: \texttt{debcheckout}, \texttt{debcommit},
948 \texttt{debrelease}\\
950 \item \texttt{debcheckout grep} $\rightarrow$ checks out the source package
956 \subsection{Backporting packages}
957 \begin{frame}{Backporting packages}
959 \item Goal: use a newer version of a package on an older system\\
960 e.g use \textsl{mutt} from Debian \textsl{unstable} on Debian \textsl{stable}
964 \item Take the source package from Debian unstable
966 \item Modify it so that it builds and works fine on Debian stable
968 \item Sometimes trivial (no changes needed)
969 \item Sometimes difficult
970 \item Sometimes impossible (many unavailable dependencies)
974 \item Some backports are provided and supported by the Debian project\\
975 \url{http://backports.debian.org/}
981 \section{Maintaining packages in Debian}
982 \subsection{Several ways to contribute to Debian}
983 \begin{frame}{Several ways to contribute to Debian}
985 \item \textbf{Worst} way to contribute:
987 \item Package your own application
988 \item Get it into Debian
992 \item \textbf{Better} ways to contribute:
994 \item Get involved in packaging teams
996 \item Many teams that focus on set of packages, and need help
997 \item List available at \url{http://wiki.debian.org/Teams}
998 \item An excellent way to learn from more experienced contributors
1001 \item Adopt existing unmaintained packages (\textsl{orphaned packages})
1003 \item Bring new software to Debian
1005 \item Only if it's interesting/useful enough, please
1006 \item Are there alternatives already packaged in Debian?
1013 \subsection{Adopting orphaned packages}
1014 \begin{frame}{Adopting orphaned packages}
1017 \item Many unmaintained packages in Debian
1019 \item Full list + process: \url{http://www.debian.org/devel/wnpp/}
1021 \item Installed on your machine: \texttt{wnpp-alert}
1023 \item Different states:
1026 \item \textbf{O}rphaned: the package is unmaintained\\
1027 Feel free to adopt it
1029 \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
1030 Maintainer looking for adopter, but continues work in the meantime\\
1031 Feel free to adopt it. A mail to the current maintainer is polite
1033 \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
1034 Someone intends to adopt the package\\
1035 You could propose your help!
1037 \item \textbf{RFH}: \textbf{R}equest \textbf{F}or \textbf{H}elp\\
1038 The maintainer is looking for help
1041 \item Some unmaintained packages not detected \arr not orphaned yet
1043 \item When in doubt, ask \texttt{debian-qa@lists.debian.org} \\
1044 or \texttt{\#debian-qa} on \texttt{irc.debian.org}
1048 \subsection{Getting your package in Debian}
1049 \begin{frame}{Getting your package in Debian}
1051 \item You do not need any official status to get your package into Debian
1053 \item Prepare a source package
1055 \item Find a Debian Developer that will sponsor your package
1058 \item Official status (when you are already experienced):
1060 \item \textbf{Debian Maintainer (DM):}\\
1061 Permission to upload your own packages\\
1062 See \url{http://wiki.debian.org/DebianMaintainer}
1064 \item \textbf{Debian Developer (DD):}\\
1065 Debian project members; can vote and upload any package
1070 \subsection{Where to find help?}
1071 \begin{frame}{Where to find help?}
1074 \item Advice and answers to your questions, code reviews
1075 \item Sponsorship for your uploads, once your package is ready
1078 You can get help from:
1080 \item \textbf{Other members of a packaging team}
1082 \item They know the specifics of your package
1083 \item You can become a member of the team
1086 \item The Debian Mentors group (if your package doesn't fit in a team)
1088 \item \url{http://wiki.debian.org/DebianMentorsFaq}
1089 \item Mailing list: \url{debian-mentors@lists.debian.org}\\
1090 {\small (also a good way to learn by accident)}
1091 \item IRC: \texttt{\#debian-mentors} on \texttt{irc.debian.org}
1092 \item \url{http://mentors.debian.net/}
1097 \subsection{Official documentation}
1098 \begin{frame}{Official documentation}
1100 \item Debian Developers' Corner\\
1101 \url{http://www.debian.org/devel/}\\
1102 {\small Links to many resources about Debian development}
1104 \item Debian New Maintainers' Guide\\
1105 \url{http://www.debian.org/doc/maint-guide/}\\
1106 {\small An introduction to Debian packaging, but could use an update}
1108 \item Debian Developer's Reference\\
1109 \url{http://www.debian.org/doc/developers-reference/}\\
1110 {\small Mostly about Debian procedures, but also some best packaging practices (part 6)}
1112 \item Debian Policy\\
1113 \url{http://www.debian.org/doc/debian-policy/}\\
1115 {\small \begin{itemize}
1116 \item \small All the requirements that every package must satisfy
1117 \item \small Specific policies for Perl, Java, Python, \ldots
1121 \item Ubuntu Packaging Guide\\
1122 \url{https://wiki.ubuntu.com/PackagingGuide}
1126 \begin{frame}{Debian dashboards for maintainers}
1128 \item \textbf{Source package centric}: Package Tracking System (PTS)\\
1129 \url{http://packages.qa.debian.org/dpkg}
1131 \item \textbf{Maintainer/team centric}: Developer's Packages Overview (DDPO)\\
1132 \url{http://qa.debian.org/developer.php?login=pkg-ruby-extras-maintainers@lists.alioth.debian.org}
1136 \subsection{More interested in Ubuntu?}
1137 \begin{frame}{More interested in Ubuntu?}
1139 \item Ubuntu mainly manages the divergence with Debian
1141 \item No real focus on specific packages\\
1142 Instead, collaboration with Debian teams
1144 \item Usually recommend uploading new packages to Debian first\\
1145 \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages}
1147 \item Possibly a better plan:
1149 \item Get involved in a Debian team and act as a bridge with Ubuntu
1151 \item Help reduce divergence, triage bugs in Launchpad
1153 \item Many Debian tools can help:
1155 \item Ubuntu column on the Developer's packages overview
1156 \item Ubuntu box on the Package Tracking System
1157 \item Receive launchpad bugmail via the PTS
1163 \section{Conclusion}
1164 \subsection{Conclusion}
1165 \begin{frame}{Conclusion}
1167 \item You now have a full overview of Debian packaging
1169 \item But you will need to read more documentation
1171 \item Best practices have evolved over the years
1173 \item If not sure, use the \textbf{dh} packaging helper, and the \textbf{3.0 (quilt)} format
1176 \item Things that were not covered in this tutorial:
1178 \item UCF -- manage user changes to configuration files when upgrading
1180 \item dpkg triggers -- group similar maintainer scripts actions together
1182 \item Debian development organization:
1184 \item Bug Tracking System (BTS)
1185 \item Suites: stable, testing, unstable, experimental, security, *-updates, backports, \ldots
1186 \item Debian Blends -- subsets of Debian targeting specific groups
1191 \centerline{\large Feedback: \textbf{lucas@debian.org}}
1194 \subsection{Legal stuff}
1195 \begin{frame}{Legal stuff}
1197 Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
1201 \textbf{This document is free software}: you can redistribute it and/or modify
1202 it under either (at your option):
1205 \item The terms of the GNU General Public License as published by the Free
1206 Software Foundation, either version 3 of the License, or
1207 (at your option) any later version.\\
1208 \url{http://www.gnu.org/licenses/gpl.html} \br
1209 \item The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported
1211 \url{http://creativecommons.org/licenses/by-sa/3.0/}
1216 \subsection{Latest version \& source code}
1217 \begin{frame}{Latest version \& source code}
1219 \item Latest version:\\
1220 {\footnotesize \url{http://git.debian.org/?p=collab-maint/packaging-tutorial.git;a=blob\_plain;f=packaging-tutorial.pdf;hb=refs/heads/pdf}}
1226 \item {\small \texttt{git clone\\ git://git.debian.org/collab-maint/packaging-tutorial.git}}
1228 \item {\small \texttt{apt-get source packaging-tutorial}}
1230 \item {\small \url{http://git.debian.org/?p=collab-maint/packaging-tutorial.git}}
1233 \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
1237 \section{Practical session 2: packaging GNUjump}
1238 \begin{frame}{Practical session 2: packaging GNUjump}
1240 \item Download GNUjump 1.0.6 from
1241 \url{http://ftp.gnu.org/gnu/gnujump/1.0.6/gnujump-1.0.6.tar.gz}
1243 \item Create a Debian package for it
1245 \item Install build-dependencies so that you can build the package
1246 \item Get a basic working package
1247 \item Finish filling \texttt{debian/control} and other files
1252 \centerline{\includegraphics[width=5cm]{figs/gnujump.png}}
1255 \section{Practical session 3: packaging a Java library}
1256 \begin{frame}{Practical session 3: packaging a Java library}
1258 \item Take a quick look at some documentation about Java packaging:\\
1260 \item \url{http://wiki.debian.org/Java}
1262 \item \url{http://wiki.debian.org/Java/Packaging}
1264 \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
1266 \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
1268 \item Paper and slides from a Debconf10 talk about javahelper:\\
1270 \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf}\\
1271 \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-slides.pdf}}
1274 \item Download IRClib from \url{http://moepii.sourceforge.net/}
1280 \section{Practical session 4: packaging a Ruby gem}
1281 \begin{frame}{Practical session 4: packaging a Ruby gem}
1283 \item Take a quick look at some documentation about Ruby packaging:\\
1285 \item \url{http://wiki.debian.org/Ruby}
1287 \item \url{http://wiki.debian.org/Teams/Ruby}
1289 \item \url{http://wiki.debian.org/Teams/Ruby/Packaging}
1291 \item \texttt{gem2deb(1)}, \texttt{dh\_ruby(1)} (in the \texttt{gem2deb} package)
1294 \item Create a basic Debian source package from the \texttt{net-ssh} gem:\\
1295 \texttt{gem2deb net-ssh}
1297 \item Improve it so that it becomes a proper Debian package
1301 \section{Answers to practical sessions}
1305 \LARGE Answers to\\[0.5em] practical sessions
1310 \subsection{Practical session 1: modifying the grep package}
1312 \begin{frame}{Practical session 1: modifying the grep package}
1314 \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
1315 download version 2.6.3-3 of the package (if you use Ubuntu 11.10 or
1316 later, or Debian testing or unstable, use version 2.9-1 or 2.9-2 instead)
1318 \item Look at the files in \texttt{debian/}.
1320 \item How many binary packages are generated by this source package?
1321 \item Which packaging helper does this package use?
1324 \item Build the package
1326 \item We are now going to modify the package. Add a changelog entry and increase the version number.
1328 \item Now disable perl-regexp support (it is a \texttt{./configure} option)
1330 \item Rebuild the package
1332 \item Compare the original and the new package with debdiff
1334 \item Install the newly built package
1336 \item Cry if you messed up ;)
1340 \begin{frame}{Fetching the source}
1342 \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
1343 download version 2.6.3-3 of the package
1346 \item Use dget to download the \texttt{.dsc} file:\\
1347 {\small \texttt{dget http://cdn.debian.net/debian/pool/main/g/grep/grep\_2.6.3-3.dsc}}
1349 \item According to \texttt{http://packages.qa.debian.org/grep}, \texttt{grep} version 2.6.3-3 is currently in \textsl{stable} (\textsl{squeeze}). If you have \texttt{deb-src} lines for \textsl{squeeze} in your \texttt{/etc/apt/sources.list}, you can use:\\
1350 \texttt{apt-get source grep=2.6.3-3}\\
1351 or \texttt{apt-get source grep/stable}\\
1352 or, if you feel lucky: \texttt{apt-get source grep}
1354 \item The \texttt{grep} source package is composed of three files:
1356 \item \texttt{grep\_2.6.3-3.dsc}
1357 \item \texttt{grep\_2.6.3-3.debian.tar.bz2}
1358 \item \texttt{grep\_2.6.3.orig.tar.bz2}
1360 This is typical of the "3.0 (quilt)" format.
1362 \item If needed, uncompress the source with\\
1363 \texttt{dpkg-source -x grep\_2.6.3-3.dsc}
1367 \begin{frame}{Looking around and building the package}
1369 \setcounter{enumi}{1}
1370 \item Look at the files in \texttt{debian/}.
1372 \item How many binary packages are generated by this source package?
1373 \item Which packaging helper does this package use?
1378 \item According to \texttt{debian/control}, this package only generates one binary package, named \texttt{grep}.
1380 \item According to \texttt{debian/rules}, this package is typical of \textsl{classic} debhelper packaging, without using \textsl{CDBS} or \textsl{dh}. One can see the various calls to \texttt{dh\_*} commands in \texttt{debian/rules}.
1384 \setcounter{enumi}{2}
1386 \item Build the package
1390 \item Use \texttt{apt-get build-dep grep} to fetch the build-dependencies
1391 \item Then \texttt{debuild} or \texttt{dpkg-buildpackage -us -uc} (Takes about 1 min)
1395 \begin{frame}{Editing the changelog}
1397 \setcounter{enumi}{3}
1399 \item We are now going to modify the package. Add a changelog entry and increase the version number.
1403 \item \texttt{debian/changelog} is a text file. You could edit it and add a new entry manually.
1405 \item Or you can use \texttt{dch -i}, which will add an entry and open the editor
1407 \item The name and email can be defined using the \texttt{DEBFULLNAME} and \texttt{DEBEMAIL} environment variables
1409 \item After that, rebuild the package: a new version of the package is built
1411 \item Package versioning is detailed in section 5.6.12 of the Debian policy\\
1412 \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
1416 \begin{frame}{Disabling Perl regexp support and rebuilding}
1418 \setcounter{enumi}{4}
1420 \item Now disable perl-regexp support (it is a \texttt{./configure} option)
1421 \item Rebuild the package
1425 \item Check with \texttt{./configure -{}-help}: the option to disable
1426 Perl regexp is \texttt{-{}-disable-perl-regexp}
1428 \item Edit \texttt{debian/rules} and find the \texttt{./configure} line
1430 \item Add \texttt{-{}-disable-perl-regexp}
1432 \item Rebuild with \texttt{debuild} or \texttt{dpkg-buildpackage -us -uc}
1436 \begin{frame}{Comparing and testing the packages}
1438 \setcounter{enumi}{6}
1440 \item Compare the original and the new package with debdiff
1441 \item Install the newly built package
1445 \item Compare the binary packages: \texttt{debdiff ../*changes}
1447 \item Compare the source packages: \texttt{debdiff ../*dsc}
1449 \item Install the newly built package: \texttt{debi}\\
1450 Or \texttt{dpkg -i ../grep\_<TAB>}
1452 \item \texttt{grep -P foo} no longer works!
1456 \setcounter{enumi}{8}
1457 \item Cry if you messed up ;)
1460 Or not: reinstall the previous version of the package:
1462 \item \texttt{apt-get install -{}-reinstall grep=2.6.3-3} \textit{(= previous version)}
1466 \subsection{Practical session 2: packaging GNUjump}
1467 \begin{frame}{Practical session 2: packaging GNUjump}
1469 \item Download GNUjump 1.0.6 from
1470 \url{http://ftp.gnu.org/gnu/gnujump/1.0.6/gnujump-1.0.6.tar.gz}
1472 \item Create a Debian package for it
1474 \item Install build-dependencies so that you can build the package
1475 \item Get a basic working package
1476 \item Finish filling \texttt{debian/control} and other files
1481 \centerline{\includegraphics[width=5cm]{figs/gnujump.png}}
1484 \begin{frame}[fragile]{Step by step\ldots}
1486 \item \texttt{wget http://ftp.gnu.org/gnu/gnujump/1.0.6/gnujump-1.0.6.tar.gz}
1488 \item \texttt{mv gnujump-1.0.6.tar.gz gnujump\_1.0.6.orig.tar.gz}
1490 \item \texttt{tar xf gnujump\_1.0.6.orig.tar.gz}
1492 \item \texttt{cd gnujump-1.0.6/}
1494 \item \texttt{dh\_make}
1496 \item \small Type of package: single binary (for now)
1499 \begin{lstlisting}[basicstyle=\ttfamily\small]
1500 gnujump-1.0.6$ ls debian/
1501 changelog gnujump.default.ex preinst.ex
1502 compat gnujump.doc-base.EX prerm.ex
1503 control init.d.ex README.Debian
1504 copyright manpage.1.ex README.source
1505 docs manpage.sgml.ex rules
1506 emacsen-install.ex manpage.xml.ex source
1507 emacsen-remove.ex menu.ex watch.ex
1508 emacsen-startup.ex postinst.ex
1509 gnujump.cron.d.ex postrm.ex
1513 \begin{frame}[fragile]{Step by step\ldots (2)}
1515 \item Look at \texttt{debian/changelog}, \texttt{debian/rules}, \texttt{debian/control}\\
1516 (auto-filled by \textbf{dh\_make})
1518 \item In \texttt{debian/control}:\\
1519 \texttt{Build-Depends: debhelper (>= 7.0.50~), autotools-dev}\\
1520 Lists the \textsl{build-dependencies} = packages needed to build the package
1522 \item Try to build the package as-is (thanks to \textbf{dh} magic)
1524 \item And add build-dependencies, until it builds
1525 \item Hint: use \texttt{apt-cache search} and \texttt{apt-file} to find the packages
1527 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
1528 checking for sdl-config... no
1529 checking for SDL - version >= 1.2.0... no
1531 configure: error: *** SDL version 1.2.0 not found!
1533 $\rightarrow$ Add \textbf{libsdl1.2-dev} to Build-Depends and install it.
1535 \item Better: use \textbf{pbuilder} to build in a clean environment
1540 \begin{frame}{Step by step\ldots (3)}
1542 \item After installing \texttt{libsdl1.2-dev, libsdl-image1.2-dev, libsdl-mixer1.2-dev}, the package builds fine.
1544 \item Use \texttt{debc} to list the content of the generated package.
1546 \item Use \texttt{debi} to install it and test it.
1548 \item Fill in \texttt{debian/control} using \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
1550 \item Test the package with \texttt{lintian}
1552 \item Remove the files that you don't need in \texttt{debian/}
1554 \item Compare your package with the one already packaged in Debian:
1556 \item It splits the data files to a second package, that is the same across all architectures ($\rightarrow$ saves space in the Debian archive)
1557 \item It installs a .desktop file (for the GNOME/KDE menus) and also integrates into the Debian menu
1558 \item It fixes a few minor problems using patches
1563 \subsection{Practical session 3: packaging a Java library}
1564 \begin{frame}{Practical session 3: packaging a Java library}
1566 \item Take a quick look at some documentation about Java packaging:\\
1568 \item \url{http://wiki.debian.org/Java}
1570 \item \url{http://wiki.debian.org/Java/Packaging}
1572 \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
1574 \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
1576 \item Paper and slides from a Debconf10 talk about javahelper:\\
1578 \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf}\\
1579 \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-slides.pdf}}
1582 \item Download IRClib from \url{http://moepii.sourceforge.net/}
1588 \begin{frame}{Step by step\ldots}
1590 \item \texttt{apt-get install javahelper}
1592 \item Create a basic source package: \texttt{jh\_makepkg}
1596 \item Default Free compiler/runtime
1599 \item Look at and fix \texttt{debian/*}
1601 \item \texttt{dpkg-buildpackage -us -uc} or \texttt{debuild}
1603 \item \texttt{lintian}, \texttt{debc}, etc.
1605 \item Compare your result with the \texttt{libirclib-java} source package
1609 \subsection{Practical session 4: packaging a Ruby gem}
1610 \begin{frame}{Practical session 4: packaging a Ruby gem}
1612 \item Take a quick look at some documentation about Ruby packaging:\\
1614 \item \url{http://wiki.debian.org/Ruby}
1616 \item \url{http://wiki.debian.org/Teams/Ruby}
1618 \item \url{http://wiki.debian.org/Teams/Ruby/Packaging}
1620 \item \texttt{gem2deb(1)}, \texttt{dh\_ruby(1)} (in the \texttt{gem2deb} package)
1623 \item Create a basic Debian source package from the \texttt{net-ssh} gem:\\
1624 \texttt{gem2deb net-ssh}
1626 \item Improve it so that it becomes a proper Debian package
1630 \begin{frame}{Step by step\ldots}
1631 \texttt{gem2deb net-ssh}:
1633 \item Downloads the gem from rubygems.org
1634 \item Creates a suitable .orig.tar.gz archive, and untar it
1635 \item Initializes a Debian source package based on the gem's metadata
1637 \item Named \texttt{ruby-\textsl{gemname}}
1639 \item Tries to build the Debian binary package (this might fail)
1642 \texttt{dh\_ruby} (included in \textsl{gem2deb}) does the Ruby-specific tasks:
1644 \item Build C extensions for each Ruby version
1645 \item Copy files to their destination directory
1646 \item Update shebangs in executable scripts
1647 \item Run tests defined in \texttt{debian/ruby-tests.rb} or \texttt{debian/ruby-test-files.yaml}, as well as various other checks
1651 \begin{frame}[fragile]{Step by step\ldots (2)}
1652 Improve the generated package:
1654 \item Run \texttt{debclean} to clean the source tree. Look at \texttt{debian/}.
1656 \item \texttt{changelog} and \texttt{compat} should be correct
1658 \item Edit \texttt{debian/control}: uncomment \texttt{Homepage}, improve \texttt{Description}
1660 \item Write a proper \texttt{copyright} file based on the upstream files
1662 \item \texttt{ruby-net-ssh.docs}: install \texttt{README.rdoc}
1664 \item \texttt{ruby-tests.rb}: run the tests. In that case, it is enough to do:\\
1665 \verb+$: << 'test' << 'lib' << '.'+\\
1666 \verb+require 'test/test_all.rb'+
1670 \begin{frame}[fragile]{Step by step\ldots (3)}
1672 It fails to build. There are two problems:
1674 \item You need to disable the \texttt{gem} call in the test suite.\\
1675 In \texttt{test/common.rb}, remove the \verb+gem "test-unit"+ line:
1677 \item \texttt{edit-patch disable-gem.patch}
1678 \item Edit \texttt{test/common.rb}, remove the \texttt{gem} line. Exit the sub-shell
1679 \item Describe the changes in \texttt{debian/changelog}
1680 \item Document the patch in \texttt{debian/patches/disable-gem.patch}
1684 \item The package lacks a build-dependency on \texttt{ruby-mocha},
1685 which is used by the test suite (you might need to build your
1686 package in a clean environment, using \texttt{pbuilder}, to
1687 reproduce that problem)
1690 \item Add \texttt{ruby-mocha} to the package's \texttt{Build-Depends}
1692 \item \textsl{gem2deb} copies the dependencies
1693 documented in the \textsl{gem} as comments in
1694 \texttt{debian/control}, but \textsl{mocha} is
1695 not listed as a development dependency by the
1696 gem (that's a bug in the gem)
1700 Compare your package with the \texttt{ruby-net-ssh} package in the Debian archive