cosmetic changes
[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     \hbr
26         \item Build the package
27     \hbr
28         \item We are now going to modify the package. Add a changelog entry and increase the version number.
29     \hbr
30         \item Now disable perl-regexp support (it is a \texttt{./configure} option)
31     \hbr
32         \item Rebuild the package
33     \hbr
34         \item Compare the original and the new package with debdiff
35     \hbr
36         \item Install the newly built package
37     \hbr
38         \item Cry if you messed up ;)
39 \end{enumerate}
40 \end{frame}
41
42 \begin{frame}{Fetching the source}
43 \begin{enumerate}
44         \item Go to \url{http://ftp.debian.org/debian/pool/main/g/grep/} and
45                 download version 2.6.3-3 of the package
46 \end{enumerate}
47 \begin{itemize}
48         \item Use dget to download the \texttt{.dsc} file:\\
49                 {\small \texttt{dget http://cdn.debian.net/debian/pool/main/g/grep/grep\_2.6.3-3.dsc}}
50                 \hbr
51         \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:\\
52                 \texttt{apt-get source grep=2.6.3-3}\\
53                 or \texttt{apt-get source grep/stable}\\
54                 or, if you feel lucky: \texttt{apt-get source grep}
55         \hbr
56         \item The \texttt{grep} source package is composed of three files:
57                 \begin{itemize}
58                         \item \texttt{grep\_2.6.3-3.dsc}
59                         \item \texttt{grep\_2.6.3-3.debian.tar.bz2}
60                         \item \texttt{grep\_2.6.3.orig.tar.bz2}
61                 \end{itemize}
62                 This is typical of the "3.0 (quilt)" format.
63         \hbr
64 \item If needed, uncompress the source with\\
65         \texttt{dpkg-source -x grep\_2.6.3-3.dsc}
66 \end{itemize}
67 \end{frame}
68
69 \begin{frame}{Looking around and building the package}
70         \begin{enumerate}
71                         \setcounter{enumi}{1}
72         \item Look at the files in \texttt{debian/}.
73                 \begin{itemize}
74                         \item           How many binary packages are generated by this source package?
75                         \item           Which packaging helper does this package use?
76                 \end{itemize}
77         \end{enumerate}
78         \hbr
79         \begin{itemize}
80                 \item According to \texttt{debian/control}, this package only generates one binary package, named \texttt{grep}.
81                         \hbr
82                 \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}.
83         \end{itemize}
84         \hbr
85         \begin{enumerate}
86                         \setcounter{enumi}{2}
87
88                 \item Build the package
89         \end{enumerate}
90         \hbr
91         \begin{itemize}
92                 \item Use \texttt{apt-get build-dep grep} to fetch the build-dependencies
93                 \item Then \texttt{debuild} or \texttt{dpkg-buildpackage -us -uc} (Takes about 1 min)
94         \end{itemize}
95 \end{frame}
96
97 \begin{frame}{Editing the changelog}
98         \begin{enumerate}
99                         \setcounter{enumi}{3}
100
101         \item We are now going to modify the package. Add a changelog entry and increase the version number.
102         \end{enumerate}
103         \hbr
104         \begin{itemize}
105                 \item \texttt{debian/changelog} is a text file. You could edit it and add a new entry manually.
106         \hbr
107                 \item Or you can use \texttt{dch -i}, which will add an entry and open the editor
108         \hbr
109                 \item The name and email can be defined using the \texttt{DEBFULLNAME} and \texttt{DEBEMAIL} environment variables
110         \hbr
111                 \item After that, rebuild the package: a new version of the package is built
112         \hbr
113                 \item Package versioning is detailed in section 5.6.12 of the Debian policy\\
114                         \url{http://www.debian.org/doc/debian-policy/ch-controlfields.html}
115         \end{itemize}
116 \end{frame}
117
118 \begin{frame}{Disabling Perl regexp support and rebuilding}
119         \begin{enumerate}
120                         \setcounter{enumi}{4}
121
122         \item Now disable perl-regexp support (it is a \texttt{./configure} option)
123         \item Rebuild the package
124         \end{enumerate}
125         \hbr
126         \begin{itemize}
127                 \item Check with \texttt{./configure --help}: the option to disable Perl regexp is \texttt{--disable-perl-regexp}
128         \hbr
129                 \item Edit \texttt{debian/rules} and find the \texttt{./configure} line
130         \hbr
131                 \item Add \texttt{--disable-perl-regexp}
132         \hbr
133                 \item Rebuild with \texttt{debuild} or \texttt{dpkg-buildpackage -us -uc}
134         \end{itemize}
135 \end{frame}
136
137 \begin{frame}{Comparing and testing the packages}
138         \begin{enumerate}
139                         \setcounter{enumi}{6}
140
141         \item Compare the original and the new package with debdiff
142         \item Install the newly built package
143         \end{enumerate}
144         \hbr
145         \begin{itemize}
146                 \item Compare the binary packages: \texttt{debdiff ../*changes}
147         \hbr
148                 \item Compare the source packages: \texttt{debdiff ../*dsc}
149         \hbr
150                 \item Install the newly built package: \texttt{debi}\\
151                         Or \texttt{dpkg -i ../grep\_<TAB>}
152         \hbr
153                 \item \texttt{grep -P foo} no longer works!
154         \end{itemize}
155 \br
156 \begin{enumerate}
157                 \setcounter{enumi}{8}
158         \item Cry if you messed up ;)
159 \end{enumerate}
160 \hbr
161 Or not: reinstall the previous version of the package:
162 \begin{itemize}
163         \item \texttt{apt-get install --reinstall grep=2.6.3-3} \textit{(= previous version)}
164 \end{itemize}
165 \end{frame}
166
167 \end{document}