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.9. Upstream git repository
7.10. chroot
7.11. Debian リビジョンの更新
7.12. アップストリームソフトウェアの新版更新
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 変換
7.17. Upload orig.tar.gz
7.18. スキップされたアップロード
7.19. 上級パッケージング
7.20. Other distros
7.21. Debug

Here are some notable tips about Debian packaging.

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

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.

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

$ 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.
  • gbp pull: update the debian, upstream and pristine-tar branches safely from the remote repository.
  • git-pbuilder: build the Debian binary package from the git repository using the pbuilder package.

    • The cowbuilder package is used as its backend.
  • 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>'

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

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

[Caution] 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, …)

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)
  • pbuilder = core of the Debian chroot environment tool
  • pdebuild = pbuilder + dpkg-buildpackage (build in the chroot)
  • cowbuilder = speed up the pbuilder execution
  • git-pbuilder = the easy-to-use command line syntax for pdebuild (used by gbp buildpackge)
  • gbp = manage the Debian source under git
  • gbp buildpackge = pbuilder + dpkg-buildpackage + gbp

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

  • The chroot filesystem creation command for the sid distribution

    • pbuilder create
    • git-pbuilder create
  • The master chroot filesystem path for the sid distribution chroot filesystem

    • /var/cache/pbuilder/base.cow
  • The package build command for the sid distribution chroot

    • pdebuild
    • git-pbuilder
    • gbp buildpackage
  • The command to update the sid chroot

    • pbuilder --update
    • git-pbuilder update
  • The command to login to the sid chroot filesystem to modify it

    • git-pbuilder login --save-after-login

An arbitrary dist distribution environment can be used as follows.

  • The chroot filesystem creation command for the dist distribution

    • pbuilder create --distribution dist
    • DIST=dist git-pbuilder create
  • The master chroot filesystem path for the dist distribution chroot

    • path: /var/cache/pbuilder/base-dist.cow
  • The package build command for the dist distribution chroot

    • pdebuild -- --basepath=/var/cache/pbuilder/base-dist.cow
    • DIST=dist git-pbuilder
    • gbp buildpackage --git-dist=dist
  • The command to update the dist chroot

    • pbuilder update --basepath=/var/cache/pbuilder/base-dist.cow
    • DIST=dist git-pbuilder update
  • The command to login to the dist chroot to modify it

    • pbuilder --login --basepath=/var/cache/pbuilder/base-dist.cow --save-after-login
    • DIST=dist git-pbuilder login --save-after-login
[Tip] Tip

A custom environment with some pre-loaded packages needed for the new experimental packages, this “git-pbuilder login --save-after-login” command is quite handy.

[Tip] Tip

If your old chroot filesystem is missing packages such as libeatmydata1, ccache, and lintian, you may want to install these with the “git-pbuilder login --save-after-login” command.

[Tip] Tip

The chroot filesystem can be cloned simply by copying with the “cp -a base-dist.cow base-customdist.cow” command. The new chroot filesystem can be accessed as “gbp buildpackage --git-dist=customdist” and “DIST=customdist git-pbuilder …”.

[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, pdebuild, and git-pbuilder 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
  • pdebuild --debbuildopts -sa
  • git-pbuilder -sa
  • 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
  • pdebuild --debbuildopts -v1.2
  • git-pbuilder -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 git-pbuilder style organization is deployed here. See . Be careful since many HOWTOs use different organization.

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