<chapter id="checkit"><title>Checking the package for errors</title>
<para>
The rewrite of this tutorial document with updated contents and more practical examples is available as <ulink url="&guidedeb;">Guide for Debian Maintainers</ulink>.  Please use this new tutorial as the primary tutorial document.
</para>
<para>
There are some techniques you should know for checking a package for errors
before uploading it to the public archives.
</para>
<para>
It's also a good idea to carry out testing on a machine other than your own.  You must watch
closely for any warnings or errors for all the tests described here.
</para>
<section id="inadvent"><title>Suspicious changes</title>
<para>
If you find a new autogenerated patch file such as
<filename>debian-changes-*</filename> in the
<filename>debian/patches</filename> directory after building your non-native
Debian package in <literal>3.0 (quilt)</literal> format, chances are you
changed some files by accident or the build script modified the upstream
source.  If it is your mistake, fix it.  If it is caused by the build script,
fix the root cause with <command>dh-autoreconf</command> as in 
<xref linkend="customrules"/> or work around it with
<filename>source/options</filename> as in <xref linkend="sourceopt"/>.
</para>
</section>
<section id="pinstall"><title>Verifying a package's installation</title>
<para>
You must test your package for whether it installs without problems.  The <citerefentry>
<refentrytitle>debi</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
command helps you to test installing all the generated binary packages.
</para>
<screen>
$ sudo debi gentoo_0.9.12-1_i386.changes
</screen>
<para>
To prevent installation problems on different systems, you must make
sure that there are no filenames conflicting with other existing packages,
using the
<filename>Contents-<replaceable>i386</replaceable></filename> file downloaded
from the Debian archive.
The <command>apt-file</command> command may be handy for this task.  If there
are collisions, please take action to avoid this real problem, whether by
renaming the file, moving a common file to a separate package that
multiple packages can depend on, using the alternatives mechanism (see
<citerefentry><refentrytitle>update-alternatives</refentrytitle>
<manvolnum>1</manvolnum></citerefentry>) in coordination with the
maintainers of other affected packages, or declaring a
<literal>Conflicts</literal> relationship in the
<filename>debian/control</filename> file.
</para>
</section>
<section id="pmaintscripts"><title>Verifying a package's maintainer scripts</title>
<para>
All maintainer scripts (that is,
<filename>preinst</filename>, <filename>prerm</filename>,
<filename>postinst</filename>, and <filename>postrm</filename> files) are
hard to write correctly unless they are auto-generated by the
<systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
a novice maintainer (see <xref linkend="maintscripts"/>).
</para>
<para>
If the package makes use of these non-trivial maintainer scripts, be sure to test not only for install but also for remove,
purge, and upgrade processes.  Many maintainer script bugs show up
when packages are removed or purged.  Use the <command>dpkg</command> command
as follows to test them:
</para>
<screen>
$ sudo dpkg -r gentoo
$ sudo dpkg -P gentoo
$ sudo dpkg -i gentoo_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>i386</replaceable>.deb
</screen>
<para>
This should be done with sequences such as the following:
</para>
<itemizedlist>
<listitem>
<para>
install the previous version (if needed).
</para>
</listitem>
<listitem>
<para>
upgrade it from the previous version.
</para>
</listitem>
<listitem>
<para>
downgrade it back to the previous version (optional).
</para>
</listitem>
<listitem>
<para>
purge it.
</para>
</listitem>
<listitem>
<para>
install the new package.
</para>
</listitem>
<listitem>
<para>
remove it.
</para>
</listitem>
<listitem>
<para>
install it again.
</para>
</listitem>
<listitem>
<para>
purge it.
</para>
</listitem>
</itemizedlist>
<para>
If this is your first package, you should create dummy packages with different
versions to test your package in advance to prevent future problems.
</para>
<para>
Bear in mind that if your package has previously been released in Debian,
people will often be upgrading to your package from the version that was in the
last Debian release.  Remember to test upgrades from that version too.
</para>
<para>
Although downgrading is not officially supported, supporting it is a
friendly gesture.
</para>
</section>
<section id="lintians"><title>Using <systemitem role="package">lintian</systemitem></title>
<para>
Run <citerefentry> <refentrytitle>lintian</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> on your <filename>.changes</filename>
file.  The <command>lintian</command> command runs many test scripts to check
for many common packaging errors.  <footnote><para> You do not need to provide
the <command>lintian</command> option <literal>-i -I --show-overrides</literal>
if you customized <filename>/etc/devscripts.conf</filename> or
<filename>~/.devscripts</filename> as described in <xref linkend="debuild"/>.
</para> </footnote>
</para>
<screen>
$ lintian -i -I --show-overrides gentoo_0.9.12-1_i386.changes
</screen>
<para>
Of course, replace the filename with the name of the
<filename>.changes</filename> file generated for your package.  The output of
the <command>lintian</command> command uses the following flags:
</para>
<itemizedlist>
<listitem>
<para>
<literal>E:</literal> for error; a sure policy violation or packaging error.
</para>
</listitem>
<listitem>
<para>
<literal>W:</literal> for warning; a possible policy violation or packaging
error.
</para>
</listitem>
<listitem>
<para>
<literal>I:</literal> for info; information on certain aspects of packaging.
</para>
</listitem>
<listitem>
<para>
<literal>N:</literal> for note; a detailed message to help your debugging.
</para>
</listitem>
<listitem>
<para>
<literal>O:</literal> for overridden; a message overridden by the
<filename>lintian-overrides</filename> files but displayed by the
<literal>--show-overrides</literal> option.
</para>
</listitem>
</itemizedlist>
<para>
When you see warnings, tune the package to avoid them or verify that the warnings are
spurious.  If spurious, set up <filename>lintian-overrides</filename> files as
described in <xref linkend="lintian"/>.
</para>
<para>
Note that you can build the package with <command>dpkg-buildpackage</command>
and run <command>lintian</command> on it in one command, if you use <citerefentry>
<refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
or <citerefentry> <refentrytitle>pdebuild</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</section>
<section id="debc"><title>The <command>debc</command> command</title>
<para>
You can list files in the binary Debian package with the <citerefentry>
<refentrytitle>debc</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
command.
</para>
<screen>
$ debc <replaceable>package</replaceable>.changes
</screen>
</section>
<section id="debdiff"><title>The <command>debdiff</command> command</title>
<para>
You can compare file contents in two source Debian packages with the
<citerefentry> <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> command.
</para>
<screen>
$ debdiff <replaceable>old-package</replaceable>.dsc <replaceable>new-package</replaceable>.dsc
</screen>
<para>
You can also compare file lists in two sets of binary Debian packages with the
<citerefentry> <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> command.
</para>
<screen>
$ debdiff <replaceable>old-package</replaceable>.changes <replaceable>new-package</replaceable>.changes
</screen>
<para>
These are useful to identify what has been changed in the source packages
and to check for inadvertent changes made when updating binary
packages, such as unintentionally misplacing or removing files.
</para>
</section>
<section id="interdiff"><title>The <command>interdiff</command> command</title>
<para>
You can compare two <filename>diff.gz</filename> files with the <citerefentry>
<refentrytitle>interdiff</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry> command.  This is useful for verifying that no inadvertent
changes were made to the source by the maintainer when updating packages in the
old <literal>1.0</literal> source format.
</para>
<screen>
$ interdiff -z <replaceable>old-package</replaceable>.diff.gz <replaceable>new-package</replaceable>.diff.gz
</screen>
<para>
The new <literal>3.0</literal> source format stores changes in multiple patch
files as described in <xref linkend="patches"/>.  You can trace changes of each
<filename>debian/patches/*</filename> file using <command>interdiff</command>, too.
</para>
</section>
<section id="mc"><title>The <command>mc</command> command</title>
<para>
Many of these file inspection operations can be made into an intuitive process
by using a file manager like <citerefentry> <refentrytitle>mc</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> which will let you browse not only the
contents of <filename>*.deb</filename> package files but also
<filename>*.udeb</filename>, <filename>*.debian.tar.gz</filename>,
<filename>*.diff.gz</filename>, and <filename>*.orig.tar.gz</filename> files.
</para>
<para>
Be on the lookout for extra unneeded files or zero length files, both in the
binary and source package.  Often cruft doesn't get cleaned up properly; adjust
your <filename>rules</filename> file to compensate for this.
</para>
</section>
</chapter>