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

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 download the set of files for the Debian source package with the dget command.

$ dget http://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 very slow proess with the remote APT package repository access.

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

$ 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 package with the dput command.

$ dput package_version-rev_arch.changes

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

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

See:

For the Debian packaging with the git-buildpackage package, the upstream branch on the remote repository origin is normally used to track the content of the released upstream tarball.

The upstream git repository can also be tracked by naming its remote repository as upstream instead of the default origin. Then you can easily cherry-pick recent upstream changes into the Debian revision by cherry-picking with the gitk command and using the gbp-pq command.

	Tip
	The git-import-orig command with the --upstream-vcs-tag option can create a nice packaging history by making a merge commit into upstream branch from the specified tag on the upstream git repository.

	Caution
	The content of the released upstream tarball may not match exactly with the corresponding content of the upstream git repository. It may contain some auto-generated files or miss some files. (Autotools, distutils, …)

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 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 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
	“The CDBS magically does the job for me with less typing” nor “I don’t understand the new dh syntax” can’t be the 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 reasons. 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 to build 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 to include the orig.tar.gz.

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 may be more focused on the feature enhancements and may be less eager for backward compatibilities etc. which are important aspect of the Debian packaging practice.

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

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