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 of your package)
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                 \hbr
137         \item \textbf{devscripts} package: contains many useful scripts for Debian maintainers
138                 \hbr
139         \item \textbf{lintian}: package checker
140         \end{itemize}
141
142         \br
143         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
144 \end{frame}
145
146 \subsection{General packaging workflow}
147 \begin{frame}{General packaging workflow}
148 \begin{center}
149 \begin{tikzpicture}[
150         node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
151         arr/.style={very thick},
152         command/.style={text=rouge,font=\ttfamily},
153 ]
154         \node[node1] (us) at (1.5, 0) {upstream source};
155         \node[node1] (da) at (-1.5, 0) {Debian mirror};
156         \node[node1] (sp) at (0, -2) {source package};
157         \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};
158         \node[node1] (b1) at (-1.5, -4) {binary package};
159         \node[node1] (b2) at (1.5, -4) {binary package};
160         \draw[arr,<-,dashed] (b2) -- (3.5,-4) node[right,text centered,font=\ttfamily] {.deb\normalfont};
161         \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
162         \draw[arr,->] (da) -- (sp) node[pos=0.5,left,command] {apt-get source};
163         \draw[arr,->] (sp) -- (b1);
164         \draw[arr,->] (sp) -- (b2) node[pos=0.5,right] {\texttt{\color{rouge}debuild} (build and test with \texttt{\color{rouge}lintian})};
165         \draw[arr,->] (0,-4.5) -- (-1,-6) node[pos=0.5,left] {install (\texttt{\color{rouge}debi})};
166         \draw[arr,->] (0,-4.5) -- (1,-6) node[pos=0.5,right] {upload (\texttt{\color{rouge}dput})};
167         \useasboundingbox (-4,-6) rectangle (6,0); % hack hack hack
168 \end{tikzpicture}
169 \end{center}
170 \end{frame}
171
172 \section{Creating source packages}
173 \subsection{Source packages formats}
174 \begin{frame}
175 \frametitle{Source package}
176 \begin{itemize}
177         \item One source package can generate several binary packages\\
178                 {\small the \texttt{\bfseries libtar} source generates the \texttt{\bfseries libtar} and \texttt{\bfseries libtar-dev} binary packages}
179                 \hbr
180         \item Two kinds of packages: (if unsure, use non-native)
181                 \begin{itemize}
182                                 \small
183                         \item Native packages: software developed inside Debian (\textsl{dpkg}, \textsl{apt})
184                         \item Non-native packages: software developed outside Debian
185                 \end{itemize}
186                 \hbr
187         \item Main file: \texttt{.dsc} (metadata)
188                 \hbr
189         \item Other files depending on the source format version
190         \begin{itemize}
191                 \item 1.0 -- native: \texttt{package\_version.tar.gz}
192                 \hbr
193                 \item 1.0 -- non-native:
194                 \begin{itemize}
195                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
196                         \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
197                 \end{itemize}
198                 \hbr
199                 \item 3.0 (quilt) -- also non-native, more recent:
200                 \begin{itemize}
201                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
202                         \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
203                 \end{itemize}
204         \end{itemize}
205 \end{itemize}
206 \br
207 (See \texttt{dpkg-source(1)} for exact details)
208 \end{frame}
209
210 \subsection{Source package example}
211 \begin{frame}[fragile]
212         \frametitle{Source package example (wget\_1.12-2.1.dsc)}
213 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
214 Format: 3.0 (quilt)
215 Source: wget
216 Binary: wget
217 Architecture: any
218 Version: 1.12-2.1
219 Maintainer: Noel Kothe <noel@debian.org>
220 Homepage: http://www.gnu.org/software/wget/
221 Standards-Version: 3.8.4
222 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo, libssl-dev (>= 0.9.8), dpatch, info2man
223 Checksums-Sha1: 
224  50d4ed2441e67db7aa5061d8a4dde41ee0e94248 2464747 wget_1.12.orig.tar.gz
225  d4c1c8bbe431d6131cbd7ed2e4fc37dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
226 Checksums-Sha256: 
227  7578ed0974e12caa71120581fa3962ee5a69f7175ddc3d6a6db0ecdcba65b572 2464747 wget_1.12.orig.tar.gz
228  1e9b0c4c00eae6b4172baae219a14857f4002382b9d7a289de7ab789c402ad78 48308 wget_1.12-2.1.debian.tar.gz
229 Files: 
230  141461b9c04e454dc8933c9d1f2abf83 2464747 wget_1.12.orig.tar.gz
231  e93123c934e3c141916f472f380278c2 48308 wget_1.12-2.1.debian.tar.gz
232 \end{lstlisting}
233 \end{frame}
234
235 \subsection{Retrieving source packages}
236 \begin{frame}
237 \frametitle{Retrieving an existing source package}
238 \begin{itemize}
239 \item From the Debian archive:
240         \begin{itemize}
241                 \item \texttt{apt-get source \textsl{package}}
242                 \item \texttt{apt-get source \textsl{package=version}}
243                 \item \texttt{apt-get source \textsl{package/release}}
244         \end{itemize}
245         (You need \texttt{deb-src} lines in \texttt{sources.list})
246         \br
247 \item From the Internet:
248         \begin{itemize}
249                 \item \texttt{dget \textsl{url-to.dsc}}
250                 \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\wget\_1.4.4-6.dsc}\\
251                         (\href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides all packages from Debian since 2005)
252         \end{itemize}
253 \br
254 \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
255 \end{itemize}
256 \end{frame}
257
258 \subsection{Creating a basic source package}
259 \begin{frame}
260 \frametitle{Creating a basic source package}
261 \begin{itemize}
262         \item Download the upstream source
263                 \hbr
264         \item Rename to \texttt{\textsl{source\_package}\_\textsl{upstream\_version}.orig.tar.gz}
265                 \hbr
266         \item Untar it
267                 \hbr
268         \item \texttt{cd \textsl{upstream\_source} \&\& dh\_make} (from the \textbf{dh-make} package)
269                 \hbr
270         \item \texttt{debian/} directory created, with lots of files in it
271                 \begin{itemize}
272                                 \small
273                         \item That's where all the work will be done
274                 \end{itemize}
275                 \hbr
276         \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
277 \end{itemize}
278 \end{frame}
279
280 \section{Maintaining packages}
281 \subsection{Becoming a Debian contributor}
282 \begin{frame}
283 \frametitle{Becoming a Debian contributor}
284 Several ways to contribute:
285 \hbr
286 \begin{itemize}
287 \item Bring new software to Debian
288 \begin{itemize}
289 \item Is that new software interesting/useful enough?
290 \item Are there alternatives already packaged in Debian?
291 \end{itemize}
292 \br
293 \item Adopt existing unmaintained packages
294 \begin{itemize}
295         \item Many unmaintained packages in Debian
296         \item Including some that you rely on, probably
297         \item Use \texttt{wnpp-alert} to find out if you have some installed
298 \end{itemize}
299 \br
300 \item Get involved in packaging teams
301 \begin{itemize}
302 \item Many teams that focus on set of packages, and need help
303 \item Full list on \url{http://wiki.debian.org/Teams}
304 \item An excellent way to work with more experienced contributors
305 \end{itemize}
306 \end{itemize}
307 \end{frame}
308
309 \begin{frame}
310 \frametitle{More interested in Ubuntu?}
311 \begin{itemize}
312         \item Ubuntu mainly manages the divergence with Debian
313         \br
314         \item Do not really focus on specific packages\\
315                 Instead, collaborate with Debian teams
316         \br
317         \item Usually recommend uploading new packages to Debian first\\
318                 \url{https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages/}
319         \br
320         \item Possibly a better plan:
321         \begin{itemize}
322                 \item Get involved in a Debian team and act as a bridge with Ubuntu
323                         \hbr
324                 \item Help reduce divergence, triage bugs in Launchpad
325                         \hbr
326                 \item Many Debian tools can help:
327                 \begin{itemize}
328                 \item Ubuntu column on the Developer' packages overview
329                 \item Ubuntu box on the Packages Tracking System
330                 \item Receive launchpad bugmail via the PTS
331                 \end{itemize}
332         \end{itemize}
333 \end{itemize}
334 \end{frame}
335
336 \subsection{Adopting orphaned packages}
337 \begin{frame}{Adopting orphaned packages}
338 \begin{itemize}
339         \item Full list: \url{http://www.debian.org/devel/wnpp/}
340         \item Installed on your machine: \texttt{wnpp-alert}
341         \item Different states:
342         \begin{itemize}
343                 \item \textbf{O}rphaned: the package is unmaintained\\
344                         Feel free to adopt it
345                 \item \textbf{RFA}: \textbf{R}equest \textbf{F}or \textbf{A}dopter\\
346                         Maintainer looking for adopter, but continues work in the meantime\\
347                         Feel free to adopt it. A mail to the current maintainer is polite
348                 \item \textbf{ITA}: \textbf{I}ntent \textbf{T}o \textbf{A}dopt\\
349                         Someone intends to adopt the package\\
350                         You could propose your help!
351                 \item \textbf{RFH} (\textbf{R}equest \textbf{F}or \textbf{H}elp\\
352                         The maintainer is looking for help
353         \end{itemize}
354         \item Some unmaintained packages not detected \arr not orphaned yet
355         \item When in doubt, ask \texttt{debian-qa@lists.debian.org}
356         \end{itemize}
357 \end{frame}
358
359 \subsection{Where to get help?}
360 \begin{frame}
361 \frametitle{Where to get help?}
362 Help you will need:
363 \begin{itemize}
364         \item Various advices and answers to your questions, code reviews
365         \item Sponsorship of your uploads, when your package is ready
366 \end{itemize}
367 \br
368 You can get help from:
369 \begin{itemize}
370         \item Other members of a packaging team $\leftarrow$ the best solution
371                 \begin{itemize}
372                         \item They know the specifics of your package
373                         \item You can become a member of the team
374                         \item See \url{http://wiki.debian.org/Teams}
375                 \end{itemize}
376         \hbr
377         \item The Debian Mentors group (if your package doesn't fit in a team)
378                 \begin{itemize}
379                         \item \url{http://wiki.debian.org/DebianMentorsFaq}
380                         \item Mailing list: \url{debian-mentors@lists.debian.org}
381                         \item IRC: \texttt{\#debian-mentors} on \texttt{irc.debian.org}
382                         \item \url{http://mentors.debian.net/}
383                 \end{itemize}
384 \end{itemize}
385 \end{frame}
386
387
388 \section{Resources}
389 \begin{frame}{Resources}
390         \begin{itemize}
391                 \item Debian Developers' Corner\\
392                         \url{http://www.debian.org/devel/}\\
393                         {\small Links to many resources about Debian development}
394                         \hbr
395                 \item Debian New Maintainers' Guide\\
396                         \url{http://www.debian.org/doc/maint-guide/}\\
397                         {\small An introduction to Debian packaging, but could use an update}
398                         \hbr
399                 \item Debian Developer's Reference\\
400                       \url{http://www.debian.org/doc/developers-reference/}\\
401                       {\small Mostly about Debian procedures, but also some best packaging practices (part 6)}
402                         \hbr
403
404               \item Debian Policy\\
405                     \url{http://www.debian.org/doc/debian-policy/}\\
406                     {\small All the requirements that every package must satisfy}
407                         \hbr
408
409                 \item Ubuntu Packaging Guide\\
410                         \url{https://wiki.ubuntu.com/PackagingGuide}
411         \end{itemize}
412 \end{frame}
413
414 \begin{frame}
415         \frametitle{Things not covered (yet)}
416 \begin{itemize}
417 \item Debian source package -- files in debian/
418 \item Example: removing IPv6 support from wget
419 \item Packaging helpers: Debhelper7, CDBS
420 \item New source formats
421 \item Modifying the upstream source + patch systems
422 \item Per-language policies and packaging helpers
423 \item Maintainer scripts
424 \item Building packages -- dpkg-buildpackage pbuilder sbuild
425 \br
426
427 \item Uploading debsign / dput -- private archive -- reprepro
428 \item Packaging with VCSes debcheckout debcommit debrelease git-buildpackage svn-buildpackage
429 \item link to debhelper 7 slides
430 \end{itemize}
431 \end{frame}
432
433
434 \end{document}