mention buildd
[packaging-tutorial.git] / pract1-grep.tex
1 \documentclass[10pt,final]{beamer}
2 \mode<presentation>
3 \usetheme{debian}
4 \usepackage{debiantutorial}
5
6 \hypersetup{pdftitle={Practical session 1: grep},bookmarks}
7 \title[Practical session 1: grep]{Practical session 1:\\ Modifying the grep package}
8 \author[]{Lucas Nussbaum\\{\small\texttt{lucas@debian.org}}}
9 \institute{\includegraphics[viewport=274 335 360 440,width=1cm]{figs/openlogo-nd.pdf}}
10 \date{}
11
12 \begin{document}
13
14 \frame{\titlepage}
15
16 \begin{frame}{Practical session: modifying the grep package}
17 \begin{enumerate}
18         \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
19                 download version 2.6.3-3 of the package
20         \item Look at the files in \texttt{debian/}.
21                 \begin{itemize}
22                         \item           How many binary packages are generated by this source package?
23                         \item           Which packaging helper does this package use?
24                 \end{itemize}
25         \item Build the package
26         \item We are now going to modify the package. Add a changelog entry and increase the version number.
27         \item Now disable perl-regexp support (it is a \texttt{./configure} option)
28         \item Rebuild the package
29         \item Compare the original and the new package with debdiff
30         \item Install the newly built package
31         \item Cry if you messed up ;)
32 \end{enumerate}
33 \end{frame}
34
35 \begin{frame}{Fetching the source}
36 \begin{enumerate}
37         \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
38                 download version 2.6.3-3 of the package
39 \end{enumerate}
40 \begin{itemize}
41         \item Use dget to download the \texttt{.dsc} file:\\
42                 {\small \texttt{dget http://cdn.debian.net/debian/pool/main/g/grep/grep\_2.6.3-3.dsc}}
43                 \hbr
44         \item According to \texttt{http://packages.qa.debian.org/grep}, \texttt{grep} version 2.6.3-3 is currently in \textsl{stable} (\textsl{squeeze}). If you have \texttt{deb-src} lines for \textsl{squeeze} in your \texttt{/etc/apt/sources.list}, you can use:\\
45                 \texttt{apt-get source grep=2.6.3-3}\\
46                 or \texttt{apt-get source grep/stable}\\
47                 or, if you feel lucky: \texttt{apt-get source grep}
48         \hbr
49         \item The \texttt{grep} source package is composed of three files:
50                 \begin{itemize}
51                         \item \texttt{grep\_2.6.3-3.dsc}
52                         \item \texttt{grep\_2.6.3-3.debian.tar.bz2}
53                         \item \texttt{grep\_2.6.3.orig.tar.bz2}
54                 \end{itemize}
55                 This is typical of the "3.0 (quilt)" format.
56         \hbr
57 \item If needed, uncompress the source with\\
58         \texttt{dpkg-source -x grep\_2.6.3-3.dsc}
59 \end{itemize}
60 \end{frame}
61
62 \begin{frame}{Looking around and building the package}
63         \begin{enumerate}
64                         \setcounter{enumi}{1}
65         \item Look at the files in \texttt{debian/}.
66                 \begin{itemize}
67                         \item           How many binary packages are generated by this source package?
68                         \item           Which packaging helper does this package use?
69                 \end{itemize}
70         \end{enumerate}
71         \hbr
72         \begin{itemize}
73                 \item According to \texttt{debian/control}, this package only generates one binary package, named \texttt{grep}.
74                         \hbr
75                 \item According to \texttt{debian/rules}, this package is typical of \textsl{classic} debhelper packaging, without using \textsl{CDBS} or \textsl{dh}. One can see the various calls to \texttt{dh\_*} commands in \texttt{debian/rules}.
76         \end{itemize}
77         \hbr
78         \begin{enumerate}
79                         \setcounter{enumi}{2}
80
81                 \item Build the package
82         \end{enumerate}
83         \hbr
84         \begin{itemize}
85                 \item Use \texttt{apt-get build-dep grep} to fetch the build-dependencies
86                 \item Then \texttt{debuild} or \texttt{dpkg-buildpackage -us -uc} (Takes about 1 min)
87         \end{itemize}
88 \end{frame}
89
90 \begin{frame}{Editing the changelog}
91         \begin{enumerate}
92                         \setcounter{enumi}{3}
93
94         \item We are now going to modify the package. Add a changelog entry and increase the version number.
95         \end{enumerate}
96         \hbr
97         \begin{itemize}
98                 \item \texttt{debian/changelog} is a text file. You could edit it and add a new entry manually.
99         \hbr
100                 \item Or you can use \texttt{dch -i}, which will add an entry and open the editor
101         \hbr
102                 \item The name and email can be defined using the \texttt{DEBFULLNAME} and \texttt{DEBEMAIL} environment variables
103         \hbr
104                 \item After that, rebuild the package: a new version of the package is built
105         \hbr
106                 \item Package versioning is detailed in section 5.6.12 of the Debian policy\\
107                         \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
108         \end{itemize}
109 \end{frame}
110
111 \begin{frame}{Disabling Perl regexp support and rebuilding}
112         \begin{enumerate}
113                         \setcounter{enumi}{4}
114
115         \item Now disable perl-regexp support (it is a \texttt{./configure} option)
116         \item Rebuild the package
117         \end{enumerate}
118         \hbr
119         \begin{itemize}
120                 \item Check with \texttt{./configure --help}: the option to disable Perl regexp is \texttt{--disable-perl-regexp}
121         \hbr
122                 \item Edit \texttt{debian/rules} and find the \texttt{./configure} line
123         \hbr
124                 \item Add \texttt{--disable-perl-regexp}
125         \hbr
126                 \item Rebuild with \texttt{debuild} or \texttt{dpkg-buildpackage -us -uc}
127         \end{itemize}
128 \end{frame}
129
130 \begin{frame}{Comparing and testing the packages}
131         \begin{enumerate}
132                         \setcounter{enumi}{6}
133
134         \item Compare the original and the new package with debdiff
135         \item Install the newly built package
136         \end{enumerate}
137         \hbr
138         \begin{itemize}
139                 \item Compare the binary packages: \texttt{debdiff ../*changes}
140         \hbr
141                 \item Compare the source packages: \texttt{debdiff ../*dsc}
142         \hbr
143                 \item Install the newly built package: \texttt{debi}\\
144                         Or \texttt{dpkg -i ../grep\_<TAB>}
145         \hbr
146                 \item \texttt{grep -P foo} no longer works!
147         \end{itemize}
148 \br
149 \begin{enumerate}
150                 \setcounter{enumi}{8}
151         \item Cry if you messed up ;)
152 \end{enumerate}
153 \hbr
154 Or not: reinstall the previous version of the package:
155 \begin{itemize}
156         \item \texttt{apt-get install --reinstall grep=2.6.3-3} \textit{(= previous version)}
157 \end{itemize}
158 \end{frame}
159
160 \end{document}