Chapter 7. Tips

Table of Contents

7.1. debdiff
7.2. dget
7.3. debc
7.4. piuparts
7.5. debsign
7.6. dput
7.7. bts
7.8. git-buildpackage
7.8.1. gbp import-dscs --debsnap
7.8.2. Upstream git repository
7.9. dgit
7.9.1. Snapshot upstream tarball (alternative git deborig approach)
7.10. chroot
7.11. New Debian revision
7.12. New upstream release
7.12.1. uupdate + tarball
7.12.2. uscan
7.12.3. gbp
7.12.4. gbp + uscan
7.13. 3.0 source format
7.14. CDBS
7.15. Build under UTF-8
7.16. UTF-8 conversion
7.17. Upload orig.tar.gz
7.18. Skipped uploads
7.19. Advanced packaging
7.20. Other distros
7.21. Debug

Here are some notable tips about Debian packaging.

Debian now enforces the source-only upload when developing packages. So there may be 2 different *.changes files:

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

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] 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

After uploading the package, you will receive bug reports. It is an important duty of a package maintainer to manage these bugs properly as described in 5.8. Handling bugs of the “Debian Developer’s Reference”.

The bts command is a handy tool to manage bugs on the Debian Bug Tracking System.

$ bts severity 123123 wishlist , tags -1 pending

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

  • gbp import-dsc: import the previous Debian source package to the git repository.
  • gbp import-orig: import the new upstream tar to the git repository.

    • The --pristine-tar option for the git import-orig command enables storing the upstream tarball in the same git repository.
    • The --uscan option as the last argument of the gbp import-orig command enables downloading and committing the new upstream tarball into the git repository.
  • gbp dch: generate the Debian changelog from the git commit messages.
  • gbp buildpackage: build the Debian binary package from the git repository.

    • The sbuild package can be used as its clean chroot build backend either by configuration or adding --git-builder='sbuild -A -s --source-only-changes -v -d unstable'
  • gbp pull: update the debian, upstream and pristine-tar branches safely from the remote repository.
  • The gbp pq, git-dpm or quilt (or alias dquilt) commands are used to manage quilt patches.

    • The dquilt command is the simplest to learn and requires you to commit the resulting files manually with the git command to the master branch.
    • The “gbp pq” command provides the equivalent functionality of patch set management without using dquilt and eases including upstream git repository changes by cherry-picking.
    • The “git dpm” command provides more enhanced functionality than that of the ‘gbp pq’' command.

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


[Tip] Tip

Relax. You don’t need to use all the wrapper tools. Use only ones which match your needs.

For Debian source packages named <source-package> recorded in the archive, an initial git repository with all of the Debian version history can be generated as follows.

$ gbp import-dscs --debsnap --pristine-tar '<source-package>'

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:

  • dgit-maint-merge(7) — for dpkg-source "Format: 3.0 (quilt)" package with its changes flowing both ways between the upstream Git repository and the Debian Git repository which are tightly coupled.
  • dgit-maint-debrebase(7) — for dpkg-source "Format: 3.0 (quilt)" package with its changes flowing mostly one way from the upstream Git repository to the Debian Git repository.
  • dgit-maint-gbp(7) — for dpkg-source "Format: 3.0 (quilt)" package with its Debian Git repository which is kept usable also for people using gbp-buildpackage(1).
  • dgit-maint-native(7) — for dpkg-source "Format: 3.0 (native)" package in the Debian Git repository.

The dgit(1) command can push the easy-to-trace change history to the site and can upload Debian package to the Debian repository properly without using dput(1).

  • dgit push-source — for uploading source-only package (normal)
  • dgit push — for uploading binary package

If you already use main and upstream branches in the Debian packaging repository (, you can use your local upstream-vcs-main branch to track the main branch of the upstream-vcs repository as:

 $ git fetch upstream-vcs main:upstream-vcs-main

Cherry picking bug fix commits from latest upstream commits are intuitive operation with dgit-maint-merge(7) and dgit-maint-debrebase(7). Just right-click those commits interactively on the upstream-vcs-main branch of the gitk(1) GUI dialog.

For quasi-native Debian binary package scheme situation described in Section 6.2, “Snapshot upstream tarball (-d, -t)” can be addressed using alternative git deborig approach adopting the dgit-maint-merge(7) scheme when debian/changelog contains the non-native version number with revision like 0.16-1.

 $ cd /path/to/upstream-git
 $ git rm -rf debian
 $ git tag -s upstream/0.16
 $ git reset --hard HEAD^
 $ git deborig
 $ sbuild

Here, for source format 3.0 (quilt), removal of files under debian/ directory in the upstream tarball is non-essential operation to quiet false positive warning from lintian.

For -1 revision, this use of git-deborig(1) as above is how this debmake-doc package generates the upstream tarball.

For -2, -3, … revisions, you need to fetch and use the uploaded upstream tarball instead. For this, origtargz(1) may be handy.

The chroot for a clean package build environment can be created and managed using the tools described in Chapter 3, Tool Setups. [19]

Here is a quick summary of available package build commands. There are many ways to do the same thing.

  • dpkg-buildpackage = core of package building tool
  • debuild = dpkg-buildpackage + lintian (build under the sanitized environment variables)
  • schroot = core of the Debian chroot environment tool
  • sbuild = schroot + dpkg-buildpackage (build in the chroot)
  • gbp = manage the Debian source under git
  • gbp buildpackage = sbuild + dpkg-buildpackage + gbp (if configured with sbuild)

A clean unstable distribution chroot environment can be used as follows.

  • The chroot filesystem creation command for the unstable distribution

  • The master chroot filesystem path for the unstable distribution chroot filesystem

    • path: /srv/chroot/unstable-amd64-sbuild
  • The package build command for the unstable distribution chroot

    • sbuild
    • gbp buildpackage
  • The command to update the unstable chroot

    • sudo sbuild-update -udcar u
  • The command to login to the unstable chroot filesystem to modify it

    • sudo sbuild-shell u

Here, single "u" is predefined short alias for "unstable".

An arbitrary dist distribution environment can be used as follows.

  • The chroot filesystem creation command for the dist distribution

  • The master chroot filesystem path for the dist distribution chroot

    • path: /srv/chroot/dist-amd64-sbuild
  • The package build command for the dist distribution chroot

    • sbuild -d dist
    • gbp buildpackage --git-dist=dist
  • The command to update the dist chroot

    • sudo sbuild-update -udcar dist
  • The command to login to the master chroot (source:dist) of the dist distribution environment to modify it persistently

    • sudo sbuild-shell dist
[Tip] Tip

For building new experimental packages or for debugging buggy packages without using slow network access, this “sudo sbuild-shell dist” command can be used to pre-loaded some packages. Make sure to retain the backup of the original minimal chroot since changes are persistent and interfere with the normal test package building with the minimal chroot.

[Tip] Tip

If your old chroot filesystem is missing packages such as libeatmydata1, ccache, and lintian, you may want to install these with the “sudo sbuild-shell dist” command.

[Tip] Tip

When the orig.tar.gz file needs to be uploaded for a Debian revision other than 0 or 1 (e.g., for a security upload), add the -sa option to the end of dpkg-buildpackage, debuild, and sbuild commands. For the “gbp buildpackage” command, temporarily modify the builder setting of ~/.gbp.conf.

[Note] Note

The description in this section is too terse to be useful for most of the prospective maintainers. This is the intentional choice of the author. You are highly encouraged to search and read all the pertinent documents associated with the commands used.

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] 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.

If a package foo is properly packaged in the modern “3.0 (native)” or “3.0 (quilt)” formats, packaging a new upstream release is essentially moving the old debian/ directory to the new source. This can be done by running the “tar -xvzf /path/to/foo_oldversion.debian.tar.gz” command in the new extracted source. [20] Of course, you need to do some obvious chores.

There are several tools to handle this situation. After updating to the new upstream release with these tools, please make sure to describe concisely the changes in the new upstream release that fix reported bugs and close those bugs by adding “Closes: #bug_number” in the debian/changelog file.

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.

You should check DEP - Debian Enhancement Proposals and adopt ACCEPTED proposals.

See ProjectsDebSrc3.0 to check the support status of the new Debian source formats by the Debian tool chains.

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] 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] 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.

export LC_ALL

If upstream documents are encoded in old encoding schemes, converting them to UTF-8 is a good idea.

Use the iconv command in the libc-bin package to convert encodings of plain text files.

 $ iconv -f latin1 -t utf8 foo_in.txt > foo_out.txt

Use w3m(1) to convert from HTML files to UTF-8 plain text files. When you do this, make sure to execute it under UTF-8 locale.

 $ LC_ALL=C.UTF-8 w3m -o display_charset=UTF-8 \
        -cols 70 -dump -no-graph -T text/html \
        < foo_in.html > foo_out.txt

Run these scripts in the override_dh_* target of the debian/rules file.

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.

  • dpkg-buildpackage -sa
  • debuild -sa
  • *sbuild
  • For gbp buildpackage, edit the ~/.gbp.conf file.
[Tip] Tip

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

[Tip] 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.

  • dpkg-buildpackage -v1.2
  • debuild -v1.2
  • sbuild --debbuildopts -v1.2
  • For gbp buildpackage, edit the ~/.gbp.conf file.

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

Hints for the following can be found in the dpkg-source(1) manpage:

  • naming convention for multiple upstream source tarballs

    • packagename_version.orig.tar.gz
    • packagename_version.orig-componentname.tar.gz
  • recording the Debian changes to the upstream source package

    • dpkg-source --commit

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.

If the other distribution of interest is an RPM based distribution, see Repackage src.rpm.

Downloading and opening of the src.rpm file can be done with the rget command. (Place the rget script in your PATH.)

rget script. 

FCSRPM=$(basename $1)
mkdir ${FCSRPM}; cd ${FCSRPM}/
wget $1
rpm2cpio ${FCSRPM} | cpio -dium

Many upstream tarballs contain the SPEC file named as packagename.spec or used by the RPM system. This can be used as the baseline for the Debian package, too.

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.

  • core dump

    • man core
    • Update the “/etc/security/limits.conf” file to include the following:

      * soft core unlimited
    • ulimit -c unlimited” in ~/.bashrc
    • ulimit -a” to check
    • Press Ctrl-\ or “kill -ABRT PID” to make a core dump file
  • gdb - The GNU Debugger

    • info gdb
    • “Debugging with GDB” in /usr/share/doc/gdb-doc/html/gdb/index.html
  • strace - Trace system calls and signals

    • Use strace-graph script found in /usr/share/doc/strace/examples/ to make a nice tree view
    • man strace
  • ltrace - Trace library calls

    • man ltrace
  • sh -n” - Syntax check of a Shell script
  • sh -x” - Trace a Shell script
  • python -m py_compile” - Syntax check of a Python script
  • python -mtrace --trace” - Trace a Python script
  • perl -I ../libpath -c” - Syntax check of a Perl script
  • perl -d:Trace” - Trace a Perl script

    • Install the libterm-readline-gnu-perl package or its equivalent to add input line editing capability with history support.
  • lsof - List open files by processes

    • man lsof
[Tip] Tip

The script command records console outputs.

[Tip] Tip

The screen and tmux commands used with the ssh command offer secure and robust remote connection terminals.

[Tip] Tip

A Python- and Shell-like REPL (=READ + EVAL + PRINT + LOOP) environment for Perl is offered by the reply command from the libreply-perl (new) package and the command from the libdevel-repl-perl (old) package.

[Tip] Tip

The rlwrap and rlfe commands add input line editing capability with history support to any interactive commands. E.g. “rlwrap dash -i”' .

[19] The sbuild style chroot organization is deployed here. See . Be careful since many HOWTOs use different chroot setups.

[20] If a package foo is packaged in the old 1.0 format, this can be done by running the “zcat /path/to/foo_oldversion.diff.gz|patch -p1” command in the new extracted source, instead.

[21] You can split the big.diff file into many small incremental patch files using the splitdiff command.