packaging-tutorial.tex

   1 \documentclass[10pt,final]{beamer}
   2 \mode<presentation>
   3 \usetheme{debian}
   4
   5 %Translators:
   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}
  10
  11 \hypersetup{bookmarks}
  12 \title{Debian Packaging Tutorial}
  13 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
  14
  15 %Translators:
  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
  18 %(numeric values).
  19 \date{\footnotesize version 0.5 -- 2012-01-14} % DATE - use debian/rules update-version-date
  20
  21 \begin{document}
  22
  23
  24 \frame{\titlepage}
  25
  26 \begin{frame}{About this tutorial}
  27   \begin{itemize}
  28   \item Goal: \textbf{tell you what you really need to know about Debian packaging}
  29     \begin{itemize}
  30       \hbr
  31     \item Modify existing packages
  32       \hbr
  33     \item Create your own packages
  34             \hbr
  35     \item Interact with the Debian community
  36       \hbr
  37     \item Become a Debian power-user
  38     \end{itemize}
  39     \br
  40   \item Covers the most important points, but is not complete
  41     \begin{itemize}
  42     \item You will need to read more documentation
  43     \end{itemize}
  44     \br
  45   \item Most of the content also applies to Debian derivatives distributions
  46     \begin{itemize}
  47       \hbr
  48     \item That includes Ubuntu
  49     \end{itemize}
  50   \end{itemize}
  51 \end{frame}
  52
  53 \begin{frame}{Outline}
  54   \tableofcontents[hideallsubsections]
  55 \end{frame}
  56
  57 \section{Introduction}
  58
  59 \subsection{Debian}
  60
  61 \begin{frame}{Debian}
  62         \begin{itemize}
  63                 \item \textbf{GNU/Linux distribution}
  64                         \br
  65                 \item 1st major distro developed ``openly in the spirit of GNU''
  66                         \br
  67                 \item \textbf{Non-commercial}, built collaboratively by over 1,000 volunteers
  68                         \br
  69                 \item 3 main features:
  70                         \begin{itemize}
  71                                 \item \textbf{Quality} -- culture of technical excellence\\
  72                                         {\small\sl We release when it's ready}
  73                                         \hbr
  74                                 \item \textbf{Freedom} -- devs and users bound by the \textsl{Social Contract}\\
  75                                         Promoting the culture of Free Software since 1993
  76                                         \hbr
  77                                 \item \textbf{Independence} -- no (single) company babysitting Debian\\
  78                                         And open decision-making process (\textsl{do-ocracy} + \textsl{democracy})
  79                         \end{itemize}
  80                         \br
  81                 \item \textbf{Amateur} in the best sense: done for the love of it
  82         \end{itemize}
  83 \end{frame}
  84
  85 \subsection{Debian packages}
  86 \begin{frame}{Debian packages}
  87 \begin{itemize}
  88 \item \textbf{.deb} files (binary packages)
  89         \br
  90 \item A very powerful and convenient way to distribute software to users
  91         \br
  92 \item One of the two most common packages format (with RPM)
  93         \br
  94 \item Universal:
  95         \begin{itemize}
  96                 \item 30,000 binary packages in Debian\\
  97                         $\rightarrow$ most of the available free software is packaged in Debian!
  98                         \hbr
  99                 \item For 12 ports (architectures), including 2 non-Linux (Hurd; KFreeBSD)
 100                         \hbr
 101                 \item Also used by 120 Debian derivatives distributions
 102         \end{itemize}
 103 \end{itemize}
 104 \end{frame}
 105
 106
 107 \subsection{The Deb package format}
 108
 109 \begin{frame}[fragile]{The Deb package format}
 110   \begin{itemize}
 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
 117     \end{lstlisting} % $
 118     \begin{itemize}
 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
 123     \end{itemize}
 124     \br
 125   \item You could create your \texttt{.deb} files manually\\
 126     {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
 127     \br
 128   \item But most people don't do it that way
 129   \end{itemize}
 130   \br
 131   \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
 132 \end{frame}
 133
 134 \subsection{Tools you will need}
 135 \begin{frame}{Tools you will need}
 136   \begin{itemize}
 137   \item A Debian (or Ubuntu) system (with root access)
 138     \br
 139   \item Some packages:
 140     \begin{itemize}
 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)
 144       \begin{itemize}
 145       \item includes a dependency on \textbf{dpkg-dev}, which contains basic
 146         Debian-specific tools to create packages
 147       \end{itemize}
 148       \hbr
 149     \item \textbf{devscripts}: contains many useful scripts for Debian
 150       maintainers
 151     \end{itemize}
 152   \end{itemize}
 153
 154   \br
 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},
 158   \ldots\\
 159   Install them when you need them.
 160 \end{frame}
 161
 162 \subsection{General packaging workflow}
 163 \begin{frame}{General packaging workflow}
 164   \begin{center}
 165     \begin{tikzpicture}[
 166       node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
 167       arr/.style={very thick}, command/.style={text=rouge,font=\ttfamily}, ]
 168
 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
 185     \end{tikzpicture}
 186   \end{center}
 187 \end{frame}
 188
 189 \subsection{Rebuilding dash}
 190 \begin{frame}{Example: rebuilding dash}
 191 \begin{enumerate}
 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}}
 195   \hbr
 196 \item Create a working directory, and get in it:\\
 197  \texttt{mkdir /tmp/debian-tutorial ; cd /tmp/debian-tutorial}
 198   \hbr
 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})}
 202   \hbr
 203 \item Build the package\\
 204   {\texttt{cd dash-*\\ debuild -us -uc}} ~~~(\texttt{-us -uc} disables signing the package with GPG)
 205
 206   \hbr
 207 \item Check that it worked
 208         \begin{itemize}
 209                 \item  There are some new \texttt{.deb} files in the parent directory
 210         \end{itemize}
 211     \hbr
 212 \item Look at the \texttt{debian/} directory
 213         \begin{itemize}
 214                 \item That's where the packaging work is done
 215         \end{itemize}
 216 \end{enumerate}
 217 \end{frame}
 218
 219 \section{Creating source packages}
 220 \subsection{Source packages basics}
 221 \begin{frame}{Source package}
 222   \begin{itemize}
 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
 226       packages} \hbr
 227   \item Two kinds of packages: (if unsure, use non-native)
 228     \begin{itemize}
 229       \small
 230     \item Native packages: normally for Debian specific software (\textsl{dpkg}, \textsl{apt})
 231     \item Non-native packages: software developed outside Debian
 232     \end{itemize}
 233     \hbr
 234   \item Main file: \texttt{.dsc} (meta-data)
 235     \hbr
 236   \item Other files depending on the version of the source format
 237     \begin{itemize}
 238     \item 1.0 -- native: \texttt{package\_version.tar.gz}
 239       \hbr
 240     \item 1.0 -- non-native:
 241       \begin{itemize}
 242       \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
 243       \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
 244       \end{itemize}
 245       \hbr
 246     \item 3.0 (quilt):
 247       \begin{itemize}
 248       \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
 249       \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
 250       \end{itemize}
 251     \end{itemize}
 252   \end{itemize}
 253   \hbr
 254   (See \texttt{dpkg-source(1)} for exact details)
 255 \end{frame}
 256
 257 \begin{frame}[fragile]{Source package example (wget\_1.12-2.1.dsc)}
 258   \begin{lstlisting}[basicstyle=\ttfamily\small]
 259 Format: 3.0 (quilt)
 260 Source: wget
 261 Binary: wget
 262 Architecture: any
 263 Version: 1.12-2.1
 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
 269 Checksums-Sha1:
 270  50d4ed2441e67[..]1ee0e94248 2464747 wget_1.12.orig.tar.gz
 271  d4c1c8bbe431d[..]dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
 272 Checksums-Sha256:
 273  7578ed0974e12[..]dcba65b572 2464747 wget_1.12.orig.tar.gz
 274  1e9b0c4c00eae[..]89c402ad78 48308 wget_1.12-2.1.debian.tar.gz
 275 Files:
 276  141461b9c04e4[..]9d1f2abf83 2464747 wget_1.12.orig.tar.gz
 277  e93123c934e3c[..]2f380278c2 48308 wget_1.12-2.1.debian.tar.gz
 278 \end{lstlisting}
 279 \end{frame}
 280
 281 \subsection{Retrieving source packages}
 282 \begin{frame}{Retrieving an existing source package}
 283   \begin{itemize}
 284   \item From the Debian archive:
 285     \begin{itemize}
 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}}
 289     \end{itemize}
 290     (You need \texttt{deb-src} lines in \texttt{sources.list})
 291     \br
 292   \item From the Internet:
 293     \begin{itemize}
 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/\\
 296         wget\_1.4.4-6.dsc}\\
 297       (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
 298     \end{itemize}
 299     \br
 300   \item From the (declared) version control system:
 301     \begin{itemize}
 302     \item \texttt{debcheckout \textsl{package}}
 303     \end{itemize}
 304     \br
 305   \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
 306   \end{itemize}
 307 \end{frame}
 308
 309 \subsection{Creating a basic source package}
 310 \begin{frame}{Creating a basic source package}
 311   \begin{itemize}
 312   \item Download the upstream source\\
 313     (\textsl{upstream source} = the one from the software's original developers)
 314     \hbr
 315   \item Rename to \texttt{<\textsl{source\_package}>\_<\textsl{upstream\_version}>.orig.tar.gz}\\
 316     (example: \texttt{simgrid\_3.6.orig.tar.gz})
 317     \hbr
 318   \item Untar it
 319     \hbr
 320   \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
 321     \hbr
 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
 325   \end{itemize}
 326 \end{frame}
 327
 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/}
 331   \hbr
 332   \begin{itemize}
 333   \item Main files:
 334     \begin{itemize}
 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
 339     \end{itemize}
 340     \hbr
 341   \item Other files:
 342     \begin{itemize}
 343     \item compat
 344     \item watch
 345     \item dh\_install* targets\\
 346       {\small *.dirs, *.docs, *.manpages, \ldots}
 347     \item maintainer scripts\\
 348       {\small *.postinst, *.prerm, \ldots}
 349     \item source/format
 350     \item patches/ -- if you need to modify the upstream sources
 351     \end{itemize}
 352     \hbr
 353   \item Several files use a format based on RFC 822 (mail headers)
 354   \end{itemize}
 355 \end{frame}
 356
 357 \begin{frame}[fragile]{debian/changelog}
 358   \begin{itemize}
 359   \item Lists the Debian packaging changes
 360   \item Gives the current version of the package
 361   \begin{center}
 362     \begin{tikzpicture}
 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};
 366 \end{tikzpicture}
 367 \end{center}
 368
 369
 370           %%
 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}
 375   \end{itemize}
 376   \seprule
 377   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 378 mpich2 (1.2.1.1-5) unstable; urgency=low
 379
 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.
 385
 386  -- Lucas Nussbaum <lucas@debian.org>  Wed, 15 Sep 2010 18:13:44 +0200
 387 \end{lstlisting}
 388 \end{frame}
 389
 390 \begin{frame}[fragile]{debian/control}
 391   \hbr
 392   \begin{itemize}
 393   \item Package metadata
 394     \begin{itemize}
 395     \item For the source package itself
 396     \item For each binary package built from this source
 397     \end{itemize}
 398     \hbr
 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}
 403   \end{itemize}
 404   \seprule
 405 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 406 Source: wget
 407 Section: web
 408 Priority: important
 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/
 414
 415 Package: wget
 416 Architecture: any
 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
 420 \end{lstlisting}
 421 \end{frame}
 422
 423 \begin{frame}{Architecture: all or any}
 424   Two kinds of binary packages:
 425   \hbr
 426   \begin{itemize}
 427   \item Packages with different contents on each Debian architecture
 428     \begin{itemize}
 429     \item Example: C program
 430     \item \texttt{Architecture:\ any} in \texttt{debian/control}
 431       \begin{itemize}
 432       \item Or, if it only works on a subset of architectures:\\
 433         \texttt{Architecture:\ amd64 i386 ia64 hurd-i386}
 434       \end{itemize}
 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}
 437     \end{itemize}
 438     \br
 439   \item Packages with the same content on all architectures
 440     \begin{itemize}
 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}
 444     \end{itemize}
 445   \end{itemize}
 446   \br
 447   A source package can generate a mix of \texttt{Architecture:\ any} and \texttt{Architecture:\ all} binary packages
 448 \end{frame}
 449
 450 \begin{frame}[fragile]{debian/rules}
 451   \hbr
 452   \begin{itemize}
 453   \item Makefile
 454     \br
 455   \item Interface used to build Debian packages
 456     \br
 457   \item Documented in Debian Policy, chapter 4.8\\
 458     {\small \texttt{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
 459     \br
 460   \item Five required targets:
 461     \begin{itemize}
 462     \item \texttt{build}: should perform all the configuration and compilation
 463       \hbr
 464     \item \texttt{binary, binary-arch, binary-indep}: build the binary packages
 465       \begin{itemize}
 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
 469       \end{itemize}
 470       \hbr
 471     \item \texttt{clean}: clean up the source directory
 472     \end{itemize}
 473   \end{itemize}
 474 \end{frame}
 475
 476 \subsection{Packaging helpers}
 477 \begin{frame}{Packaging helpers -- debhelper}
 478   \begin{itemize}
 479   \item You could write shell code in \texttt{debian/rules} directly
 480     \begin{itemize}
 481     \item See the \texttt{adduser} package for example
 482     \end{itemize}
 483     \hbr
 484   \item Better practice (used by most packages): use a \textsl{Packaging helper}
 485     \hbr
 486   \item Most popular one: \textbf{debhelper} (used by 98\% of packages)
 487     \hbr
 488   \item Goals:
 489     \begin{itemize}
 490     \item Factor the common tasks in standard tools used by all packages
 491     \item Fix some packaging bugs once for all packages
 492     \end{itemize}
 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}
 498     \begin{itemize}
 499     \item Called from \texttt{debian/rules}
 500     \item Configurable using command parameters or files in \texttt{debian/}
 501     \end{itemize}
 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")
 507   \end{itemize}
 508 \end{frame}
 509
 510 \begin{frame}[fragile]{debian/rules using debhelper (1/2)}
 511   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize,escapeinside=\{\}]
 512 #!/usr/bin/make -f
 513
 514 # Uncomment this to turn on verbose mode.
 515 #export DH_VERBOSE=1
 516
 517 build:
 518         $(MAKE)
 519         #docbook-to-man debian/packagename.sgml > packagename.1
 520
 521 clean:
 522         dh_testdir
 523         dh_testroot
 524         rm -f build-stamp configure-stamp
 525         $(MAKE) clean
 526         dh_clean
 527
 528 install: build
 529         dh_testdir
 530         dh_testroot
 531         dh_clean -k
 532         dh_installdirs
 533         # Add here commands to install the package into debian/packagename.
 534         $(MAKE) DESTDIR=$(CURDIR)/debian/packagename install
 535 \end{lstlisting}
 536 \end{frame}
 537
 538 \begin{frame}[fragile]{debian/rules using debhelper (2/2)}
 539   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize,escapeinside=\{\}]
 540
 541 # Build architecture-independent files here.
 542 binary-indep: build install
 543
 544 # Build architecture-dependent files here.
 545 binary-arch: build install
 546         dh_testdir
 547         dh_testroot
 548         dh_installchangelogs
 549         dh_installdocs
 550         dh_installexamples
 551         dh_install
 552         dh_installman
 553         dh_link
 554         dh_strip
 555         dh_compress
 556         dh_fixperms
 557         dh_installdeb
 558         dh_shlibdeps
 559         dh_gencontrol
 560         dh_md5sums
 561         dh_builddeb
 562
 563 binary: binary-indep binary-arch
 564 .PHONY: build clean binary-indep binary-arch binary install configure
 565 \end{lstlisting}
 566 \end{frame}
 567
 568 \begin{frame}[fragile]{CDBS}
 569   \hbr
 570   \begin{itemize}
 571   \item With debhelper, still a lot of redundancy between packages
 572     \hbr
 573   \item Second-level helpers that factor common functionality
 574     \begin{itemize}
 575     \item E.g building with \texttt{./configure \&\& make \&\& make install} or CMake
 576     \end{itemize}
 577     \hbr
 578   \item CDBS:
 579     \begin{itemize}
 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:
 584       \begin{itemize}
 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\_*})
 588       \end{itemize}
 589     \end{itemize}
 590   \end{itemize}
 591   \seprule
 592       \begin{lstlisting}[basicstyle=\ttfamily\footnotesize,escapeinside=\{\}]
 593 #!/usr/bin/make -f
 594 include /usr/share/cdbs/1/rules/debhelper.mk
 595 include /usr/share/cdbs/1/class/autotools.mk
 596
 597 # add an action after the build
 598 build/mypackage::
 599     /bin/bash debian/scripts/foo.sh
 600       \end{lstlisting}
 601 \end{frame}
 602
 603 \begin{frame}[fragile]{Dh (aka Debhelper 7, or dh7)}
 604   \begin{itemize}
 605   \item Introduced in 2008 as a \textsl{CDBS killer}
 606     \hbr
 607   \item \textbf{dh} command that calls \texttt{dh\_*}
 608     \hbr
 609   \item Simple \textsl{debian/rules}, listing only overrides
 610     \hbr
 611   \item Easier to customize than CDBS
 612     \hbr
 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}
 615   \end{itemize}
 616   \seprule
 617     \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 618 #!/usr/bin/make -f
 619 %:
 620     dh $@
 621
 622 override_dh_auto_configure:
 623      dh_auto_configure -- --with-kitchen-sink
 624
 625 override_dh_auto_build:
 626      make world
 627
 628     \end{lstlisting}
 629 \end{frame}
 630
 631 \begin{frame}{Classic debhelper vs CDBS vs dh}
 632   \hbr
 633   \begin{itemize}
 634   \item Mind shares:\\
 635     Classic debhelper: 36\% \hskip 1em CDBS: 21\% \hskip 1em  dh: 41\%
 636     \hbr
 637   \item Which one should I learn?
 638     \begin{itemize}
 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
 642     \end{itemize}
 643     \hbr
 644   \item Which one should I use for a new package?
 645     \begin{itemize}
 646     \item \textbf{dh} (only solution with an increasing mind share)
 647     \end{itemize}
 648   \end{itemize}
 649
 650   \hbr
 651   \begin{center}
 652     \begin{tikzpicture}
 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}
 660 \end{axis}
 661 \end{tikzpicture}
 662 \end{center}
 663
 664 \end{frame}
 665
 666 \section{Building and testing packages}
 667 \subsection{Building packages}
 668 \begin{frame}{Building packages}
 669   \begin{itemize}
 670   \item \textttc{apt-get build-dep mypackage}\\
 671     Installs the \textsl{build-dependencies} (for a package in the archive)
 672
 673     \br
 674   \item \textttc{debuild}: build, test with \texttt{lintian}, sign with GPG
 675     \br
 676   \item Also possible to call \textttc{dpkg-buildpackage} directly
 677     \begin{itemize}
 678     \item Usually with \texttt{dpkg-buildpackage -us -uc}
 679     \end{itemize}
 680     \br
 681   \item It is better to build packages in a clean \& minimal environment
 682     \begin{itemize}
 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})
 686       \hbr
 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} )
 690     \end{itemize}
 691     \br
 692   \item Generates \texttt{.deb} files and a \texttt{.changes} file
 693     \begin{itemize}
 694     \item \texttt{.changes}: describes what was built; used to upload the package
 695     \end{itemize}
 696   \end{itemize}
 697 \end{frame}
 698 \subsection{Installing and testing packages}
 699 \begin{frame}{Installing and testing packages}
 700   \begin{itemize}
 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}\\
 709     \br
 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/}
 716   \end{itemize}
 717 \end{frame}
 718 \section{Practical session 1: modifying the grep package}
 719 \begin{frame}{Practical session 1: modifying the grep package}
 720   \begin{enumerate}
 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)
 724
 725   \item Look at the files in \texttt{debian/}.
 726     \begin{itemize}
 727     \item               How many binary packages are generated by this source package?
 728     \item               Which packaging helper does this package use?
 729     \end{itemize}
 730     \hbr
 731   \item Build the package
 732     \hbr
 733   \item We are now going to modify the package. Add a changelog entry and increase the version number.
 734     \hbr
 735   \item Now disable perl-regexp support (it is a \texttt{./configure} option)
 736     \hbr
 737   \item Rebuild the package
 738     \hbr
 739   \item Compare the original and the new package with debdiff
 740     \hbr
 741   \item Install the newly built package
 742     \hbr
 743   \item Cry if you messed up ;)
 744   \end{enumerate}
 745 \end{frame}
 746
 747 \section{Advanced packaging topics}
 748 \subsection{debian/copyright}
 749 \begin{frame}[fragile]{debian/copyright}
 750   \hbr
 751   \begin{itemize}
 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/}
 755   \end{itemize}
 756   \seprule
 757   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 758 Format: <VERSIONED_FORMAT_URL>
 759 Upstream-Name: X Solitaire
 760 Source: ftp://ftp.example.com/pub/games
 761
 762 Files: *
 763 Copyright: Copyright 1998 John Doe <jdoe@example.com>
 764 License: GPL-2+
 765  This program is free software; you can redistribute it
 766  [...]
 767  .
 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'.
 771
 772 Files: debian/*
 773 Copyright: Copyright 1998 Jane Smith <jsmith@example.net>
 774 License:
 775  [LICENSE TEXT]
 776 \end{lstlisting}
 777 \end{frame}
 778
 779
 780
 781 \subsection{Modifying the upstream source}
 782 \begin{frame}{Modifying the upstream source}
 783   Often needed:
 784   \begin{itemize}
 785   \item Fix bugs or add customizations that are specific to Debian
 786     \hbr
 787   \item Backport fixes from a newer upstream release
 788   \end{itemize}
 789   \br
 790   Several methods to do it:
 791   \begin{itemize}
 792   \item Modifying the files directly
 793     \begin{itemize}
 794     \item Simple
 795     \item But no way to track and document the changes
 796     \end{itemize}
 797     \hbr
 798   \item Using patch systems
 799     \begin{itemize}
 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/}
 804     \end{itemize}
 805   \end{itemize}
 806 \end{frame}
 807
 808 \begin{frame}{Patch systems}
 809   \begin{itemize}
 810   \item Principle: changes are stored as patches in \texttt{debian/patches/}
 811     \br
 812   \item Applied and unapplied during build
 813     \br
 814   \item Past: several implementations -- \textsl{simple-patchsys} (\textsl{cdbs}),
 815     \textsl{dpatch}, \textbf{\textsl{quilt}}
 816     \begin{itemize}
 817   \item Each supports two \texttt{debian/rules} targets:
 818     \begin{itemize}
 819     \item \texttt{debian/rules patch}: apply all patches
 820     \item \texttt{debian/rules unpatch}: de-apply all patches
 821     \end{itemize}
 822           \hbr
 823   \item More documentation: \url{http://wiki.debian.org/debian/patches}
 824   \end{itemize}
 825   \br
 826   \item \textbf{New source package format with built-in patch system: 3.0 (quilt)}
 827   \begin{itemize}
 828   \item Recommended solution
 829           \hbr
 830   \item You need to learn \textsl{quilt}\\
 831     \url{http://pkg-perl.alioth.debian.org/howto/quilt.html}
 832     \hbr
 833   \item Patch-system-agnostic tool in \texttt{devscripts}: \texttt{edit-patch}
 834   \end{itemize}
 835   \end{itemize}
 836 \end{frame}
 837
 838 \begin{frame}[fragile]{Documentation of patches}
 839   \begin{itemize}
 840           \item Standard headers at the beginning of the patch
 841     \br
 842   \item Documented in DEP-3 - Patch Tagging Guidelines\\
 843     \url{http://dep.debian.net/deps/dep3/}
 844   \end{itemize}
 845   \vfill
 846 \seprule
 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
 854
 855 --- a/src/widgets.c
 856 +++ b/src/widgets.c
 857 @@ -101,9 +101,6 @@ struct {
 858 \end{lstlisting}
 859 \end{frame}
 860
 861 \subsection{Doing things during installation and removal}
 862 \begin{frame}{Doing things during installation and removal}
 863   \begin{itemize}
 864   \item Decompressing the package is sometimes not enough
 865     \hbr
 866   \item Create/remove system users, start/stop services, manage \textsl{alternatives}
 867     \hbr
 868   \item Done in \textsl{maintainer scripts}\\
 869     \texttt{preinst, postinst, prerm, postrm}
 870     \begin{itemize}
 871             \item  Snippets for common actions can be generated by debhelper
 872     \end{itemize}
 873     \hbr
 874   \item Documentation:
 875     \begin{itemize}
 876     \item Debian Policy Manual, chapter 6\\
 877       {\footnotesize \url{http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html}}
 878
 879       \hbr
 880     \item Debian Developer's Reference, chapter 6.4\\
 881       {\scriptsize \url{http://www.debian.org/doc/developers-reference/best-pkging-practices.html}}
 882       \hbr
 883     \item {\footnotesize \url{http://people.debian.org/~srivasta/MaintainerScripts.html}}
 884     \end{itemize}
 885     \br
 886   \item Prompting the user
 887     \begin{itemize}
 888     \item Must be done with \textbf{debconf}
 889       \hbr
 890     \item Documentation: \texttt{debconf-devel(7)} (\texttt{debconf-doc} package)
 891     \end{itemize}
 892   \end{itemize}
 893 \end{frame}
 894
 895 \begin{frame}[fragile]{Monitoring upstream versions}
 896   \begin{itemize}
 897   \item Specify where to look in \texttt{debian/watch} (see \texttt{uscan(1)})
 898     \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 899 version=3
 900
 901 http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
 902   Twisted-([\d\.]*)\.tar\.bz2
 903     \end{lstlisting}
 904     \br
 905   \item Debian infrastructure that makes use of \texttt{debian/watch}:\\
 906     \textbf{Debian External Health Status}\\
 907     \url{http://dehs.alioth.debian.org/}
 908     \br
 909   \item Maintainer warned by emails sent to the Package Tracking System\\
 910     \url{http://packages.qa.debian.org/}
 911     \br
 912   \item \texttt{uscan}: run a manual check
 913     \br
 914   \item \texttt{uupdate}: try to update your package to the latest upstream version
 915   \end{itemize}
 916 \end{frame}
 917
 918 \subsection{Packaging with a VCS (SVN, Git \& friends)}
 919 \begin{frame}[fragile]{Packaging with a VCS (SVN, Git, etc.)}
 920   \begin{itemize}
 921   \item Several tools to help manage branches and tags for your packaging work:\\
 922     \texttt{svn-buildpackage}, \texttt{git-buildpackage}
 923     \hbr
 924   \item Example: \texttt{git-buildpackage}
 925     \begin{itemize}
 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
 930     \end{itemize}
 931     \hbr
 932   \item \texttt{Vcs-*} fields in \texttt{debian/control} to locate the repository
 933           \begin{itemize}
 934                 \item \url{http://wiki.debian.org/Alioth/Git}
 935                 \item \url{http://wiki.debian.org/Alioth/Svn}
 936         \end{itemize}
 937 \end{itemize}
 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
 941   \end{lstlisting}
 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
 945   \end{lstlisting}
 946   \begin{itemize}
 947   \item VCS-agnostic interface: \texttt{debcheckout}, \texttt{debcommit},
 948     \texttt{debrelease}\\
 949     \begin{itemize}
 950             \item     \texttt{debcheckout grep} $\rightarrow$ checks out the source package
 951     from Git
 952     \end{itemize}
 953 \end{itemize}
 954 \end{frame}
 955
 956 \subsection{Backporting packages}
 957 \begin{frame}{Backporting packages}
 958   \begin{itemize}
 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}
 961         \br
 962   \item General idea:
 963           \begin{itemize}
 964                 \item Take the source package from Debian unstable
 965                 \hbr
 966                 \item Modify it so that it builds and works fine on Debian stable
 967                 \begin{itemize}
 968                         \item Sometimes trivial (no changes needed)
 969                         \item Sometimes difficult
 970                         \item Sometimes impossible (many unavailable dependencies)
 971                 \end{itemize}
 972         \end{itemize}
 973         \br
 974    \item Some backports are provided and supported by the Debian project\\
 975            \url{http://backports.debian.org/}
 976 \end{itemize}
 977 \end{frame}
 978
 979
 980
 981 \section{Maintaining packages in Debian}
 982 \subsection{Several ways to contribute to Debian}
 983 \begin{frame}{Several ways to contribute to Debian}
 984   \begin{itemize}
 985   \item \textbf{Worst} way to contribute:
 986     \begin{enumerate}
 987     \item Package your own application
 988     \item Get it into Debian
 989     \item Disappear
 990     \end{enumerate}
 991     \br
 992   \item \textbf{Better} ways to contribute:
 993           \begin{itemize}
 994                   \item Get involved in packaging teams
 995     \begin{itemize}
 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
 999     \end{itemize}
1000     \br
1001 \item Adopt existing unmaintained packages (\textsl{orphaned packages})
1002     \br
1003   \item Bring new software to Debian
1004     \begin{itemize}
1005     \item Only if it's interesting/useful enough, please
1006     \item Are there alternatives already packaged in Debian?
1007     \end{itemize}
1008   \end{itemize}
1009
1010   \end{itemize}
1011 \end{frame}
1012
1013 \subsection{Adopting orphaned packages}
1014 \begin{frame}{Adopting orphaned packages}
1015       \hbr
1016   \begin{itemize}
1017     \item Many unmaintained packages in Debian
1018     \hbr
1019   \item Full list + process: \url{http://www.debian.org/devel/wnpp/}
1020     \hbr
1021   \item Installed on your machine: \texttt{wnpp-alert}
1022     \hbr
1023   \item Different states:
1024     \begin{itemize}
1025                     \small
1026     \item \textbf{O}rphaned: the package is unmaintained\\
1027       Feel free to adopt it
1028       \hbr
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
1032       \hbr
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!
1036       \hbr
1037     \item \textbf{RFH}: \textbf{R}equest \textbf{F}or \textbf{H}elp\\
1038       The maintainer is looking for help
1039     \end{itemize}
1040     \hbr
1041   \item Some unmaintained packages not detected \arr not orphaned yet
1042     \hbr
1043   \item When in doubt, ask \texttt{debian-qa@lists.debian.org} \\
1044     or \texttt{\#debian-qa} on \texttt{irc.debian.org}
1045   \end{itemize}
1046 \end{frame}
1047
1048 \subsection{Getting your package in Debian}
1049 \begin{frame}{Getting your package in Debian}
1050 \begin{itemize}
1051 \item You do not need any official status to get your package into Debian
1052         \begin{enumerate}
1053                 \item Prepare a source package
1054                         \hbr
1055                 \item Find a Debian Developer that will sponsor your package
1056         \end{enumerate}
1057 \br
1058 \item Official status (when you are already experienced):
1059         \begin{itemize}
1060                 \item \textbf{Debian Maintainer (DM):}\\
1061                         Permission to upload your own packages\\
1062                         See \url{http://wiki.debian.org/DebianMaintainer}
1063                         \hbr
1064                 \item \textbf{Debian Developer (DD):}\\
1065                         Debian project members; can vote and upload any package
1066         \end{itemize}
1067 \end{itemize}
1068 \end{frame}
1069
1070 \subsection{Where to find help?}
1071 \begin{frame}{Where to find help?}
1072   Help you will need:
1073   \begin{itemize}
1074   \item Advice and answers to your questions, code reviews
1075   \item Sponsorship for your uploads, once your package is ready
1076   \end{itemize}
1077   \br
1078   You can get help from:
1079   \begin{itemize}
1080           \item \textbf{Other members of a packaging team}
1081     \begin{itemize}
1082     \item They know the specifics of your package
1083     \item You can become a member of the team
1084     \end{itemize}
1085     \hbr
1086   \item The Debian Mentors group (if your package doesn't fit in a team)
1087     \begin{itemize}
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/}
1093     \end{itemize}
1094   \end{itemize}
1095 \end{frame}
1096
1097 \subsection{Official documentation}
1098 \begin{frame}{Official documentation}
1099   \begin{itemize}
1100   \item Debian Developers' Corner\\
1101     \url{http://www.debian.org/devel/}\\
1102     {\small Links to many resources about Debian development}
1103     \hbr
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}
1107     \hbr
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)}
1111     \hbr
1112   \item Debian Policy\\
1113     \url{http://www.debian.org/doc/debian-policy/}\\
1114
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
1118       \end{itemize}}
1119     \hbr
1120
1121   \item Ubuntu Packaging Guide\\
1122     \url{https://wiki.ubuntu.com/PackagingGuide}
1123   \end{itemize}
1124 \end{frame}
1125
1126 \begin{frame}{Debian dashboards for maintainers}
1127   \begin{itemize}
1128           \item \textbf{Source package centric}: Package Tracking System (PTS)\\
1129     \url{http://packages.qa.debian.org/dpkg}
1130     \br
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}
1133   \end{itemize}
1134 \end{frame}
1135
1136 \subsection{More interested in Ubuntu?}
1137 \begin{frame}{More interested in Ubuntu?}
1138   \begin{itemize}
1139   \item Ubuntu mainly manages the divergence with Debian
1140     \br
1141   \item No real focus on specific packages\\
1142     Instead, collaboration with Debian teams
1143     \br
1144   \item Usually recommend uploading new packages to Debian first\\
1145     \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages}
1146     \br
1147   \item Possibly a better plan:
1148     \begin{itemize}
1149     \item Get involved in a Debian team and act as a bridge with Ubuntu
1150       \hbr
1151     \item Help reduce divergence, triage bugs in Launchpad
1152       \hbr
1153     \item Many Debian tools can help:
1154       \begin{itemize}
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
1158       \end{itemize}
1159     \end{itemize}
1160   \end{itemize}
1161 \end{frame}
1162
1163 \section{Conclusion}
1164 \subsection{Conclusion}
1165 \begin{frame}{Conclusion}
1166   \begin{itemize}
1167   \item You now have a full overview of Debian packaging
1168     \br
1169   \item But you will need to read more documentation
1170     \br
1171   \item Best practices have evolved over the years
1172     \begin{itemize}
1173     \item If not sure, use the \textbf{dh} packaging helper, and the \textbf{3.0 (quilt)} format
1174     \end{itemize}
1175     \br
1176   \item Things that were not covered in this tutorial:
1177     \begin{itemize}
1178         \item UCF -- manage user changes to configuration files when upgrading
1179                 \hbr
1180         \item dpkg triggers -- group similar maintainer scripts actions together
1181                 \hbr
1182         \item Debian development organization:
1183                 \begin{itemize}
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
1187                 \end{itemize}
1188                 \end{itemize}
1189   \end{itemize}
1190   \vfill
1191   \centerline{\large Feedback: \textbf{lucas@debian.org}}
1192 \end{frame}
1193
1194 \subsection{Legal stuff}
1195 \begin{frame}{Legal stuff}
1196
1197   Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
1198   \br
1199
1200   {\small
1201     \textbf{This document is free software}: you can redistribute it and/or modify
1202     it under either (at your option):
1203     \hbr
1204     \begin{itemize}
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
1210       License.\\
1211       \url{http://creativecommons.org/licenses/by-sa/3.0/}
1212     \end{itemize}
1213   }
1214 \end{frame}
1215
1216 \subsection{Latest version \& source code}
1217 \begin{frame}{Latest version \& source code}
1218   \begin{itemize}
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}}
1221   \end{itemize}
1222
1223   \begin{itemize}
1224   \item Contribute:
1225           \begin{itemize}
1226                   \item  {\small \texttt{git clone\\ git://git.debian.org/collab-maint/packaging-tutorial.git}}
1227     \hbr
1228     \item {\small \texttt{apt-get source packaging-tutorial}}
1229     \hbr
1230     \item {\small \url{http://git.debian.org/?p=collab-maint/packaging-tutorial.git}}
1231     \end{itemize}
1232     \br
1233   \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
1234   \end{itemize}
1235 \end{frame}
1236
1237 \section{Practical session 2: packaging GNUjump}
1238 \begin{frame}{Practical session 2: packaging GNUjump}
1239 \begin{enumerate}
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}
1242                 \br
1243         \item Create a Debian package for it
1244                 \begin{itemize}
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
1248                 \end{itemize}
1249                 \br
1250         \item Enjoy
1251 \end{enumerate}
1252 \centerline{\includegraphics[width=5cm]{figs/gnujump.png}}
1253 \end{frame}
1254
1255 \section{Practical session 3: packaging a Java library}
1256 \begin{frame}{Practical session 3: packaging a Java library}
1257 \begin{enumerate}
1258         \item Take a quick look at some documentation about Java packaging:\\
1259                 \begin{itemize}
1260                 \item \url{http://wiki.debian.org/Java}
1261       \hbr
1262                 \item \url{http://wiki.debian.org/Java/Packaging}
1263       \hbr
1264                 \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
1265       \hbr
1266                 \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
1267       \hbr
1268                 \item Paper and slides from a Debconf10 talk about javahelper:\\
1269                         {\footnotesize
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}}
1272                 \end{itemize}
1273                 \br
1274         \item Download IRClib from \url{http://moepii.sourceforge.net/}
1275                 \br
1276         \item Package it
1277 \end{enumerate}
1278 \end{frame}
1279
1280 \section{Practical session 4: packaging a Ruby gem}
1281 \begin{frame}{Practical session 4: packaging a Ruby gem}
1282 \begin{enumerate}
1283         \item Take a quick look at some documentation about Ruby packaging:\\
1284                 \begin{itemize}
1285                 \item \url{http://wiki.debian.org/Ruby}
1286       \hbr
1287                 \item \url{http://wiki.debian.org/Teams/Ruby}
1288       \hbr
1289                 \item \url{http://wiki.debian.org/Teams/Ruby/Packaging}
1290       \hbr
1291                 \item \texttt{gem2deb(1)}, \texttt{dh\_ruby(1)} (in the \texttt{gem2deb} package)
1292                 \end{itemize}
1293                 \hbr
1294         \item Create a basic Debian source package from the \texttt{net-ssh} gem:\\
1295                 \texttt{gem2deb net-ssh}
1296         \hbr
1297         \item Improve it so that it becomes a proper Debian package
1298 \end{enumerate}
1299 \end{frame}
1300
1301 \section{Answers to practical sessions}
1302
1303 \begin{frame}
1304         \begin{center}
1305                 \LARGE Answers to\\[0.5em]  practical sessions
1306         \end{center}
1307 \end{frame}
1308
1309
1310 \subsection{Practical session 1: modifying the grep package}
1311
1312 \begin{frame}{Practical session 1: modifying the grep package}
1313 \begin{enumerate}
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)
1317
1318         \item Look at the files in \texttt{debian/}.
1319                 \begin{itemize}
1320                         \item           How many binary packages are generated by this source package?
1321                         \item           Which packaging helper does this package use?
1322                 \end{itemize}
1323     \hbr
1324         \item Build the package
1325     \hbr
1326         \item We are now going to modify the package. Add a changelog entry and increase the version number.
1327     \hbr
1328         \item Now disable perl-regexp support (it is a \texttt{./configure} option)
1329     \hbr
1330         \item Rebuild the package
1331     \hbr
1332         \item Compare the original and the new package with debdiff
1333     \hbr
1334         \item Install the newly built package
1335     \hbr
1336         \item Cry if you messed up ;)
1337 \end{enumerate}
1338 \end{frame}
1339
1340 \begin{frame}{Fetching the source}
1341 \begin{enumerate}
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
1344 \end{enumerate}
1345 \begin{itemize}
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}}
1348                 \hbr
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}
1353         \hbr
1354         \item The \texttt{grep} source package is composed of three files:
1355                 \begin{itemize}
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}
1359                 \end{itemize}
1360                 This is typical of the "3.0 (quilt)" format.
1361         \hbr
1362 \item If needed, uncompress the source with\\
1363         \texttt{dpkg-source -x grep\_2.6.3-3.dsc}
1364 \end{itemize}
1365 \end{frame}
1366
1367 \begin{frame}{Looking around and building the package}
1368         \begin{enumerate}
1369                         \setcounter{enumi}{1}
1370         \item Look at the files in \texttt{debian/}.
1371                 \begin{itemize}
1372                         \item           How many binary packages are generated by this source package?
1373                         \item           Which packaging helper does this package use?
1374                 \end{itemize}
1375         \end{enumerate}
1376         \hbr
1377         \begin{itemize}
1378                 \item According to \texttt{debian/control}, this package only generates one binary package, named \texttt{grep}.
1379                         \hbr
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}.
1381         \end{itemize}
1382         \hbr
1383         \begin{enumerate}
1384                         \setcounter{enumi}{2}
1385
1386                 \item Build the package
1387         \end{enumerate}
1388         \hbr
1389         \begin{itemize}
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)
1392         \end{itemize}
1393 \end{frame}
1394
1395 \begin{frame}{Editing the changelog}
1396         \begin{enumerate}
1397                         \setcounter{enumi}{3}
1398
1399         \item We are now going to modify the package. Add a changelog entry and increase the version number.
1400         \end{enumerate}
1401         \hbr
1402         \begin{itemize}
1403                 \item \texttt{debian/changelog} is a text file. You could edit it and add a new entry manually.
1404         \hbr
1405                 \item Or you can use \texttt{dch -i}, which will add an entry and open the editor
1406         \hbr
1407                 \item The name and email can be defined using the \texttt{DEBFULLNAME} and \texttt{DEBEMAIL} environment variables
1408         \hbr
1409                 \item After that, rebuild the package: a new version of the package is built
1410         \hbr
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}
1413         \end{itemize}
1414 \end{frame}
1415
1416 \begin{frame}{Disabling Perl regexp support and rebuilding}
1417         \begin{enumerate}
1418                         \setcounter{enumi}{4}
1419
1420         \item Now disable perl-regexp support (it is a \texttt{./configure} option)
1421         \item Rebuild the package
1422         \end{enumerate}
1423         \hbr
1424         \begin{itemize}
1425           \item Check with \texttt{./configure -{}-help}: the option to disable
1426             Perl regexp is \texttt{-{}-disable-perl-regexp}
1427         \hbr
1428                 \item Edit \texttt{debian/rules} and find the \texttt{./configure} line
1429         \hbr
1430                 \item Add \texttt{-{}-disable-perl-regexp}
1431         \hbr
1432                 \item Rebuild with \texttt{debuild} or \texttt{dpkg-buildpackage -us -uc}
1433         \end{itemize}
1434 \end{frame}
1435
1436 \begin{frame}{Comparing and testing the packages}
1437         \begin{enumerate}
1438                         \setcounter{enumi}{6}
1439
1440         \item Compare the original and the new package with debdiff
1441         \item Install the newly built package
1442         \end{enumerate}
1443         \hbr
1444         \begin{itemize}
1445                 \item Compare the binary packages: \texttt{debdiff ../*changes}
1446         \hbr
1447                 \item Compare the source packages: \texttt{debdiff ../*dsc}
1448         \hbr
1449                 \item Install the newly built package: \texttt{debi}\\
1450                         Or \texttt{dpkg -i ../grep\_<TAB>}
1451         \hbr
1452                 \item \texttt{grep -P foo} no longer works!
1453         \end{itemize}
1454 \br
1455 \begin{enumerate}
1456                 \setcounter{enumi}{8}
1457         \item Cry if you messed up ;)
1458 \end{enumerate}
1459 \hbr
1460 Or not: reinstall the previous version of the package:
1461 \begin{itemize}
1462         \item \texttt{apt-get install -{}-reinstall grep=2.6.3-3} \textit{(= previous version)}
1463 \end{itemize}
1464 \end{frame}
1465
1466 \subsection{Practical session 2: packaging GNUjump}
1467 \begin{frame}{Practical session 2: packaging GNUjump}
1468 \begin{enumerate}
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}
1471                 \br
1472         \item Create a Debian package for it
1473                 \begin{itemize}
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
1477                 \end{itemize}
1478                 \br
1479         \item Enjoy
1480 \end{enumerate}
1481 \centerline{\includegraphics[width=5cm]{figs/gnujump.png}}
1482 \end{frame}
1483
1484 \begin{frame}[fragile]{Step by step\ldots}
1485 \begin{itemize}
1486         \item \texttt{wget http://ftp.gnu.org/gnu/gnujump/1.0.6/gnujump-1.0.6.tar.gz}
1487                 \hbr
1488         \item \texttt{mv gnujump-1.0.6.tar.gz gnujump\_1.0.6.orig.tar.gz}
1489                 \hbr
1490         \item \texttt{tar xf gnujump\_1.0.6.orig.tar.gz}
1491                 \hbr
1492         \item \texttt{cd gnujump-1.0.6/}
1493                 \hbr
1494         \item \texttt{dh\_make}
1495         \begin{itemize}
1496                 \item \small Type of package: single binary (for now)
1497         \end{itemize}
1498 \end{itemize}
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
1510 \end{lstlisting}
1511 \end{frame}
1512
1513 \begin{frame}[fragile]{Step by step\ldots (2)}
1514 \begin{itemize}
1515         \item Look at \texttt{debian/changelog}, \texttt{debian/rules}, \texttt{debian/control}\\
1516                 (auto-filled by \textbf{dh\_make})
1517                 \hbr
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
1521                 \hbr
1522         \item Try to build the package as-is (thanks to \textbf{dh} magic)
1523                 \begin{itemize}
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
1526                         \item Example:
1527 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
1528 checking for sdl-config... no
1529 checking for SDL - version >= 1.2.0... no
1530 [...]
1531 configure: error: *** SDL version 1.2.0 not found!
1532 \end{lstlisting}
1533 $\rightarrow$ Add \textbf{libsdl1.2-dev} to Build-Depends and install it.
1534                 \hbr
1535         \item Better: use \textbf{pbuilder} to build in a clean environment
1536                 \end{itemize}
1537 \end{itemize}
1538 \end{frame}
1539
1540 \begin{frame}{Step by step\ldots (3)}
1541 \begin{itemize}
1542         \item After installing \texttt{libsdl1.2-dev, libsdl-image1.2-dev, libsdl-mixer1.2-dev}, the package builds fine.
1543                 \hbr
1544         \item Use \texttt{debc} to list the content of the generated package.
1545                 \hbr
1546         \item Use \texttt{debi} to install it and test it.
1547                 \hbr
1548         \item Fill in \texttt{debian/control} using \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
1549                 \hbr
1550         \item Test the package with \texttt{lintian}
1551                 \hbr
1552         \item Remove the files that you don't need in \texttt{debian/}
1553                 \hbr
1554         \item Compare your package with the one already packaged in Debian:
1555                 \begin{itemize}
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
1559                 \end{itemize}
1560 \end{itemize}
1561 \end{frame}
1562
1563 \subsection{Practical session 3: packaging a Java library}
1564 \begin{frame}{Practical session 3: packaging a Java library}
1565 \begin{enumerate}
1566         \item Take a quick look at some documentation about Java packaging:\\
1567                 \begin{itemize}
1568                 \item \url{http://wiki.debian.org/Java}
1569       \hbr
1570                 \item \url{http://wiki.debian.org/Java/Packaging}
1571       \hbr
1572                 \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
1573       \hbr
1574                 \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
1575       \hbr
1576                 \item Paper and slides from a Debconf10 talk about javahelper:\\
1577                         {\footnotesize
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}}
1580                 \end{itemize}
1581                 \br
1582         \item Download IRClib from \url{http://moepii.sourceforge.net/}
1583                 \br
1584         \item Package it
1585 \end{enumerate}
1586 \end{frame}
1587
1588 \begin{frame}{Step by step\ldots}
1589 \begin{itemize}
1590         \item \texttt{apt-get install javahelper}
1591                 \hbr
1592         \item Create a basic source package: \texttt{jh\_makepkg}
1593                 \begin{itemize}
1594                         \item Library
1595                         \item None
1596                         \item Default Free compiler/runtime
1597                 \end{itemize}
1598                 \hbr
1599         \item Look at and fix \texttt{debian/*}
1600                 \hbr
1601         \item \texttt{dpkg-buildpackage -us -uc} or \texttt{debuild}
1602                 \hbr
1603         \item \texttt{lintian}, \texttt{debc}, etc.
1604                 \hbr
1605         \item Compare your result with the \texttt{libirclib-java} source package
1606 \end{itemize}
1607 \end{frame}
1608
1609 \subsection{Practical session 4: packaging a Ruby gem}
1610 \begin{frame}{Practical session 4: packaging a Ruby gem}
1611 \begin{enumerate}
1612         \item Take a quick look at some documentation about Ruby packaging:\\
1613                 \begin{itemize}
1614                 \item \url{http://wiki.debian.org/Ruby}
1615       \hbr
1616                 \item \url{http://wiki.debian.org/Teams/Ruby}
1617       \hbr
1618                 \item \url{http://wiki.debian.org/Teams/Ruby/Packaging}
1619       \hbr
1620                 \item \texttt{gem2deb(1)}, \texttt{dh\_ruby(1)} (in the \texttt{gem2deb} package)
1621                 \end{itemize}
1622                 \hbr
1623         \item Create a basic Debian source package from the \texttt{net-ssh} gem:\\
1624                 \texttt{gem2deb net-ssh}
1625         \hbr
1626         \item Improve it so that it becomes a proper Debian package
1627 \end{enumerate}
1628 \end{frame}
1629
1630 \begin{frame}{Step by step\ldots}
1631 \texttt{gem2deb net-ssh}:
1632 \begin{itemize}
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
1636         \begin{itemize}
1637                 \item Named \texttt{ruby-\textsl{gemname}}
1638         \end{itemize}
1639 \item Tries to build the Debian binary package (this might fail)
1640 \end{itemize}
1641 \br
1642 \texttt{dh\_ruby} (included in \textsl{gem2deb}) does the Ruby-specific tasks:
1643 \begin{itemize}
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
1648 \end{itemize}
1649 \end{frame}
1650
1651 \begin{frame}[fragile]{Step by step\ldots (2)}
1652 Improve the generated package:
1653 \begin{itemize}
1654         \item Run \texttt{debclean} to clean the source tree. Look at \texttt{debian/}.
1655                 \hbr
1656         \item \texttt{changelog} and \texttt{compat} should be correct
1657                 \hbr
1658         \item Edit \texttt{debian/control}: uncomment \texttt{Homepage}, improve \texttt{Description}
1659                 \hbr
1660         \item Write a proper \texttt{copyright} file based on the upstream files
1661                 \hbr
1662         \item \texttt{ruby-net-ssh.docs}: install \texttt{README.rdoc}
1663                 \hbr
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'+
1667 \end{itemize}
1668 \end{frame}
1669
1670 \begin{frame}[fragile]{Step by step\ldots (3)}
1671 Build the package.
1672 It fails to build. There are two problems:
1673 \begin{itemize}
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:
1676                 \begin{itemize}
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}
1681                 \end{itemize}
1682                 \hbr
1683
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)
1688
1689                 \begin{itemize}
1690                         \item Add \texttt{ruby-mocha} to the package's \texttt{Build-Depends}
1691
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)
1697                 \end{itemize}
1698 \end{itemize}
1699 \hbr
1700 Compare your package with the \texttt{ruby-net-ssh} package in the Debian archive
1701 \end{frame}
1702
1703 \end{document}