update packaging
[packaging-tutorial.git] / packaging-tutorial.tex
index 2727b87..857169e 100644 (file)
@@ -6,7 +6,7 @@
 \hypersetup{pdftitle={Debian Packaging Tutorial},bookmarks}
 \title{Debian Packaging Tutorial}
 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
-\date{\footnotesize version 0.1 - 2011-05-05}
+\date{\footnotesize version 0.1 - 2011-05-25}
 
 \begin{document}
 
   \tableofcontents[hideallsubsections]
 \end{frame}
 
-\section{Practical session 0: simple rebuild of dash}
-\begin{frame}{Practical session 1: simple rebuild of dash}
-  \begin{enumerate}
-  \item install the packages we need
-  \item Create a working directory
-  \item Grab a simple source package
-  \item Build the package
-  \item Check that it worked
-  \end{enumerate}
-\end{frame}
-
 \section{Introduction}
 
 \subsection{Debian}
@@ -66,8 +55,6 @@
                        \br
                \item \textbf{Non-commercial}, built collaboratively by over 1,000 volunteers
                        \br
-               \item 30,000 binary packages; 12 ports (inc. 2 non-Linux); 120 derivatives
-                       \br
                \item 3 main features:
                        \begin{itemize}
                                \item \textbf{Quality} -- culture of technical excellence\\
                                \item \textbf{Independence} -- no (single) company babysitting Debian\\
                                        And open decision-making process (\textsl{do-ocracy} + \textsl{democracy})
                        \end{itemize}
+                        \br
+                \item \textbf{Amateur} in the best sense: done for the love of it
        \end{itemize}
 \end{frame}
 
+\subsection{Debian packages}
+\begin{frame}{Debian packages}
+\begin{itemize}
+\item \textbf{.deb} files (binary packages)
+       \br
+\item A very powerful and convenient way to distribute software to users
+       \br
+\item One of the two most common packages format (with RPM)
+       \br
+\item Universal:
+       \begin{itemize}
+               \item 30,000 binary packages in Debian\\
+                       $\rightarrow$ most of the available free software is packaged in Debian!
+                       \hbr
+               \item For 12 ports (architectures), including 2 non-Linux (Hurd; KFreeBSD)
+                       \hbr
+               \item Also used by 120 Debian derivatives distributions
+       \end{itemize}
+\end{itemize}
+\end{frame}
 
 
 \subsection{The Deb package format}
 
 \begin{frame}[fragile]{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
@@ -103,11 +110,13 @@ rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
       {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
     \item \texttt{data.tar.gz}: data files of the package
     \end{itemize}
+    \br
   \item You could create your \texttt{.deb} files manually\\
     {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
+    \br
   \item But most people don't do it that way
   \end{itemize}
-  \hbr
+  \br
   \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
 \end{frame}
 
@@ -166,6 +175,35 @@ rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
   \end{center}
 \end{frame}
 
+\subsection{Rebuilding dash}
+\begin{frame}{Example: rebuilding dash}
+\begin{enumerate}
+\item Install build-essential, devscripts and debhelper (needed to build dash)\\
+  {\texttt{apt-get install build-essential devscripts debhelper}}
+  \hbr
+\item Create a working directory, and get in it:\\
+ \texttt{mkdir /tmp/debian-tutorial ; cd /tmp/debian-tutorial}
+  \hbr
+\item Grab the \texttt{dash} source package\\
+  \texttt{apt-get source dash}\\ 
+  {\small (This needs you to have \texttt{deb-src} lines in your \texttt{/etc/apt/sources.list})}
+  \hbr
+\item Build the package\\
+  {\texttt{cd dash-*\\ debuild -us -uc}}
+
+  \hbr
+\item Check that it worked
+       \begin{itemize}
+               \item  There are some new \texttt{.deb} files in the parent directory
+       \end{itemize}
+    \hbr
+\item Look at the \texttt{debian/} directory
+       \begin{itemize}
+               \item That's where the packaging work is done
+       \end{itemize}
+\end{enumerate}
+\end{frame}
+
 \section{Creating source packages}
 \subsection{Source packages basics}
 \begin{frame}{Source package}
@@ -307,11 +345,23 @@ Files:
 \begin{frame}[fragile]{debian/changelog}
   \begin{itemize}
   \item Lists the Debian packaging changes
+  \item Gives the current version of the package
+  \begin{center}
+    \begin{tikzpicture}
+           \draw (0,0) node[above right] {\large 1.2.1.1-5};
+           \draw [decorate,decoration={brace}] (2,0) -- (1.45,0) node[at start,below,text width=1.6cm,text centered] {\small  Debian revision};
+           \draw [decorate,decoration={brace}] (1.4,0) -- (0,0) node[midway,below,text width=1.6cm,text centered] { \small Upstream version};
+\end{tikzpicture}
+\end{center}
+
+
+         %%
   \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}
+  \seprule
   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 mpich2 (1.2.1.1-5) unstable; urgency=low
 
@@ -325,35 +375,6 @@ mpich2 (1.2.1.1-5) unstable; urgency=low
 \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}
@@ -368,6 +389,7 @@ License:
   \item Documentation: Debian Policy chapter 5\\
     \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
   \end{itemize}
+  \seprule
 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 Source: wget
 Section: web
@@ -552,6 +574,9 @@ binary: binary-indep binary-arch
         "\textsl{twisty maze of makefiles and environment variables}"
       \item Slower than plain debhelper (many useless calls to \texttt{dh\_*})
       \end{itemize}
+    \end{itemize}
+  \end{itemize}
+  \seprule
       \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 #!/usr/bin/make -f
 include /usr/share/cdbs/1/rules/debhelper.mk
@@ -561,8 +586,6 @@ include /usr/share/cdbs/1/class/autotools.mk
 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)}
@@ -577,7 +600,8 @@ build/mypackage::
     \hbr
   \item Doc: manpages (\texttt{debhelper(7)}, \texttt{dh(1)}) + slides from DebConf9 talk\\
     \url{http://kitenet.net/~joey/talks/debhelper/debhelper-slides.pdf}
-    \br
+  \end{itemize}
+  \seprule
     \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 #!/usr/bin/make -f
 %:
@@ -589,8 +613,7 @@ override_dh_auto_configure:
 override_dh_auto_build:
      make world
 
-    \end{lstlisting}
-  \end{itemize} %$
+    \end{lstlisting}%$
 \end{frame}
 
 \begin{frame}{Classic debhelper vs CDBS vs dh}
@@ -618,8 +641,8 @@ override_dh_auto_build:
 \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,blue,thick,style=densely dotted] table[x=date,y=dh] {cdbs-dh7.txt};
+       \addplot[mark=none,red,thick,style=dashed] 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}
@@ -646,10 +669,12 @@ override_dh_auto_build:
   \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}
+      Good documentation: \url{https://wiki.ubuntu.com/PbuilderHowto}\\
+      (optimization: \textttc{cowbuilder} \textttc{ccache} \textttc{distcc})
       \hbr
     \item \textttc{schroot} and \textttc{sbuild}: used on the Debian build daemons\\
-      (not as easy to use as \texttt{pbuilder})
+      (not as simple as \texttt{pbuilder}, but allows LVM snapshots\\
+       see: \url{https://help.ubuntu.com/community/SbuildLVMHowto} )
     \end{itemize}
     \br
   \item Generate \texttt{.deb} files and a \texttt{.changes} file
@@ -688,17 +713,57 @@ override_dh_auto_build:
     \item              How many binary packages are generated by this source package?
     \item              Which packaging helper does this package use?
     \end{itemize}
+    \hbr
   \item Build the package
+    \hbr
   \item We are now going to modify the package. Add a changelog entry and increase the version number.
+    \hbr
   \item Now disable perl-regexp support (it is a \texttt{./configure} option)
+    \hbr
   \item Rebuild the package
+    \hbr
   \item Compare the original and the new package with debdiff
+    \hbr
   \item Install the newly built package
+    \hbr
   \item Cry if you messed up ;)
   \end{enumerate}
 \end{frame}
 
 \section{Advanced packaging topics}
+\subsection{debian/copyright}
+\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}
+  \seprule
+  \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}
+
+
+
 \subsection{Modifying the upstream source}
 \begin{frame}{Modifying the upstream source}
   Often needed:
@@ -762,6 +827,10 @@ override_dh_auto_build:
   \item Documented in DEP-3 - Patch Tagging Guidelines\\
     \url{http://dep.debian.net/deps/dep3/}
   \end{itemize}
+\begin{itemize}
+\item All patches are published on \url{http://patch-tracker.debian.org/}
+\end{itemize}
+\seprule
   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 Description: Fix widget frobnication speeds
  Frobnicating widgets too quickly tended to cause explosions.
@@ -774,9 +843,6 @@ Last-Update: 2010-03-29
 +++ b/src/widgets.c
 @@ -101,9 +101,6 @@ struct {
 \end{lstlisting}
-\begin{itemize}
-\item All patches are published on \url{http://patch-tracker.debian.org/}
-\end{itemize}
 \end{frame}
 
 \subsection{Doing things during installation and removal}
@@ -958,17 +1024,37 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
     \hbr
   \item When in doubt, ask \texttt{debian-qa@lists.debian.org} \\
     or \texttt{\#debian-qa} on \texttt{irc.debian.org}
-    
   \end{itemize}
 \end{frame}
 
-\section{Resources}
+\subsection{Getting your package in Debian}
+\begin{frame}{Getting your package in Debian}
+\begin{itemize}
+\item You do not need any official status to get your package into Debian
+       \begin{enumerate}
+               \item Prepare a source package
+                       \hbr
+               \item Find a Debian Developer that will sponsor your package
+       \end{enumerate}
+\br
+\item Official status (when you are already experienced):
+       \begin{itemize}
+               \item \textbf{Debian Maintainer (DM):}\\
+                       Permission to upload your own packages\\
+                       See \url{http://wiki.debian.org/DebianMaintainer}
+                       \hbr
+               \item \textbf{Debian Developer (DD):}\\
+                       Debian project members; can vote and upload any package
+       \end{itemize}
+\end{itemize}
+\end{frame}
+
 \subsection{Where to find help?}
 \begin{frame}{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
+  \item Advice and answers to your questions, code reviews
+  \item Sponsorship for your uploads, once your package is ready
   \end{itemize}
   \br
   You can get help from:
@@ -1053,7 +1139,7 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
                \begin{itemize}
                        \item Bug Tracking System (BTS)
                        \item Suites: stable, testing, unstable, experimental, security, *-updates, backports, \ldots
-                       \item Debian Blends -- subsets of Debian targetting specific groups
+                       \item Debian Blends -- subsets of Debian targeting specific groups
                \end{itemize}
                \end{itemize}
   \end{itemize}
@@ -1124,9 +1210,13 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
        \item Take a quick look at some documentation about Java packaging:\\
                \begin{itemize}
                \item \url{http://wiki.debian.org/Java}
+      \hbr
                \item \url{http://wiki.debian.org/Java/Packaging}
+      \hbr
                \item \url{http://www.debian.org/doc/packaging-manuals/java-policy/}
+      \hbr
                \item \url{http://pkg-java.alioth.debian.org/docs/tutorial.html}
+      \hbr
                \item Paper and slides from a Debconf10 talk about javahelper:\\
                        {\footnotesize
                        \url{http://pkg-java.alioth.debian.org/docs/debconf10-javahelper-paper.pdf}\\