cont

[packaging-tutorial.git] / packaging-tutorial.tex

\documentclass[10pt,final]{beamer}
\mode<presentation>
\usetheme{lucasdeb}
\usepackage{debiantutorial}

\hypersetup{pdftitle={An Introduction to Debian Packaging},bookmarks}
\title{An Introduction to Debian Packaging}
\author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
\institute{\includegraphics[viewport=274 335 360 440,width=1cm]{figs/openlogo-nd.pdf}}
\date{}

\begin{document}

\frame{\titlepage}

\section{Introduction}
\subsection{Legal stuff}
\begin{frame}
\frametitle{Legal stuff}

Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
\br

{\small 
\textbf{This document is free software}: you can redistribute it and/or modify
it under either (at your option):
\hbr
\begin{itemize}
\item The terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.\\
    \url{http://www.gnu.org/licenses/gpl.html}
    \br
\item The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported License.\\
        \url{http://creativecommons.org/licenses/by-sa/3.0/}
\end{itemize}
}
\end{frame}

\subsection{Latest version \& source code}
\begin{frame}
\frametitle{Latest version \& source code}
\begin{itemize}
\item Latest version:\\
        {\footnotesize \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git;a=blob\_plain;f=packaging-tutorial.pdf;hb=refs/heads/pdf}}
\end{itemize}

\begin{itemize}
\item Contribute:\\
        \texttt{git clone git://git.debian.org/\~{}lucas/packaging-tutorial.git}\\
        \hbr
        Or over HTTP: \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git}
        \br
\item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
\end{itemize}
\end{frame}

\subsection{About this tutorial}
\begin{frame}{About this tutorial}
\begin{itemize}
\item Goal: tell you what you really need to know about Debian packaging
\begin{itemize}
                        \hbr
\item To modify existing packages
                        \hbr
\item To create your own packages
                        \hbr
\item To become a Debian power-user
\end{itemize}
\br
\item Tries to keep a reasonable size
        \begin{itemize}
                        \hbr
                \item No attempt to be complete
                        \hbr
                \item You will need to read more documentation
        \end{itemize}
\br
\item Most of the content also applies to Debian derivatives distributions
        \begin{itemize}
                        \hbr
                \item That includes Ubuntu
        \end{itemize}
\end{itemize}
\end{frame}

\subsection{The Deb package format}
\begin{frame}[fragile]
        \frametitle{Introduction: the Deb package format}
\begin{itemize}
        \item One of the two most common packages format (with RPM)
        \item A very powerful and convenient way to distribute software to users
        \item \texttt{.deb} file: an \texttt{ar} archive
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
$ ar tv wget_1.12-2.1_i386.deb
rw-r--r-- 0/0      4 Sep  5 15:43 2010 debian-binary
rw-r--r-- 0/0   2403 Sep  5 15:43 2010 control.tar.gz
rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
\end{lstlisting}
\begin{itemize}
        \item \texttt{debian-binary}: version of the deb file format, \texttt{"2.0\textbackslash{}n"}
        \item \texttt{control.tar.gz}: metadata about the package\\
                {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
        \item \texttt{data.tar.gz}: data files of the package
\end{itemize}
\item You could create your \texttt{.deb} files manually\\
        {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
\item But most people don't do it that way
\end{itemize}
\hbr
\centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
\end{frame}

\subsection{Tools you will need}
\begin{frame}{Tools you will need}
        \begin{itemize}
                \item A Debian (or Ubuntu) system (with root access)
                        \br
                \item Some packages:
        \begin{itemize}
                \item \textbf{build-essential}: has dependencies on the packages that will be assumed to be available on the developers' machine (no need to specify them in the \texttt{Build-Depends:} control field of your package)
                \begin{itemize}
                        \item includes a dependency on \textbf{dpkg-dev}, which contains basic Debian-specific tools to create packages
                \end{itemize}
                \hbr
        \item \textbf{devscripts}: contains many useful scripts for Debian maintainers
        \end{itemize}
        \end{itemize}

        \br
        Many other tools will also be mentioned later, such as \textbf{debhelper}, \textbf{cdbs}, \textbf{quilt}, \textbf{pbuilder}, \textbf{sbuild}, \textbf{lintian}, \textbf{svn-buildpackage}, \textbf{git-buildpackage}, \ldots\\
        Install them when you need them.
\end{frame}

\subsection{General packaging workflow}
\begin{frame}{General packaging workflow}
\begin{center}
\begin{tikzpicture}[
        node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
        arr/.style={very thick},
        command/.style={text=rouge,font=\ttfamily},
]
        \node[node1] (www) at (0, 0) {Web};
        \node[node1] (us) at (2.5, 0) {upstream source};
        \node[node1] (da) at (-2.5, 0) {Debian mirror};
        \node[node1] (sp) at (0, -2) {source package};
        \draw[arr,<-,dashed] (sp) -- (2.5,-2) node[right=0cm,text width=2.98cm,text centered,font=\small] {where most of the manual work is done};
        \node[node1] (bin) at (0, -4) {one or several binary packages};
        \draw[arr,<-,dashed] (bin) -- (3.5,-4) node[right,text centered,font=\ttfamily] {.deb\normalfont};
        \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
        \draw[arr,->] (da) -- (sp) node[pos=0.5,left,command] {apt-get source};
        \draw[arr,->] (www) -- (sp) node[pos=0.5,left,command] {dget};
        \draw[arr,->] (sp) -- (bin) node[pos=0.5,right,text width=6cm] {\textttc{debuild} (build and test with \textttc{lintian}) or \textttc{dpkg-buildpackage}};
        \draw[arr,->] (bin) -- (-1,-6) node[pos=0.5,left] {install (\textttc{debi})};
        \draw[arr,->] (bin) -- (1,-6) node[pos=0.5,right] {upload (\textttc{dput})};
        \useasboundingbox (-4,-6) rectangle (6,0); % hack hack hack
\end{tikzpicture}
\end{center}
\end{frame}

\section{Creating source packages}
\subsection{Source packages basics}
\begin{frame}
\frametitle{Source package}
\begin{itemize}
        \item One source package can generate several binary packages\\
                {\small e.g the \texttt{\bfseries libtar} source generates the \texttt{\bfseries libtar} and \texttt{\bfseries libtar-dev} binary packages}
                \hbr
        \item Two kinds of packages: (if unsure, use non-native)
                \begin{itemize}
                                \small
                        \item Native packages: software developed inside Debian (\textsl{dpkg}, \textsl{apt})
                        \item Non-native packages: software developed outside Debian
                \end{itemize}
                \hbr
        \item Main file: \texttt{.dsc} (meta-data)
                \hbr
        \item Other files depending on the version of the source format
        \begin{itemize}
                \item 1.0 -- native: \texttt{package\_version.tar.gz}
                \hbr
                \item 1.0 -- non-native:
                \begin{itemize}
                        \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
                        \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
                \end{itemize}
                \hbr
                \item 3.0 (quilt):
                \begin{itemize}
                        \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
                        \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
                \end{itemize}
        \end{itemize}
\end{itemize}
\br
(See \texttt{dpkg-source(1)} for exact details)
\end{frame}

\begin{frame}[fragile]
        \frametitle{Source package example (wget\_1.12-2.1.dsc)}
\begin{lstlisting}[basicstyle=\ttfamily\small]
Format: 3.0 (quilt)
Source: wget
Binary: wget
Architecture: any
Version: 1.12-2.1
Maintainer: Noel Kothe <noel@debian.org>
Homepage: http://www.gnu.org/software/wget/
Standards-Version: 3.8.4
Build-Depends: debhelper (>> 5.0.0), gettext, texinfo, libssl-dev (>= 0.9.8), dpatch, info2man
Checksums-Sha1: 
 50d4ed2441e67db7aa5061d8a4dde41ee0e94248 2464747 wget_1.12.orig.tar.gz
 d4c1c8bbe431d6131cbd7ed2e4fc37dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
Checksums-Sha256: 
 7578ed0974e12caa71120581fa3962ee5a69f7175ddc3d6a6db0ecdcba65b572 2464747 wget_1.12.orig.tar.gz
 1e9b0c4c00eae6b4172baae219a14857f4002382b9d7a289de7ab789c402ad78 48308 wget_1.12-2.1.debian.tar.gz
Files: 
 141461b9c04e454dc8933c9d1f2abf83 2464747 wget_1.12.orig.tar.gz
 e93123c934e3c141916f472f380278c2 48308 wget_1.12-2.1.debian.tar.gz
\end{lstlisting}
\end{frame}

\subsection{Retrieving source packages}
\begin{frame}
\frametitle{Retrieving an existing source package}
\begin{itemize}
\item From the Debian archive:
        \begin{itemize}
                \item \texttt{apt-get source \textsl{package}}
                \item \texttt{apt-get source \textsl{package=version}}
                \item \texttt{apt-get source \textsl{package/release}}
        \end{itemize}
        (You need \texttt{deb-src} lines in \texttt{sources.list})
        \br
\item From the Internet:
        \begin{itemize}
                \item \texttt{dget \textsl{url-to.dsc}}
                \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\wget\_1.4.4-6.dsc}\\
                        (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
        \end{itemize}
\br
\item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
\end{itemize}
\end{frame}

\subsection{Creating a basic source package}
\begin{frame}
\frametitle{Creating a basic source package}
\begin{itemize}
        \item Download the upstream source
                \hbr
        \item Rename to \texttt{\textsl{source\_package}\_\textsl{upstream\_version}.orig.tar.gz}
                \hbr
        \item Untar it
                \hbr
        \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
                \hbr
        \item There are some alternatives to \texttt{dh\_make} for specific sets of packages: \textbf{dh-make-perl}, \textbf{dh-make-php}, \ldots
                \hbr
        \item \texttt{debian/} directory created, with a lot of files in it
\end{itemize}
\end{frame}

\subsection{Files in debian/}
\begin{frame}{Files in debian/}
        All the packaging work should usually be made by modifying files in \texttt{debian/}
\hbr
\begin{itemize}
        \item Main files:
        \begin{itemize}
                \item changelog
                \item copyright
                \item control
                \item rules
        \end{itemize}
        \hbr
        \item Optional files:
        \begin{itemize}
                \item compat
                \item watch
                \item dh\_install* targets\\
                        {\small *.dirs, *.docs, *.manpages, \ldots}
                \item maintainer scripts\\
                        {\small *.postinst, *.prerm, \ldots}
                \item source/format
                \item patches
        \end{itemize}
\end{itemize}
\end{frame}

\begin{frame}[fragile]{debian/changelog}
        \begin{itemize}
                \item Lists the Debian packaging changes
                \item Edited manually or with \texttt{dch}
                \item Special format to automatically close Debian or Ubuntu bugs\\
                        Debian: \texttt{Closes:~\#595268} ; Ubuntu: \texttt{LP:~\#616929}
                \item Installed as \texttt{/usr/share/doc/\textit{package}/changelog.Debian.gz}
        \end{itemize}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
mpich2 (1.2.1.1-5) unstable; urgency=low

  * Use /usr/bin/python instead of /usr/bin/python2.5. Allow
    to drop dependency on python2.5.  Closes: #595268
  * Make /usr/bin/mpdroot setuid. This is the default after
    the installation of mpich2 from source, too. LP: #616929
    + Add corresponding lintian override.

 -- Lucas Nussbaum <lucas@debian.org>  Wed, 15 Sep 2010 18:13:44 +0200
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]{debian/copyright}
        \hbr
        \begin{itemize}
                \item Copyright and license information for the source and the packaging
                \item Traditionally written as a text file
                \item New machine-readable format: \url{http://dep.debian.net/deps/dep5/}
        \end{itemize}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
Format: <VERSIONED_FORMAT_URL>
Upstream-Name: X Solitaire
Source: ftp://ftp.example.com/pub/games

Files: *
Copyright: Copyright 1998 John Doe <jdoe@example.com>
License: GPL-2+
 This program is free software; you can redistribute it
 [...]
 .
 On Debian systems, the full text of the GNU General Public
 License version 2 can be found in the file
 `/usr/share/common-licenses/GPL-2'.

Files: debian/*
Copyright: Copyright 1998 Jane Smith <jsmith@example.net>
License:
 [LICENSE TEXT]
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]{debian/control}
        \hbr
        \begin{itemize}
                \item Package metadata
                        \begin{itemize}
                                \item For the source package itself
                                \item For each binary package built from this source
                        \end{itemize}
                        \hbr
                \item Package name, section, priority, maintainer, uploaders, build-dependencies, dependencies, description, homepage, \ldots
                        \hbr
                \item Documentation: Debian Policy chapter 5\\
                        \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
        \end{itemize}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
Source: wget
Section: web
Priority: important
Maintainer: Noel Kothe <noel@debian.org>
Build-Depends: debhelper (>> 5.0.0), gettext, texinfo,
 libssl-dev (>= 0.9.8), dpatch, info2man
Standards-Version: 3.8.4
Homepage: http://www.gnu.org/software/wget/

Package: wget
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: retrieves files from the web
 Wget is a network utility to retrieve files from the Web
\end{lstlisting}
\end{frame}

\begin{frame}{Architecture: all or any}
Two kinds of binary packages:
\hbr
\begin{itemize}
        \item Packages with a different content on each Debian architecture
        \begin{itemize}
        \item Example: C program
        \item \texttt{Architecture:\ any} in \texttt{debian/control}
                \begin{itemize}
                        \item Or, if it only works on a subset of architectures:\\
                                \texttt{Architecture:\ amd64 i386 ia64 hurd-i386}
                \end{itemize}
        \item Packages for other architectures built by the Debian infrastructure
        \item Named \texttt{\textsl{package}\_\textsl{version}\_\textsl{architecture}.deb}
        \end{itemize}
\br
        \item Packages with the same content on all architectures
        \begin{itemize}
        \item Example: Perl library
        \item \texttt{Architecture:\ all} in \texttt{debian/control}
        \item Named \texttt{\textsl{package}\_\textsl{version}\_\textbf{all}.deb}
\end{itemize}
\end{itemize}
\end{frame}

\begin{frame}[fragile]{debian/rules}
        \hbr
        \begin{itemize}
                \item Makefile
                        \br
                \item Interface used to build Debian packages
                        \br
                \item Documented in Debian Policy, chapter 4.8\\
                        {\small \texttt{http://www.debian.org/doc/debian-policy/ch-source.html\#s-debianrules}}
                        \br
                \item Five required targets:
                \begin{itemize}
                        \item \texttt{build}: should perform all the configuration and compilation of the package
                                \hbr
                        \item \texttt{binary, binary-arch, binary-indep}: build the binary packages produced by this source package
                                \begin{itemize}
                                        \item \texttt{dpkg-buildpackage} will call \texttt{binary} to build all the packages, or \texttt{binary-arch} to build only the \texttt{Architecture:~any} packages
                                \end{itemize}
                                \hbr
                        \item \texttt{clean}: clean up the source directory
                \end{itemize}
        \end{itemize}
\end{frame}

\subsection{Packaging helpers}
\begin{frame}{Packaging helpers -- debhelper}
\begin{itemize}
        \item You could write shell code in \texttt{debian/rules} directly
        \begin{itemize}
                \item See the \texttt{adduser} package for example
        \end{itemize}
        \hbr
        \item But most packages in Debian use a \textsl{Packaging helper}
        \hbr
        \item Most popular one: \textbf{debhelper} (used by 98\% of packages)
        \hbr
        \item Goal: factor the common tasks in standard tools used by all packages\\
                {\footnotesize dh\_installdirs, dh\_installchangelogs, dh\_installdocs, dh\_installexamples, dh\_install, dh\_installdebconf, dh\_installinit, dh\_link, dh\_strip, dh\_compress, dh\_fixperms, dh\_perl, dh\_makeshlibs, dh\_installdeb, dh\_shlibdeps, dh\_gencontrol, dh\_md5sums, dh\_builddeb, \ldots}
                \begin{itemize}
                        \item Called from \texttt{debian/rules}
                        \item Configurable using command parameters or files in \texttt{debian/}\\
                                {\footnotesize \ttfamily dirs, package.docs, package.examples, package.install, package.menu, package.logrotate, package.manpages, \ldots}
                \end{itemize}
        \hbr
\item Third-party helpers for sets of packages: \textbf{python-support}, \textbf{dh\_ocaml}, \ldots
        \hbr
\item Gotcha: \texttt{debian/compat}: Debhelper compatibility version (use "7")
\end{itemize}
\end{frame}

\begin{frame}[fragile]{debian/rules using debhelper (1/2)}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
#!/usr/bin/make -f

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

build: 
        $(MAKE)
        #docbook-to-man debian/packagename.sgml > packagename.1

clean: 
        dh_testdir
        dh_testroot
        rm -f build-stamp configure-stamp
        $(MAKE) clean
        dh_clean 

install: build
        dh_testdir
        dh_testroot
        dh_clean -k 
        dh_installdirs
        # Add here commands to install the package into debian/packagename.
        $(MAKE) DESTDIR=$(CURDIR)/debian/packagename install
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]{debian/rules using debhelper (2/2)}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]

# Build architecture-independent files here.
binary-indep: build install

# Build architecture-dependent files here.
binary-arch: build install
        dh_testdir
        dh_testroot
        dh_installchangelogs 
        dh_installdocs
        dh_installexamples
#       dh_install
        dh_installman
        dh_link
        dh_strip
        dh_compress
        dh_fixperms
        dh_installdeb
        dh_shlibdeps
        dh_gencontrol
        dh_md5sums
        dh_builddeb

binary: binary-indep binary-arch
.PHONY: build clean binary-indep binary-arch binary install configure
\end{lstlisting}
\end{frame}

\begin{frame}[fragile]{CDBS}
\hbr
\begin{itemize}
\item Still a lot of redundancy between packages
\hbr
\item Second-level helpers that factor common funtionality
        \begin{itemize}
        \item Building with \texttt{./configure \&\& make \&\& make install} or CMake
        \item Support for Perl, Python, Ruby, GNOME, KDE, Java, Haskell, \ldots
        \end{itemize}
\hbr
\item CDBS:
        \begin{itemize}
                \item Introduced in 2005, based on advanced \textsl{GNU make} magic
                \item Documentation: \texttt{/usr/share/doc/cdbs/}
                \item But some people hate it:
                        \begin{itemize}
                                \item Sometimes difficult to customize package builds:\\
                                "\textsl{twisty maze of makefiles, environment vars and black magic}"
                        \item Slower than plain debhelper (many useless calls to \texttt{dh\_*})
                        \end{itemize}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk

# add an action after the build
build/mypackage::
    /bin/bash debian/scripts/foo.sh
\end{lstlisting}
        \end{itemize}
\end{itemize}
\end{frame}

\begin{frame}[fragile]{Dh (aka Debhelper 7, or dh7)}
\begin{itemize}
\item Introduced in 2008 as a \textsl{CDBS killer}
\hbr
\item \textbf{dh} command that calls \texttt{dh\_*}
\hbr
\item Simple \textsl{debian/rules}, listing only overrides
\hbr
\item Easier to customize than CDBS
\hbr
\item Doc: manpages (\texttt{debhelper(7)}, \texttt{dh(1)}) + slides from DC9 talk\\
        \url{http://kitenet.net/~joey/talks/debhelper/debhelper-slides.pdf}
        \br
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
#!/usr/bin/make -f
%:
    dh $@

override_dh_auto_configure:
     dh_auto_configure -- --with-kitchen-sink

override_dh_auto_build:
     make world

\end{lstlisting}
\end{itemize}
\end{frame}

\begin{frame}{Classic debhelper vs CDBS vs dh}
        \hbr
\begin{itemize}
\item Market shares: (feb'11)\\
Classic debhelper: 45\% \hskip 1em CDBS: 24\% \hskip 1em  dh: 29\%
\hbr
\item Which one should I learn?
\begin{itemize}
        \item Probably all of them
        \item You need to know debhelper to use CDBS and dh
        \item You might have to modify CDBS packages
\end{itemize}
\hbr
\item Which one should I use for a new package?
\begin{itemize}
        \item \textbf{dh} (only solution with an increasing market share)
\end{itemize}
\end{itemize}

\hbr
\begin{center}
\begin{tikzpicture}
\begin{axis}[small,label style={font=\footnotesize},xlabel={\small Time},ylabel={\small Market share (\%)},
        date coordinates in=x,height=4.85cm,width=9cm,xticklabel={\month/\year},
             legend style={font=\footnotesize,at={(1.02,1)},anchor=north west},max space between ticks=82,try min ticks=5,ymin=0]
        \addplot[mark=none,blue,thick] table[x=date,y=dh] {cdbs-dh7.txt};
        \addplot[mark=none,red,thick] table[x=date,y=dh7] {cdbs-dh7.txt};
        \addplot[mark=none,green,thick] table[x=date,y=cdbs] {cdbs-dh7.txt};
        \legend{debhelper, dh, CDBS}
\end{axis}
\end{tikzpicture}
\end{center}

\end{frame}

\section{Building and testing packages}
\subsection{Building packages}
\begin{frame}{Building packages}
\begin{itemize}
        \item \textttc{apt-get build-dep mypackage}\\
                Installs the \textsl{build-dependencies} (for a package in the archive)
                
                \br
        \item \textttc{debuild}: build, test with \texttt{lintian}, sign with GPG
                \br
        \item Also possible to call \textttc{dpkg-buildpackage} directly
                \begin{itemize}
                        \item Usually with \texttt{dpkg-buildpackage -us -uc}
                \end{itemize}
                \br
        \item It is better to build packages in a clean \& minimal environment
                \begin{itemize}
                        \item \textttc{pbuilder} -- helper to build packages in a \textsl{chroot}\\
                                Good documentation: \url{https://wiki.ubuntu.com/PbuilderHowto}
                        \hbr
                \item \textttc{schroot} and \textttc{sbuild}: used on the Debian build daemons\\
                        (not as easy to use as \texttt{pbuilder})
                \end{itemize}
                \br
        \item Generate \texttt{.deb} files and a \texttt{.changes} file
                \begin{itemize}
                        \item \texttt{.changes}: describes what was built ; used to upload the package
                \end{itemize}
\end{itemize}
\end{frame}
\subsection{Installing and testing packages}
\begin{frame}{Installing and testing packages}
\begin{itemize}
        \item Install the package locally: \textttc{debi} (will use \texttt{.changes} to know what to install)
                \br
        \item List the content of the package: \texttt{{\color{rouge}debc} ../mypackage<TAB>.changes}
                \br
        \item Compare the package with a previous version:\\
                \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.changes ../mypackage\_2\_*.changes}\\
                or to compare the sources:\\
                \texttt{{\color{rouge}debdiff} ../mypackage\_1\_*.dsc ../mypackage\_2\_*.dsc}\\
                \br
        \item Check the package with \texttt{lintian} (static analyzer):\\
                \texttt{{\color{rouge}lintian} ../mypackage<TAB>.changes}\\
                \texttt{lintian -i}: gives more information about the errors
                \br
        \item Upload the package to Debian (\textttc{dput})
                \br
        \item Manage a private Debian archive with \textttc{reprepro}\\
                Documentation: \url{http://mirrorer.alioth.debian.org/}

\end{itemize}
\end{frame}
\section{Practical session: modifying the grep package}
\begin{frame}{Practical session: modifying the grep package}
\begin{enumerate}
        \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
                download version 2.6.3-3 of the package
        \item Look at the files in \texttt{debian/}.
                \begin{itemize}
                        \item           How many binary packages are generated by this source package?
                        \item           Which packaging helper does this package use?
                \end{itemize}
        \item Build the package
        \item We are now going to modify the package. Add a changelog entry and increase the version number.
        \item Now disable perl-regexp support (it is a \texttt{./configure} option)
        \item Rebuild the package
        \item Compare the original and the new package with debdiff
        \item Install the newly built package
\end{enumerate}
\end{frame}

\section{Advanced packaging topics}
\subsection{Modifying the upstream source}
\begin{frame}{Modifying the upstream source}
Often needed:
\begin{itemize}
\item Fix bugs or add customizations that are specific to Debian
\hbr
\item Backport fixes from a newer upstream release
\end{itemize}
\br
Several methods to do it:
\begin{itemize}
\item Modifying the files directly
        \begin{itemize}
                \item Simple
                \item But no way to track and document the changes
        \end{itemize}
        \hbr
\item Using patch systems
\end{itemize}
\end{frame}

\begin{frame}{Patch systems}
\begin{itemize}
\item Principle: changes are stored as patches in \texttt{debian/patches/}
                \hbr
\item Applied and unapplied during build
                \hbr
\item Several implementations: \textsl{simple-patchsys} (\textsl{cdbs} only), \textsl{dpatch}, \textbf{\textsl{quilt}}
        \hbr
\item Each supports two \texttt{debian/rules} targets:
        \begin{itemize}
                \item \texttt{debian/rules patch}: apply all patches
                \item \texttt{debian/rules unpatch}: de-apply all patches
        \end{itemize}
        \hbr
\item More documentation: \url{http://wiki.debian.org/debian/patches}
\end{itemize}
\br
Future: new source package format with built-in patch system: \textbf{3.0 (quilt)}
\begin{itemize}
        \item Recommended solution
        \item You need to learn \textsl{quilt}\\
                \url{http://pkg-perl.alioth.debian.org/howto/quilt.html}

\end{itemize}
\end{frame}

\begin{frame}[fragile]{Documentation of patches}
\begin{itemize}
        \item Standard headers
                \hbr
        \item Documented in DEP3 - Patch Tagging Guidelines\\
                \url{http://dep.debian.net/deps/dep3/}
\end{itemize}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
Description: Fix widget frobnication speeds
 Frobnicating widgets too quickly tended to cause explosions.
Forwarded: http://lists.example.com/2010/03/1234.html
Author: John Doe <johndoe-guest@users.alioth.debian.org>
Applied-Upstream: 1.2, http://bzr.foo.com/frobnicator/revision/123
Last-Update: 2010-03-29
\end{lstlisting}
\end{frame}

\subsection{Doing things during installation and removal}
\begin{frame}{Doing things during installation and removal}
\begin{itemize}
\item Decompressing the package is sometimes not enough
\hbr
\item Create/remove system users, start/stop services, manage \textsl{alternatives}
\hbr
\item Done in \textsl{maintainer scripts}\\
        \texttt{preinst, postinst, prerm, postrm}
\hbr
\item Documentation:
        \begin{itemize}
                \item Debian Policy Manual, chapter 6\\
                        {\footnotesize \url{http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html}}
                        
                        \hbr
                \item Debian Developer's Reference, chapter 6.4\\
                        {\scriptsize \url{http://www.debian.org/doc/developers-reference/best-pkging-practices.html}}
                        \hbr
                \item {\footnotesize \url{http://people.debian.org/~srivasta/MaintainerScripts.html}}
        \end{itemize}
\br
\item Prompting the user
\begin{itemize}
        \item Must be done with \textbf{debconf}
                \hbr
        \item Documentation: \texttt{debconf-devel(7)} (\texttt{debconf-doc} package)
\end{itemize}
\end{itemize}
\end{frame}

\begin{frame}[fragile]{Monitoring upstream versions}
\begin{itemize}
\item Specify where to look in \texttt{debian/watch} (see \texttt{uscan(1)})
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
version=3

http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
  Twisted-([\d\.]*)\.tar\.bz2
\end{lstlisting}
        \br
\item Debian infrastructure that makes use of \texttt{debian/watch}:\\
        \textbf{Debian External Health Status}\\
        \url{http://dehs.alioth.debian.org/}
        \br
\item Maintainer warned by emails sent to the Packages Tracking System
\br
\item \texttt{uscan}: run a manual check
\br
\item \texttt{uupdate}: try to update your package to the latest upstream version
\end{itemize}
\end{frame}

\subsection{Packaging with a VCS (SVN, Git \& friends)}
\begin{frame}[fragile]{Packaging with a VCS (SVN, Git \& friends)}
\begin{itemize}
\item Several tools to help manage branches and tags for your packaging work:\\
\texttt{svn-buildpackage}, \texttt{git-buildpackage}
\hbr
\item Example: \texttt{git-buildpackage}
        \begin{itemize}
                \item \texttt{upstream} branch to track upstream with \texttt{upstream/\textsl{version}} tags
                \item \texttt{master} branch tracks the Debian package
                \item \texttt{debian/\textsl{version}} tags for each upload
                \item \texttt{pristine-tar} branch to be able to rebuild the upstream tarball
        \end{itemize}
\hbr
\item \texttt{Vcs-*} fields in \texttt{debian/control} to locate the repository
\end{itemize}
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
Vcs-Browser: http://git.debian.org/?p=devscripts/devscripts.git
Vcs-Git: git://git.debian.org/devscripts/devscripts.git

Vcs-Browser: http://svn.debian.org/viewsvn/pkg-perl/trunk/libwww-perl/
Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
\end{lstlisting}
\begin{itemize}
        \item VCS-agnostic interface: \texttt{debcheckout}, \texttt{debcommit}, \texttt{debrelease}\\
                \texttt{debcheckout devscripts} $\rightarrow$ check out the source package from Git
\end{itemize}
\end{frame}

\section{Maintaining packages in Debian}
\subsection{Several ways to contribute to Debian}
\begin{frame}{Several ways to contribute to Debian}
\begin{itemize}
\item Bring new software to Debian
\begin{itemize}
\item Is that new software interesting/useful enough?
\item Are there alternatives already packaged in Debian?
\end{itemize}
\br
\item Adopt existing unmaintained packages (\textsl{orphaned packages})
\begin{itemize}
        \item Many unmaintained packages in Debian
        \item Including some that you rely on, probably
\end{itemize}
\br
\item Get involved in packaging teams
\begin{itemize}
\item Many teams that focus on set of packages, and need help
\item Full list on \url{http://wiki.debian.org/Teams}
\item An excellent way to work with more experienced contributors
\end{itemize}
\end{itemize}
\end{frame}

\subsection{More interested in Ubuntu?}
\begin{frame}
\frametitle{More interested in Ubuntu?}
\begin{itemize}
        \item Ubuntu mainly manages the divergence with Debian
        \br
        \item Do not really focus on specific packages\\
                Instead, collaborate with Debian teams
        \br
        \item Usually recommend uploading new packages to Debian first\\
                \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages/}
        \br
        \item Possibly a better plan:
        \begin{itemize}
                \item Get involved in a Debian team and act as a bridge with Ubuntu
                        \hbr
                \item Help reduce divergence, triage bugs in Launchpad
                        \hbr
                \item Many Debian tools can help:
                \begin{itemize}
                \item Ubuntu column on the Developer' packages overview
                \item Ubuntu box on the Packages Tracking System
                \item Receive launchpad bugmail via the PTS
                \end{itemize}
        \end{itemize}
\end{itemize}
\end{frame}

\subsection{Adopting orphaned packages}
\begin{frame}{Adopting orphaned packages}
\begin{itemize}
        \item Full list: \url{http://www.debian.org/devel/wnpp/}
                \hbr
        \item Installed on your machine: \texttt{wnpp-alert}
                \hbr
        \item Different states:
        \begin{itemize}
                \item \textbf{O}rphaned: the package is unmaintained\\
                        Feel free to adopt it
                \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
                        Maintainer looking for adopter, but continues work in the meantime\\
                        Feel free to adopt it. A mail to the current maintainer is polite
                \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
                        Someone intends to adopt the package\\
                        You could propose your help!
                \item \textbf{RFH} (\textbf{R}equest \textbf{F}or \textbf{H}elp\\
                        The maintainer is looking for help
        \end{itemize}
                \hbr
        \item Some unmaintained packages not detected \arr not orphaned yet
                \hbr
        \item When in doubt, ask \texttt{debian-qa@lists.debian.org}
        \end{itemize}
\end{frame}

\section{Resources}
\subsection{Where to find help?}
\begin{frame}
\frametitle{Where to find help?}
Help you will need:
\begin{itemize}
        \item Various advices and answers to your questions, code reviews
        \item Sponsorship of your uploads, when your package is ready
\end{itemize}
\br
You can get help from:
\begin{itemize}
        \item Other members of a packaging team: the best solution
                \begin{itemize}
                        \item They know the specifics of your package
                        \item You can become a member of the team
                        \item See \url{http://wiki.debian.org/Teams}
                \end{itemize}
        \hbr
        \item The Debian Mentors group (if your package doesn't fit in a team)
                \begin{itemize}
                        \item \url{http://wiki.debian.org/DebianMentorsFaq}
                        \item Mailing list: \url{debian-mentors@lists.debian.org}
                        \item IRC: \texttt{\#debian-mentors} on \texttt{irc.debian.org}
                        \item \url{http://mentors.debian.net/}
                \end{itemize}
\end{itemize}
\end{frame}

\subsection{Official documentation}
\begin{frame}{Official documentation}
        \begin{itemize}
                \item Debian Developers' Corner\\
                        \url{http://www.debian.org/devel/}\\
                        {\small Links to many resources about Debian development}
                        \br
                \item Debian New Maintainers' Guide\\
                        \url{http://www.debian.org/doc/maint-guide/}\\
                        {\small An introduction to Debian packaging, but could use an update}
                        \br
                \item Debian Developer's Reference\\
                      \url{http://www.debian.org/doc/developers-reference/}\\
                      {\small Mostly about Debian procedures, but also some best packaging practices (part 6)}
                        \br
              \item Debian Policy\\
                    \url{http://www.debian.org/doc/debian-policy/}\\
                    {\small All the requirements that every package must satisfy}
                        \br

                \item Ubuntu Packaging Guide\\
                        \url{https://wiki.ubuntu.com/PackagingGuide}
        \end{itemize}
\end{frame}

\section{Conclusion}
\begin{frame}{Conclusion}
\begin{itemize}
        \item You now have a full overview of Debian packaging
                \br
        \item But you will need to read more documentation
                \br
        \item Best practices have evolved over the years
                \begin{itemize}
                        \item If not sure, use the \textbf{dh} packaging helper, and the \textbf{3.0 (quilt)} format
                \end{itemize}
\end{itemize}
\vfill
\centerline{\large Feedback: \textbf{lucas@debian.org}}
\end{frame}

\backupbegin

\begin{frame}
        \frametitle{TODO}
\begin{itemize}
\item Fix background with N900 PDF viewer
\item more practical sessions
\item debc and lintian should really pick-up the .changes file automatically
\end{itemize}
\end{frame}

\begin{frame}{Debian branches (\textsl{suites})}
                \begin{itemize}
                        \item \textbf{stable} (currently codenamed \textbf{squeeze}): stable and supported. Only important bug fixes.
                        \br
                        \item \textbf{testing} (currently codenamed \textbf{wheezy}): the future stable release.
                        \br
                        \item \textbf{unstable} (always codenamed \textbf{sid}): where most of the work occurs, and where packages are uploaded. Packages migrate automatically from \textsl{unstable} to \textsl{testing} according to some rules.
                        \br
                        \item \textbf{experimental}: for experimental packages that are not suited for a stable release.
                \end{itemize}
                \hbr
                Developers mostly run \textsl{unstable} or \textsl{testing} (with \textsl{APT pinning})
                \hbr

                Packages can be \textbf{backported} from \textsl{testing/unstable} to \textsl{stable}. See \url{http://backports.debian.org/}
\end{frame}

\begin{frame}{Debian portals for maintainers}
                \begin{itemize}
                        \item Source package centric: Packages Tracking System\\
                        \url{http://packages.qa.debian.org/dpkg}
                        \br
                        \item Maintainer/team centric: Developer's Packages Overview\\
                        \url{http://qa.debian.org/developer.php?login=pkg-ruby-extras-maintainers@lists.alioth.debian.org}
                \end{itemize}
\end{frame}

\backupend

\end{document}