general workflow, source package, retrieving source package
[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{About this document}
51 \begin{frame}
52 \frametitle{About this document}
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 \centerline{\rule{0.7\linewidth}{0.3mm}}
71 \begin{itemize}
72 \item Latest version:\\
73 \url{http://git.debian.org/?p=users/lucas/packaging-tutorial.git}
74         \br
75 \item Contribute:\\
76         \texttt{git clone git://git.debian.org/\~{}lucas/packaging-tutorial.git}
77         \br
78 \item Feedback: \href{mailto:lucas@debian.org}{\textbf{\texttt{lucas@debian.org}}}
79 \end{itemize}
80 \end{frame}
81
82 \subsection{The Deb package format}
83 \begin{frame}[fragile]
84         \frametitle{Introduction: the Deb package format}
85 \begin{itemize}
86         \item One of the two most common packages format (with RPM)
87         \item Used by Debian and its derivatives (including Ubuntu)
88         \item A very powerful and convenient way to distribute software to users
89                 \pause
90         \item \texttt{.deb} file: an \texttt{ar} archive
91 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
92 $ ar tv wget_1.12-2.1_i386.deb
93 rw-r--r-- 0/0      4 Sep  5 15:43 2010 debian-binary
94 rw-r--r-- 0/0   2403 Sep  5 15:43 2010 control.tar.gz
95 rw-r--r-- 0/0 751613 Sep  5 15:43 2010 data.tar.gz
96 \end{lstlisting}
97 \begin{itemize}
98         \item \texttt{debian-binary}: version of the deb file format, \texttt{"2.0\textbackslash{}n"}
99         \item \texttt{control.tar.gz}: metadata about the package\\
100                 {\small \texttt{\textbf{control}, md5sums, (pre|post)(rm|inst), triggers, shlibs}, \ldots}
101         \item \texttt{data.tar.gz}: data files of the package
102 \end{itemize}
103                 \pause
104 \item You could create your \texttt{.deb} files manually\\
105         {\footnotesize \url{http://tldp.org/HOWTO/html\_single/Debian-Binary-Package-Building-HOWTO/}}
106 \item But most people don't do it that way
107 \end{itemize}
108 \hbr
109 \centerline{\textbf{This tutorial: create Debian packages, the Debian way}}
110 \end{frame}
111
112 \begin{frame}{Tools you will need}
113         \begin{itemize}
114                 \item A Debian (or Ubuntu) system
115                         \br
116                 \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)
117                 \begin{itemize}
118                         \item includes a dependency on \textbf{dpkg-dev}, which contains basic Debian-specific tools to create packages
119                 \end{itemize}
120                 \br
121         \item \textbf{devscripts} package: contains many useful scripts for Debian maintainers
122         \end{itemize}
123
124         \br
125         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
126 \end{frame}
127
128 \begin{frame}{General packaging workflow}
129 \begin{center}
130 \begin{tikzpicture}[
131         node1/.style={shape=rectangle,draw=rouge,fill=debianbackgroundblue,thick},
132         arr/.style={very thick},
133         command/.style={text=rouge,font=\ttfamily},
134 ]
135         \node[node1] (us) at (0, 0) {upstream source};
136         \node[node1] (sp) at (0, -1.5) {source package};
137         \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};
138         \node[node1] (b1) at (-1.5, -3) {binary package};
139         \node[node1] (b2) at (1.5, -3) {binary package};
140         \draw[arr,<-,dashed] (b2) -- (3.5,-3) node[right,text centered,font=\ttfamily] {.deb\normalfont};
141         \draw[arr,->] (us) -- (sp) node[pos=0.5,right,command] {dh\_make};
142         \draw[arr,->] (sp) -- (b1);
143         \draw[arr,->] (sp) -- (b2) node[pos=0.5,right,command] {debuild};
144         \node (dot) at (0,-4.5) {};
145         \draw[fill=black] (dot) circle (.05cm);
146         \draw[arr,->] (0,-3.5) -- (dot) node[pos=0.5,right] {test (\texttt{\color{rouge}lintian})};
147         \draw[arr,->] (dot) -- (-1,-5.5) node[pos=0.5,left] {install (\texttt{\color{rouge}debi})};
148         \draw[arr,->] (dot) -- (1,-5.5) node[pos=0.5,right] {upload (\texttt{\color{rouge}dput})};
149         \useasboundingbox (-3,-6) rectangle (6,0); % hack hack hack
150 \end{tikzpicture}
151 \end{center}
152 \end{frame}
153
154 \begin{frame}
155 \frametitle{Source package}
156 \begin{itemize}
157         \item One source package can generate several binary packages\\
158                 {\small the \texttt{\bfseries libtar} source generates the \texttt{\bfseries libtar} and \texttt{\bfseries libtar-dev} binary packages}
159                 \hbr
160         \item Two kinds of packages: (if unsure, use non-native)
161                 \begin{itemize}
162                                 \small
163                         \item Native packages: software developed inside Debian (\textsl{dpkg}, \textsl{apt})
164                         \item Non-native packages: software developed outside Debian
165                 \end{itemize}
166                 \hbr
167         \item Main file: \texttt{.dsc} (metadata)
168                 \hbr
169         \item Other files depending on the source format version
170         \begin{itemize}
171                 \item 1.0 -- native: \texttt{package\_version.tar.gz}
172                 \hbr
173                 \item 1.0 -- non-native:
174                 \begin{itemize}
175                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
176                         \item \texttt{pkg\_debver.diff.gz} : patch to add Debian-specific changes
177                 \end{itemize}
178                 \hbr
179                 \item 3.0 (quilt) -- also non-native, more recent:
180                 \begin{itemize}
181                         \item \texttt{pkg\_ver.orig.tar.gz} : upstream source
182                         \item \texttt{pkg\_debver.debian.tar.gz} : tarball with the Debian changes
183                 \end{itemize}
184         \end{itemize}
185 \end{itemize}
186 \br
187 (See \texttt{dpkg-source(1)} for exact details)
188 \end{frame}
189
190 \begin{frame}[fragile]
191         \frametitle{Source package example (wget\_1.12-2.1.dsc)}
192 \begin{lstlisting}[basicstyle=\ttfamily\footnotesize]
193 Format: 3.0 (quilt)
194 Source: wget
195 Binary: wget
196 Architecture: any
197 Version: 1.12-2.1
198 Maintainer: Noel Kothe <noel@debian.org>
199 Homepage: http://www.gnu.org/software/wget/
200 Standards-Version: 3.8.4
201 Build-Depends: debhelper (>> 5.0.0), gettext, texinfo, libssl-dev (>= 0.9.8), dpatch, info2man
202 Checksums-Sha1: 
203  50d4ed2441e67db7aa5061d8a4dde41ee0e94248 2464747 wget_1.12.orig.tar.gz
204  d4c1c8bbe431d6131cbd7ed2e4fc37dd7cef3611 48308 wget_1.12-2.1.debian.tar.gz
205 Checksums-Sha256: 
206  7578ed0974e12caa71120581fa3962ee5a69f7175ddc3d6a6db0ecdcba65b572 2464747 wget_1.12.orig.tar.gz
207  1e9b0c4c00eae6b4172baae219a14857f4002382b9d7a289de7ab789c402ad78 48308 wget_1.12-2.1.debian.tar.gz
208 Files: 
209  141461b9c04e454dc8933c9d1f2abf83 2464747 wget_1.12.orig.tar.gz
210  e93123c934e3c141916f472f380278c2 48308 wget_1.12-2.1.debian.tar.gz
211 \end{lstlisting}
212 \end{frame}
213
214 \begin{frame}
215 \frametitle{Retrieving an existing source package}
216 \begin{itemize}
217 \item From the Debian archive:
218         \begin{itemize}
219                 \item \texttt{apt-get source \textsl{package}}
220                 \item \texttt{apt-get source \textsl{package=version}}
221                 \item \texttt{apt-get source \textsl{package/release}}
222         \end{itemize}
223         \br
224 \item From the Internet:
225         \begin{itemize}
226                 \item \texttt{dget \textsl{url-to-.dsc}}
227                 \item \texttt{dget http://snapshot.debian.org/archive/debian-archive/\\20090802T004153Z/debian/dists/bo/main/source/web/\\wget\_1.4.4-6.dsc}\\
228                         \href{http://snapshot.debian.org/}{\ttfamily snapshot.d.o} provides the history of Debian since 2005
229         \end{itemize}
230 \br
231 \item Once downloaded, extract with \texttt{dpkg-source -x \textsl{file.dsc}}
232 \end{itemize}
233 \end{frame}
234 \begin{frame}
235         \frametitle{Ideas dump}
236 \begin{itemize}
237 \item Creating a basic Debian source package
238 \item Debian source package -- files in debian/
239 \item Example: removing IPv6 support from wget
240 \item Debhelper7
241 \item CDBS
242 \item New source formats
243 \item Modifying the upstream source Patch systems
244 \item Per-language policies and packaging helpers
245 \item Maintainer scripts
246 \item Building packages -- dpkg-buildpackage pbuilder sbuild
247 \item Packaging with VCSes debcheckout debcommit debrelease git-buildpackage svn-buildpackage
248 \item Uploading debsign / dput -- private archive -- reprepro
249 \item Contributing the package to Debian and Ubuntu
250
251 \item Contributing new stuff vs adopting (WNPP, etc) vs co-maintaining
252 \end{itemize}
253 \end{frame}
254
255 \section{Links}
256 \begin{frame}{Links}
257
258 http://wiki.debian.org/IntroDebianPackaging
259 http://www.debian.org/devel/
260 http://www.debian.org/doc/debian-policy/
261 http://www.debian.org/doc/developers-reference/
262 http://www.debian.org/doc/maint-guide/
263 https://wiki.ubuntu.com/PackagingGuide
264 lp:ubuntu-packaging-guide
265 debian-mentors
266 mentors.debian.net
267 library packaging guide
268 debhelper 7 slides
269 \end{frame}
270
271 \end{document}