Chapter 7. Checking the package for errors

Table of Contents

7.1. Suspicious changes
7.2. Verifying a package's installation
7.3. Verifying a package's maintainer scripts
7.4. Using lintian
7.5. The debc command
7.6. The debdiff command
7.7. The interdiff command
7.8. The mc command

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

There are some techniques you should know for checking a package for errors before uploading it to the public archives.

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.

If you find a new autogenerated patch file such as debian-changes-* in the debian/patches directory after building your non-native Debian package in 3.0 (quilt) 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 dh-autoreconf as in Section 4.4.3, “Customization of rules file” or work around it with source/options as in Section 5.24, “source/options.

You must test your package for whether it installs without problems. The debi(1) command helps you to test installing all the generated binary packages.

$ sudo debi gentoo_0.9.12-1_i386.changes

To prevent installation problems on different systems, you must make sure that there are no filenames conflicting with other existing packages, using the Contents-i386 file downloaded from the Debian archive. The apt-file 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 update-alternatives(1)) in coordination with the maintainers of other affected packages, or declaring a Conflicts relationship in the debian/control file.

All maintainer scripts (that is, preinst, prerm, postinst, and postrm files) are hard to write correctly unless they are auto-generated by the debhelper programs. So do not use them if you are a novice maintainer (see Section 5.18, “{pre,post}{inst,rm}).

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 dpkg command as follows to test them:

$ sudo dpkg -r gentoo
$ sudo dpkg -P gentoo
$ sudo dpkg -i gentoo_version-revision_i386.deb

This should be done with sequences such as the following:

  • install the previous version (if needed).

  • upgrade it from the previous version.

  • downgrade it back to the previous version (optional).

  • purge it.

  • install the new package.

  • remove it.

  • install it again.

  • purge it.

If this is your first package, you should create dummy packages with different versions to test your package in advance to prevent future problems.

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.

Although downgrading is not officially supported, supporting it is a friendly gesture.

Run lintian(1) on your .changes file. The lintian command runs many test scripts to check for many common packaging errors. [75]

$ lintian -i -I --show-overrides gentoo_0.9.12-1_i386.changes

Of course, replace the filename with the name of the .changes file generated for your package. The output of the lintian command uses the following flags:

  • E: for error; a sure policy violation or packaging error.

  • W: for warning; a possible policy violation or packaging error.

  • I: for info; information on certain aspects of packaging.

  • N: for note; a detailed message to help your debugging.

  • O: for overridden; a message overridden by the lintian-overrides files but displayed by the --show-overrides option.

When you see warnings, tune the package to avoid them or verify that the warnings are spurious. If spurious, set up lintian-overrides files as described in Section 5.14, “{package.,source/}lintian-overrides.

Note that you can build the package with dpkg-buildpackage and run lintian on it in one command, if you use debuild(1) or pdebuild(1).

You can list files in the binary Debian package with the debc(1) command.

$ debc package.changes

You can compare file contents in two source Debian packages with the debdiff(1) command.

$ debdiff old-package.dsc new-package.dsc

You can also compare file lists in two sets of binary Debian packages with the debdiff(1) command.

$ debdiff old-package.changes new-package.changes

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.

You can compare two diff.gz files with the interdiff(1) command. This is useful for verifying that no inadvertent changes were made to the source by the maintainer when updating packages in the old 1.0 source format.

$ interdiff -z old-package.diff.gz new-package.diff.gz

The new 3.0 source format stores changes in multiple patch files as described in Section 5.25, “patches/*. You can trace changes of each debian/patches/* file using interdiff, too.

Many of these file inspection operations can be made into an intuitive process by using a file manager like mc(1) which will let you browse not only the contents of *.deb package files but also *.udeb, *.debian.tar.gz, *.diff.gz, and *.orig.tar.gz files.

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 rules file to compensate for this.

[75] You do not need to provide the lintian option -i -I --show-overrides if you customized /etc/devscripts.conf or ~/.devscripts as described in Section 6.3, “debuild command”.