Give example of package adoption
[packaging-tutorial.git] / packaging-tutorial.tex
index 9e5158e..7b4efea 100644 (file)
 \hypersetup{bookmarks}
 \title{Debian Packaging Tutorial}
 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
-\date{\footnotesize version 0.3 - 2011-08-26}
+
+%Translators:
+%leave \\version unchanged: this will a variable containing the actual version
+%To translate the date, use \\today or a string containing \\year, \\month, \\day
+%(numeric values).
+\date{\footnotesize version 0.5 -- 2012-01-14} % DATE - use debian/rules update-version-date
 
 \begin{document}
 
+
 \frame{\titlepage}
 
 \begin{frame}{About this tutorial}
@@ -184,8 +190,8 @@ rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
 \begin{frame}{Example: rebuilding dash}
 \begin{enumerate}
 \item Install packages needed to build dash, and devscripts\\
-  {\texttt{apt-get build-dep dash}}\\
-  {\texttt{apt-get install -{}-no-install-recommends devscripts}}
+  {\texttt{sudo apt-get build-dep dash}\\ (requires \texttt{deb-src} lines in \texttt{/etc/apt/sources.list})}\\
+  {\texttt{sudo apt-get install -{}-no-install-recommends devscripts}}
   \hbr
 \item Create a working directory, and get in it:\\
  \texttt{mkdir /tmp/debian-tutorial ; cd /tmp/debian-tutorial}
@@ -195,7 +201,7 @@ rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
   {\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}}
+  {\texttt{cd dash-*\\ debuild -us -uc}} ~~~(\texttt{-us -uc} disables signing the package with GPG)
 
   \hbr
 \item Check that it worked
@@ -244,7 +250,7 @@ rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
       \end{itemize}
     \end{itemize}
   \end{itemize}
-  \br
+  \hbr
   (See \texttt{dpkg-source(1)} for exact details)
 \end{frame}
 
@@ -362,7 +368,10 @@ Files:
 
 
          %%
-  \item Edited manually or with \texttt{dch}
+  \item Edited manually or with \textttc{dch}
+  \begin{itemize}
+         \item Create a changelog entry for a new release: \textttc{dch -i}
+  \end{itemize}
   \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}
@@ -626,7 +635,7 @@ override_dh_auto_build:
   \hbr
   \begin{itemize}
   \item Mind shares:\\
-    Classic debhelper: 40\% \hskip 1em CDBS: 23\% \hskip 1em  dh: 36\%
+    Classic debhelper: 36\% \hskip 1em CDBS: 21\% \hskip 1em  dh: 41\%
     \hbr
   \item Which one should I learn?
     \begin{itemize}
@@ -662,7 +671,8 @@ override_dh_auto_build:
 \begin{frame}{Building packages}
   \begin{itemize}
   \item \textttc{apt-get build-dep mypackage}\\
-    Installs the \textsl{build-dependencies} (for a package in the archive)
+    Installs the \textsl{build-dependencies} (for a package already in Debian)\\
+    Or \textttc{mk-build-deps -ir} (inside the package source tree)
     
     \br
   \item \textttc{debuild}: build, test with \texttt{lintian}, sign with GPG
@@ -683,7 +693,7 @@ override_dh_auto_build:
        see: \url{https://help.ubuntu.com/community/SbuildLVMHowto} )
     \end{itemize}
     \br
-  \item Generate \texttt{.deb} files and a \texttt{.changes} file
+  \item Generates \texttt{.deb} files and a \texttt{.changes} file
     \begin{itemize}
     \item \texttt{.changes}: describes what was built; used to upload the package
     \end{itemize}
@@ -713,7 +723,13 @@ override_dh_auto_build:
 \begin{frame}{Practical session 1: 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
+    download version 2.6.3-3 of the package (if you use Ubuntu 11.10 or
+    later, or Debian testing or unstable, use version 2.9-1 or 2.9-2 instead)
+    \begin{itemize}
+                  \item If the source package is not unpacked automatically, unpack it with
+                          \texttt{dpkg-source~-x~grep\_*.dsc}
+    \end{itemize}
+
   \item Look at the files in \texttt{debian/}.
     \begin{itemize}
     \item              How many binary packages are generated by this source package?
@@ -821,7 +837,8 @@ License:
          \hbr
   \item You need to learn \textsl{quilt}\\
     \url{http://pkg-perl.alioth.debian.org/howto/quilt.html}
-    
+    \hbr
+  \item Patch-system-agnostic tool in \texttt{devscripts}: \texttt{edit-patch}
   \end{itemize}
   \end{itemize}
 \end{frame}
@@ -829,13 +846,11 @@ License:
 \begin{frame}[fragile]{Documentation of patches}
   \begin{itemize}
          \item Standard headers at the beginning of the patch
-    \hbr
+    \br
   \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}
+  \vfill
 \seprule
   \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
 Description: Fix widget frobnication speeds
@@ -908,8 +923,8 @@ http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
   \end{itemize}
 \end{frame}
 
-\subsection{Packaging with a VCS (SVN, Git \& friends)}
-\begin{frame}[fragile]{Packaging with a VCS (SVN, Git, etc.)}
+\subsection{Packaging with a Version Control System (SVN, Git)}
+\begin{frame}[fragile]{Packaging with a Version Control System}
   \begin{itemize}
   \item Several tools to help manage branches and tags for your packaging work:\\
     \texttt{svn-buildpackage}, \texttt{git-buildpackage}
@@ -946,6 +961,31 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
 \end{itemize}
 \end{frame}
 
+\subsection{Backporting packages}
+\begin{frame}{Backporting packages}
+  \begin{itemize}
+  \item Goal: use a newer version of a package on an older system\\
+         e.g use \textsl{mutt} from Debian \textsl{unstable} on Debian \textsl{stable}
+       \br
+  \item General idea:
+         \begin{itemize}
+               \item Take the source package from Debian unstable
+               \hbr
+               \item Modify it so that it builds and works fine on Debian stable
+               \begin{itemize}
+                       \item Sometimes trivial (no changes needed)
+                       \item Sometimes difficult
+                       \item Sometimes impossible (many unavailable dependencies)
+               \end{itemize}
+       \end{itemize}
+       \br
+   \item Some backports are provided and supported by the Debian project\\
+          \url{http://backports.debian.org/}
+\end{itemize}
+\end{frame}
+
+
+
 \section{Maintaining packages in Debian}
 \subsection{Several ways to contribute to Debian}
 \begin{frame}{Several ways to contribute to Debian}
@@ -1013,6 +1053,32 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
   \end{itemize}
 \end{frame}
 
+\begin{frame}[fragile]{Adopting a package: example}
+\begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
+From: You <you@yourdomain>
+To: 640454@bugs.debian.org, control@bugs.debian.org
+Cc: Francois Marier <francois@debian.org>
+Subject: ITA: verbiste -- French conjugator
+
+retitle 640454 \textbf{ITA}: verbiste -- French conjugator
+owner 640454 !
+thanks
+
+Hi,
+
+I am using verbiste and I am willing to take care of the package.
+
+Cheers,
+
+You
+\end{lstlisting}
+
+\begin{itemize}
+\item Polite to contact the previous maintainer (especially if the package was RFAed, not orphaned)
+\item Very good idea to contact the upstream project
+\end{itemize}
+\end{frame}
+
 \subsection{Getting your package in Debian}
 \begin{frame}{Getting your package in Debian}
 \begin{itemize}
@@ -1068,15 +1134,15 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
   \item Debian Developers' Corner\\
     \url{http://www.debian.org/devel/}\\
     {\small Links to many resources about Debian development}
-    \br
+    \hbr
   \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
+    \hbr
   \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
+    \hbr
   \item Debian Policy\\
     \url{http://www.debian.org/doc/debian-policy/}\\
     
@@ -1084,7 +1150,7 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
       \item \small All the requirements that every package must satisfy
       \item \small Specific policies for Perl, Java, Python, \ldots
       \end{itemize}}
-    \br
+    \hbr
     
   \item Ubuntu Packaging Guide\\
     \url{https://wiki.ubuntu.com/PackagingGuide}
@@ -1245,6 +1311,27 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
 \end{enumerate}
 \end{frame}
 
+\section{Practical session 4: packaging a Ruby gem}
+\begin{frame}{Practical session 4: packaging a Ruby gem}
+\begin{enumerate}
+       \item Take a quick look at some documentation about Ruby packaging:\\
+               \begin{itemize}
+               \item \url{http://wiki.debian.org/Ruby}
+      \hbr
+               \item \url{http://wiki.debian.org/Teams/Ruby}
+      \hbr
+               \item \url{http://wiki.debian.org/Teams/Ruby/Packaging}
+      \hbr
+               \item \texttt{gem2deb(1)}, \texttt{dh\_ruby(1)} (in the \texttt{gem2deb} package)
+               \end{itemize}
+               \hbr
+       \item Create a basic Debian source package from the \texttt{net-ssh} gem:\\
+               \texttt{gem2deb net-ssh}
+       \hbr
+       \item Improve it so that it becomes a proper Debian package
+\end{enumerate}
+\end{frame}
+
 \section{Answers to practical sessions}
 
 \begin{frame}
@@ -1256,10 +1343,12 @@ Vcs-Svn: svn://svn.debian.org/pkg-perl/trunk/libwww-perl
 
 \subsection{Practical session 1: modifying the grep package}
 
-\begin{frame}{Practical session: modifying the grep package}
+\begin{frame}{Practical session 1: 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 Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
+    download version 2.6.3-3 of the package (if you use Ubuntu 11.10 or
+    later, or Debian testing or unstable, use version 2.9-1 or 2.9-2 instead)
+
        \item Look at the files in \texttt{debian/}.
                \begin{itemize}
                        \item           How many binary packages are generated by this source package?
@@ -1455,7 +1544,7 @@ gnujump.cron.d.ex   postrm.ex
 \end{lstlisting}
 \end{frame}
 
-\begin{frame}[fragile]{Step by step \ldots (2)}
+\begin{frame}[fragile]{Step by step\ldots (2)}
 \begin{itemize}
        \item Look at \texttt{debian/changelog}, \texttt{debian/rules}, \texttt{debian/control}\\
                (auto-filled by \textbf{dh\_make})
@@ -1482,7 +1571,7 @@ $\rightarrow$ Add \textbf{libsdl1.2-dev} to Build-Depends and install it.
 \end{itemize}
 \end{frame}
 
-\begin{frame}{Step by step \ldots (3)}
+\begin{frame}{Step by step\ldots (3)}
 \begin{itemize}
        \item After installing \texttt{libsdl1.2-dev, libsdl-image1.2-dev, libsdl-mixer1.2-dev}, the package builds fine.
                \hbr
@@ -1551,4 +1640,98 @@ $\rightarrow$ Add \textbf{libsdl1.2-dev} to Build-Depends and install it.
 \end{itemize}
 \end{frame}
 
+\subsection{Practical session 4: packaging a Ruby gem}
+\begin{frame}{Practical session 4: packaging a Ruby gem}
+\begin{enumerate}
+       \item Take a quick look at some documentation about Ruby packaging:\\
+               \begin{itemize}
+               \item \url{http://wiki.debian.org/Ruby}
+      \hbr
+               \item \url{http://wiki.debian.org/Teams/Ruby}
+      \hbr
+               \item \url{http://wiki.debian.org/Teams/Ruby/Packaging}
+      \hbr
+               \item \texttt{gem2deb(1)}, \texttt{dh\_ruby(1)} (in the \texttt{gem2deb} package)
+               \end{itemize}
+               \hbr
+       \item Create a basic Debian source package from the \texttt{net-ssh} gem:\\
+               \texttt{gem2deb net-ssh}
+       \hbr
+       \item Improve it so that it becomes a proper Debian package
+\end{enumerate}
+\end{frame}
+
+\begin{frame}{Step by step\ldots}
+\texttt{gem2deb net-ssh}:
+\begin{itemize}
+\item Downloads the gem from rubygems.org
+\item Creates a suitable .orig.tar.gz archive, and untar it
+\item Initializes a Debian source package based on the gem's metadata
+       \begin{itemize}
+               \item Named \texttt{ruby-\textsl{gemname}}
+       \end{itemize}
+\item Tries to build the Debian binary package (this might fail)
+\end{itemize}
+\br
+\texttt{dh\_ruby} (included in \textsl{gem2deb}) does the Ruby-specific tasks:
+\begin{itemize}
+       \item Build C extensions for each Ruby version
+       \item Copy files to their destination directory
+       \item Update shebangs in executable scripts
+       \item Run tests defined in \texttt{debian/ruby-tests.rb} or \texttt{debian/ruby-test-files.yaml}, as well as various other checks
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]{Step by step\ldots (2)}
+Improve the generated package:
+\begin{itemize}
+       \item Run \texttt{debclean} to clean the source tree. Look at \texttt{debian/}.
+               \hbr
+       \item \texttt{changelog} and \texttt{compat} should be correct
+               \hbr
+       \item Edit \texttt{debian/control}: uncomment \texttt{Homepage}, improve \texttt{Description}
+               \hbr
+       \item Write a proper \texttt{copyright} file based on the upstream files
+               \hbr
+       \item \texttt{ruby-net-ssh.docs}: install \texttt{README.rdoc}
+               \hbr
+       \item \texttt{ruby-tests.rb}: run the tests. In that case, it is enough to do:\\
+               \verb+$: << 'test' << 'lib' << '.'+\\
+               \verb+require 'test/test_all.rb'+
+\end{itemize}
+\end{frame}
+
+\begin{frame}[fragile]{Step by step\ldots (3)}
+Build the package.
+It fails to build. There are two problems:
+\begin{itemize}
+       \item You need to disable the \texttt{gem} call in the test suite.\\
+       In \texttt{test/common.rb}, remove the \verb+gem "test-unit"+ line:
+               \begin{itemize}
+                       \item \texttt{edit-patch disable-gem.patch}
+                       \item Edit \texttt{test/common.rb}, remove the \texttt{gem} line. Exit the sub-shell
+                       \item Describe the changes in \texttt{debian/changelog}
+                       \item Document the patch in \texttt{debian/patches/disable-gem.patch}
+               \end{itemize}
+               \hbr
+
+       \item The package lacks a build-dependency on \texttt{ruby-mocha},
+               which is used by the test suite (you might need to build your
+               package in a clean environment, using \texttt{pbuilder}, to
+               reproduce that problem)
+
+               \begin{itemize}
+                       \item Add \texttt{ruby-mocha} to the package's \texttt{Build-Depends}
+
+                       \item \textsl{gem2deb} copies the dependencies
+                               documented in the \textsl{gem} as comments in
+                               \texttt{debian/control}, but \textsl{mocha} is
+                               not listed as a development dependency by the
+                               gem (that's a bug in the gem)
+               \end{itemize}
+\end{itemize}
+\hbr
+Compare your package with the \texttt{ruby-net-ssh} package in the Debian archive
+\end{frame}
+
 \end{document}