continued.
[packaging-tutorial.git] / packaging-tutorial.tex
1 \documentclass[10pt,final,handout]{beamer}
2 \mode<presentation>
3 \usetheme{lucasdeb}
4 \usepackage{paralist}
5 \usepackage{wasysym}
6 \definecolor{darkgreen}{rgb}{0,.7,0}
7 \definecolor{darkred}{rgb}{.7,0,0}
8 \newcommand{\Smiley}{{\color{darkgreen}\smiley}}
9 \newcommand{\Frownie}{{\color{darkred}\frownie}}
10 \usepackage[utf8]{inputenc}
11 \usepackage{helvet}
12 \usepackage[OT1]{fontenc}
13 \usepackage{xspace}
14 \usepackage{verbatim}
15 \usepackage{comment}
16 \usepackage{tabularx}
17 \usepackage{listings}
18 \lstset{basicstyle=\ttfamily}
19 \beamertemplatetransparentcovereddynamic
20 \setbeamercovered{invisible}
21 \newcommand{\br}{\vskip 1em}
22 \newcommand{\hbr}{\vskip 0.5em}
23 \newcommand{\hhbr}{\vskip 0.25em}
24 \newcommand{\Arr}{\textbf{$\Rightarrow$}\xspace}
25 \newcommand{\arr}{\textbf{$\rightarrow$}\xspace}
26 \newcommand{\fixme}[1]{ {\color{red}\footnotesize\bf #1}}
27 \usepackage{listings}
28 \usepackage{tikz}
29
30 \renewcommand{\ttdefault}{aett}
31 \usepackage{aecompl}
32
33 \newcommand{\pedp}{\NoAutoSpaceBeforeFDP}
34
35 \usebackgroundtemplate{\includegraphics[width=\paperwidth]{figs/dslide8.pdf}}
36 \logo{\includegraphics[viewport=274 335 360 440,width=0.5cm]{figs/openlogo-nd.pdf}}
37 \hypersetup{pdftitle={An Introduction to Debian Packaging},bookmarks}
38 \title{An Introduction to Debian Packaging}
39 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
40 \institute{\includegraphics[viewport=274 335 360 440,width=1cm]{figs/openlogo-nd.pdf}}
41 \date{}
42
43 \newcommand{\nospace}[1]{{\NoAutoSpaceBeforeFDP{}#1}}%
44
45 \begin{document}
46
47 \frame{\titlepage}
48
49 \section{Introduction}
50 \subsection{Legal stuff}
51 \begin{frame}
52 \frametitle{Legal stuff}
53
54 Copyright \copyright 2011 Lucas Nussbaum -- lucas@debian.org
55 \br
56
57 {\small 
58 This document is free software: you can redistribute it and/or modify
59 it under either (at your option):
60 \begin{itemize}
61 \item The terms of the GNU General Public License as published by
62     the Free Software Foundation, either version 3 of the License, or
63     (at your option) any later version.\\
64     \url{http://www.gnu.org/licenses/gpl.html}
65     \hbr
66 \item The terms of the Creative Commons Attribution-ShareAlike 3.0 Unported License.\\
67         \url{http://creativecommons.org/licenses/by-sa/3.0/}
68 \end{itemize}
69 }
70 \end{frame}
71
72 \subsection{About this tutorial}
73 \begin{frame}{About this tutorial}
74 \begin{itemize}
75 \item Goal: tell you what you really need to know about Debian packaging
76         \br
77 \item Tries to keep a reasonable size
78         \begin{itemize}
79         \hbr
80                 \item No attempt to be complete
81                         \hbr
82                 \item You might need to read more documentation
83         \end{itemize}
84 \end{itemize}
85 \vfill
86 \begin{itemize}
87 \item Latest version:\\
88 \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git}
89         \br
90 \item Contribute:\\
91         \texttt{git clone git://git.debian.org/\~{}lucas/packaging-tutorial.git}
92         \br
93 \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
94 \end{itemize}
95 \end{frame}
96
97 \subsection{The Deb package format}
98 \begin{frame}[fragile]
99         \frametitle{Introduction: the Deb package format}
100 \begin{itemize}
101         \item One of the two most common packages format (with RPM)
102         \item Used by Debian and its derivatives (including Ubuntu)
103         \item A very powerful and convenient way to distribute software to users
104                 \pause
105         \item \texttt{.deb} file: an \texttt{ar} archive
106 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
107 $ ar tv wget_1.12-2.1_i386.deb
108 rw-r--r-- 0/0      4 Sep  5 15:43 2010 debian-binary
109 rw-r--r-- 0/0   2403 Sep  5 15:43 2010 control.tar.gz
110 rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
111 \end{lstlisting}
112 \begin{itemize}
113         \item \texttt{debian-binary}: version of the deb file format, \texttt{"2.0\textbackslash{}n"}
114         \item \texttt{control.tar.gz}: metadata about the package\\
115                 {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
116         \item \texttt{data.tar.gz}: data files of the package
117 \end{itemize}
118                 \pause
119 \item You could create your \texttt{.deb} files manually\\
120         {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
121 \item But most people don't do it that way
122 \end{itemize}
123 \hbr
124 \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
125 \end{frame}
126
127 \subsection{Tools you will need}
128 \begin{frame}{Tools you will need}
129         \begin{itemize}
130                 \item A Debian (or Ubuntu) system
131                         \br
132                 \item \textbf{build-essential} package: 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)
133                 \begin{itemize}
134                         \item includes a dependency on \textbf{dpkg-dev}, which contains basic Debian-specific tools to create packages
135                 \end{itemize}
136                 \br
137         \item \textbf{devscripts} package: contains many useful scripts for Debian maintainers
138         \end{itemize}
139
140         \br
141         Many other tools will also be mentioned later, such as \textbf{debhelper}, \textbf{cdbs}, \textbf{quilt}, \textbf{pbuilder}, \textbf{sbuild}, \textbf{svn-buildpackage}, \textbf{git-buildpackage}, \ldots
142 \end{frame}
143
144 \subsection{General packaging workflow}
145 \begin{frame}{General packaging workflow}
146 \begin{center}
147 \begin{tikzpicture}[
148         node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
149         arr/.style={very thick},
150         command/.style={text=rouge,font=\ttfamily},
151 ]
152         \node[node1] (us) at (1.5, 0) {upstream source};
153         \node[node1] (da) at (-1.5, 0) {Debian mirror};
154         \node[node1] (sp) at (0, -1.5) {source package};
155         \draw[arr,<-,dashed] (sp) -- (2.5,-1.5) node[right=0cm,text width=2.98cm,text centered,font=\small] {where most of the manual work is done};
156         \node[node1] (b1) at (-1.5, -3) {binary package};
157         \node[node1] (b2) at (1.5, -3) {binary package};
158         \draw[arr,<-,dashed] (b2) -- (3.5,-3) node[right,text centered,font=\ttfamily] {.deb\normalfont};
159         \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
160         \draw[arr,->] (da) -- (sp) node[pos=0.5,left,command] {apt-get source};
161         \draw[arr,->] (sp) -- (b1);
162         \draw[arr,->] (sp) -- (b2) node[pos=0.5,right,command] {debuild};
163         \node (dot) at (0,-4.5) {};
164         \draw[fill=black] (dot) circle (.05cm);
165         \draw[arr,->] (0,-3.5) -- (dot) node[pos=0.5,right] {test (\texttt{\color{rouge}lintian})};
166         \draw[arr,->] (dot) -- (-1,-5.5) node[pos=0.5,left] {install (\texttt{\color{rouge}debi})};
167         \draw[arr,->] (dot) -- (1,-5.5) node[pos=0.5,right] {upload (\texttt{\color{rouge}dput})};
168         \useasboundingbox (-4,-6) rectangle (6,0); % hack hack hack
169 \end{tikzpicture}
170 \end{center}
171 \end{frame}
172
173 \section{Creating source packages}
174 \subsection{Source packages formats}
175 \begin{frame}
176 \frametitle{Source package}
177 \begin{itemize}
178         \item One source package can generate several binary packages\\
179                 {\small the \texttt{\bfseries libtar} source generates the \texttt{\bfseries libtar} and \texttt{\bfseries libtar-dev} binary packages}
180                 \hbr
181         \item Two kinds of packages: (if unsure, use non-native)
182                 \begin{itemize}
183                                 \small
184                         \item Native packages: software developed inside Debian (\textsl{dpkg}, \textsl{apt})
185                         \item Non-native packages: software developed outside Debian
186                 \end{itemize}
187                 \hbr
188         \item Main file: \texttt{.dsc} (metadata)
189                 \hbr
190         \item Other files depending on the source format version
191         \begin{itemize}
192                 \item 1.0 -- native: \texttt{package\_version.tar.gz}
193                 \hbr
194                 \item 1.0 -- non-native:
195                 \begin{itemize}
196                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
197                         \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
198                 \end{itemize}
199                 \hbr
200                 \item 3.0 (quilt) -- also non-native, more recent:
201                 \begin{itemize}
202                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
203                         \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
204                 \end{itemize}
205         \end{itemize}
206 \end{itemize}
207 \br
208 (See \texttt{dpkg-source(1)} for exact details)
209 \end{frame}
210
211 \subsection{Source package example}
212 \begin{frame}[fragile]
213         \frametitle{Source package example (wget\_1.12-2.1.dsc)}
214 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
215 Format: 3.0 (quilt)
216 Source: wget
217 Binary: wget
218 Architecture: any
219 Version: 1.12-2.1
220 Maintainer: Noel Kothe <noel@debian.org>
221 Homepage: http://www.gnu.org/software/wget/
222 Standards-Version: 3.8.4
223 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo, libssl-dev (>= 0.9.8), dpatch, info2man
224 Checksums-Sha1: 
225  50d4ed2441e67db7aa5061d8a4dde41ee0e94248 2464747 wget_1.12.orig.tar.gz
226  d4c1c8bbe431d6131cbd7ed2e4fc37dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
227 Checksums-Sha256: 
228  7578ed0974e12caa71120581fa3962ee5a69f7175ddc3d6a6db0ecdcba65b572 2464747 wget_1.12.orig.tar.gz
229  1e9b0c4c00eae6b4172baae219a14857f4002382b9d7a289de7ab789c402ad78 48308 wget_1.12-2.1.debian.tar.gz
230 Files: 
231  141461b9c04e454dc8933c9d1f2abf83 2464747 wget_1.12.orig.tar.gz
232  e93123c934e3c141916f472f380278c2 48308 wget_1.12-2.1.debian.tar.gz
233 \end{lstlisting}
234 \end{frame}
235
236 \subsection{Retrieving source packages}
237 \begin{frame}
238 \frametitle{Retrieving an existing source package}
239 \begin{itemize}
240 \item From the Debian archive:
241         \begin{itemize}
242                 \item \texttt{apt-get source \textsl{package}}
243                 \item \texttt{apt-get source \textsl{package=version}}
244                 \item \texttt{apt-get source \textsl{package/release}}
245         \end{itemize}
246         (You need \texttt{deb-src} lines in \texttt{sources.list})
247         \br
248 \item From the Internet:
249         \begin{itemize}
250                 \item \texttt{dget \textsl{url-to.dsc}}
251                 \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\wget\_1.4.4-6.dsc}\\
252                         (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
253         \end{itemize}
254 \br
255 \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
256 \end{itemize}
257 \end{frame}
258
259 \subsection{Creating a basic source package}
260 \begin{frame}
261 \frametitle{Creating a basic source package}
262 \begin{itemize}
263         \item Download the upstream source
264                 \hbr
265         \item Rename to \texttt{\textsl{source\_package}\_\textsl{upstream\_version}.orig.tar.gz}
266                 \hbr
267         \item Untar it
268                 \hbr
269         \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
270                 \hbr
271         \item \texttt{debian/} directory created, with lots of files in it
272                 \begin{itemize}
273                                 \small
274                         \item That's where all the work will be done
275                 \end{itemize}
276                 \hbr
277         \item There are some alternatives to \texttt{dh\_make} that target more specific sets of packages: \textbf{dh-make-perl}, \textbf{dh-make-php}, \ldots
278 \end{itemize}
279 \end{frame}
280
281 \begin{frame}
282         \frametitle{Ideas dump}
283 \begin{itemize}
284 \item Debian source package -- files in debian/
285 \item Example: removing IPv6 support from wget
286 \item Packaging helpers: Debhelper7, CDBS
287 \item New source formats
288 \item Modifying the upstream source + patch systems
289 \item Per-language policies and packaging helpers
290 \item Maintainer scripts
291 \item Building packages -- dpkg-buildpackage pbuilder sbuild
292 \end{itemize}
293 \end{frame}
294
295 \section{Maintaining packages}
296 \begin{frame}
297         \frametitle{Ideas dump 2}
298 \begin{itemize}
299 \item Uploading debsign / dput -- private archive -- reprepro
300 \item Uploading new packages in Debian and Ubuntu
301 \item Joining teams
302 \item Adopting packages
303 \item Contributing new stuff vs adopting (WNPP, etc) vs co-maintaining
304 \item Packaging with VCSes debcheckout debcommit debrelease git-buildpackage svn-buildpackage
305 \end{itemize}
306 \end{frame}
307
308 \begin{frame}
309 \frametitle{Becoming a Debian contributor}
310 Several ways to contribute:
311 \hbr
312 \begin{itemize}
313 \item Bring new software to Debian
314 \begin{itemize}
315 \item Is that new software interesting/useful enough?
316 \item Are there alternatives already packaged in Debian?
317 \end{itemize}
318 \br
319 \item Adopt existing unmaintained packages
320 \begin{itemize}
321         \item Many unmaintained packages in Debian
322         \item Including some that you rely on, probably
323         \item Use \texttt{wnpp-alert} to find out if you have some installed
324 \end{itemize}
325 \br
326 \item Get involved in packaging teams
327 \begin{itemize}
328 \item Many teams that focus on set of packages
329 \item Full list on \url{http://wiki.debian.org/Teams}
330 \item An excellent way to work with more experienced contributors
331 \end{itemize}
332 \end{itemize}
333 \end{frame}
334
335 \begin{frame}
336 \frametitle{More interested in Ubuntu?}
337 \begin{itemize}
338         \item Ubuntu mainly manages the divergence with Debian
339         \br
340         \item Do not really focus on specific packages\\
341                 Instead, collaborate with Debian teams
342         \br
343         \item Recommend uploading new packages to Debian first\\
344         \fixme{ref}
345         \br
346         \item Possibly a better plan:
347         \begin{itemize}
348                 \item Get involved in a Debian team and act as a bridge with Ubuntu
349                         \hbr
350                 \item Help reduce divergence, triage bugs in Launchpad
351                         \hbr
352                 \item Many Debian tools can help:
353                 \begin{itemize}
354                 \item Ubuntu column on the Developer' packages overview
355                 \item Ubuntu box on the Packages Tracking System
356                 \item Receive launchpad bugmail via the PTS
357                 \end{itemize}
358         \end{itemize}
359 \end{itemize}
360 \end{frame}
361
362 \subsection{Adopting orphaned packages}
363 \begin{frame}{Adopting orphaned packages}
364 \begin{itemize}
365         \item Full list: \fixme{ref}
366         \item Installed on your machine: \texttt{wnpp-alert}
367         \item Different states:
368         \begin{itemize}
369                 \item \textbf{O}rphaned: the package is unmaintained\\
370                         Feel free to adopt it
371                 \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
372                         Maintainer looking for adopter, but continues work in the meantime\\
373                         Feel free to adopt it. A mail to the current maintainer is polite
374                 \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
375                         Someone intends to adopt the package\\
376                         You could propose your help!
377                 \item \textbf{RFH} (\textbf{R}equest \textbf{F}or \textbf{H}elp\\
378                         The maintainer is looking for help
379         \end{itemize}
380         \item Some unmaintained packages not detected \arr Not orphaned yet
381         \item Some packages are stalled in \textbf{ITA} state
382         \item When in doubt, ask \texttt{debian-qa@lists.debian.org}
383         \end{itemize}
384 \end{frame}
385
386 \section{Links}
387 \begin{frame}{Links}
388
389 http://wiki.debian.org/IntroDebianPackaging
390 http://www.debian.org/devel/
391 http://www.debian.org/doc/debian-policy/
392 http://www.debian.org/doc/developers-reference/
393 http://www.debian.org/doc/maint-guide/
394 https://wiki.ubuntu.com/PackagingGuide
395 lp:ubuntu-packaging-guide
396 debian-mentors
397 mentors.debian.net
398 library packaging guide
399 debhelper 7 slides
400 \end{frame}
401
402 \end{document}