Chapter 7. Tips

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

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

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

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

これらのコマンドは、ソースパッケージ中でどんな変更をしたのか、バイナリーパッケージの中で意図せず削除したり配置を間違えたりしていないか、そしてバイナリーパッケージの更新時に不用意な変更をしていないかどうか、といった事柄を確認するのに便利です。

You can download the set of files for the Debian source package with the dget command.

$ dget https://www.example.org/path/to/package_version-rev.dsc

You should install generated packages with the debc command to test it locally.

$ debc package_version-rev_arch.changes

You should install generated packages with the piuparts command to test it automatically.

$ sudo piuparts package_version-rev_arch.changes

	Note
	This is a very slow process with remote APT package repository access.

After completing the test of the package, you can sign it with the debsign command.

For uploading source-only package (normal):

$ debsign package_version-rev_source.changes

For uploading binary package:

$ debsign package_version-rev_arch.changes

After signing the package with the debsign command, you can upload the set of files for the Debian source and binary packages with the dput command.

For uploading source-only package (normal):

$ dput package_version-rev_source.changes

For uploading binary package:

$ dput package_version-rev_arch.changes

The git-buildpackage package offers many commands to automate packaging activities using the git repository.

Package history management with the git-buildpackage package is becoming the standard practice for most Debian maintainers.

See:

The new dgit package offers commands to automate packaging activities using the git repository as an alternative to still popular gbp-buildpackage. Please read their guide:

Let’s assume that a bug report #bug_number was filed against your package, and it describes a problem that you can solve by editing the buggy file in the upstream source. Here’s what you need to do to create a new Debian revision of the package with the bugname.patch file recording the fix.

New Debian revision with the dquilt command. 

 $ dquilt push -a
 $ dquilt new bugname.patch
 $ dquilt add buggy
 $ vim buggy
   ...
 $ dquilt refresh
 $ dquilt header -e
 $ dquilt pop -a
 $ dch -i

Alternatively if the package is managed in the git repository using the git-buildpackage command with its default configuration:

New Debian revision with the gbp-pq command. 

 $ git checkout master
 $ gbp pq import
 $ vim buggy
 $ git add buggy
 $ git commit
 $ git tag pq/<newrev>
 $ gbp pq export
 $ gbp pq drop
 $ git add debian/patches/*
 $ dch -i
 $ git commit -a -m "Closes: #<bug_number>"

Please make sure to describe concisely the changes that fix reported bugs and close those bugs by adding “Closes: #<bug_number>” in the debian/changelog file.

	Tip
	Use a debian/changelog entry with a version string such as 1.0.1-1~rc1 when you experiment. Then, unclutter such changelog entries into a single entry for the official package.

Updating the package style is not a required activity for the update of a package. However, doing so lets you use the full capabilities of the modern debhelper system and the 3.0 source format.

The Common Debian Build System (CDBS) is a wrapper system over the debhelper package. The CDBS is based on the Makefile inclusion mechanism and configured by the DEB_* configuration variables set in the debian/rules file.

Before the introduction of the dh command to the debhelper package at the version 7, the CDBS was the only approach to create a simple and clean debian/rules file.

For many simple packages, the dh command alone allows us to make a simple and clean debian/rules file now. It is desirable to keep the build system simple and clean by not using the superfluous CDBS.

	Note
	Neither “the CDBS magically does the job for me with less typing” nor “I don’t understand the new dh syntax” can be an excuse to keep using the CDBS system.

For some complicated packages such as GNOME related ones, the CDBS is leveraged to automate their uniform packaging by the current maintainers with justification. If this is the case, please do not bother converting from the CDBS to the dh syntax.

	Note
	If you are working with a team of maintainers, please follow the established practice of the team.

When converting packages from the CDBS to the dh syntax, please use the following as your reference:

The default locale of the build environment is C.

Some programs such as the read function of Python3 change their behavior depending on the locale.

Adding the following code to the debian/rules file ensures building the program under the C.UTF-8 locale.

LC_ALL := C.UTF-8
export LC_ALL

When you first upload the package to the archive, you need to include the original orig.tar.gz source, too.

If the Debian revision number of the package is either 1 or 0, this is the default. Otherwise, you must provide the dpkg-buildpackage option -sa to the dpkg-buildpackage command.

	Tip
	On the other hand, the -sd option will force the exclusion of the original orig.tar.gz source.

	Tip
	Security uploads require including the orig.tar.gz file.

If you created multiple entries in the debian/changelog while skipping uploads, you must create a proper *_.changes file which includes all changes since the last upload. This can be done by specifying the dpkg-buildpackage option -v with the last uploaded version, e.g., 1.2.

Hints for the following can be found in the debhelper(7) manpage:

Although the upstream tarball has all the information to build the Debian package, it is not always easy to figure out which combination of options to use.

Also, the upstream package may be more focused on feature enhancements and may be less eager about backward compatibilities etc., which are an important aspect of Debian packaging practice.

The leveraging of information from other distributions is an option to address the above issues.

If the other distribution of interest is a Debian derivative one, it is trivial to reuse it.

When you face build problems or core dumps of generated binary programs, you need to resolve them yourself. That’s debug.

This is too deep a topic to describe here. So, let me just list few pointers and hints for some typical debug tools.