Table of Contents
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 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
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-orig: import the new upstream tar to the git repository.
gbp buildpackage: build the Debian binary package from the git repository.
--git-builder='sbuild -A -s --source-only-changes -v -d unstable'
The gbp pq, git-dpm or quilt (or alias dquilt) commands are used to manage quilt patches.
Package history management with the git-buildpackage package is becoming the standard practice for most Debian maintainers.
See:
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 snapshot.debian.org 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 | |
---|---|
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 | |
---|---|
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 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:
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.
Format: 3.0 (quilt)
" package with its changes flowing mostly one way from the upstream Git repository to the Debian Git repository.
Format: 3.0 (quilt)
" package with its Debian Git repository which is kept usable also for people using gbp-buildpackage(1).
Format: 3.0 (native)
" package in the Debian Git repository.
The dgit(1) command can push the easy-to-trace change history to the https://browse.dgit.debian.org/ site and can upload Debian package to the Debian repository properly without using dput(1).
If you already use main
and upstream
branches in the Debian packaging repository (salsa.debian.org
), 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. [20]
Here is a quick summary of available package build commands. There are many ways to do the same thing.
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
The package build command for the unstable distribution chroot
The command to update the unstable chroot
The command to login to the unstable chroot filesystem to modify it
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
The package build command for the dist distribution chroot
The command to update the dist chroot
The command to login to the master chroot (source:dist) of the dist distribution environment to modify it persistently
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 | |
---|---|
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 | |
---|---|
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 | |
---|---|
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. |
Note | |
---|---|
When an essential package becomes a non-essential one (e.g., adduser), you need to remove it manually from the existing chroot environment for its use by piuparts. |
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. |
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. [21] 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.
You can automatically update to the new upstream source with the uupdate command from the devscripts package. It requires having the old Debian source package and the new upstream tarball.
$ wget https://example.org/foo/foo-newversion.tar.gz $ cd foo-oldversion $ uupdate -v newversion ../foo-newversion.tar.gz ... $ cd ../foo-newversion $ while dquilt push; do dquilt refresh; done $ dch
You can automatically update to the new upstream source with the uscan command from the devscripts package. It requires having the old Debian source package and the debian/watch file in it.
$ cd foo-oldversion $ uscan ... $ while dquilt push; do dquilt refresh; done $ dch
You can automatically update to the new upstream source with the “gbp import-orig --pristine-tar” command from the git-buildpackage package. It requires having the old Debian source in the git repository and the new upstream tarball.
$ ln -sf foo-newversion.tar.gz foo_newversion.orig.tar.gz $ cd foo-vcs $ git checkout master $ gbp pq import $ git checkout master $ gbp import-orig --pristine-tar ../foo_newversion.orig.tar.gz ... $ gbp pq rebase $ git checkout master $ gbp pq export $ gbp pq drop $ git add debian/patches $ dch -v <newversion> $ git commit -a -m "Refresh patches"
Tip | |
---|---|
If upstream uses a git repository, please also use the --upstream-vcs-tag option for the gbp import-orig command. |
You can automatically update to the new upstream source with the “gbp import-orig --pristine-tar --uscan” command from the git-buildpackage package. It requires having the old Debian source in the git repository and the debian/watch file in it.
$ cd foo-vcs $ git checkout master $ gbp pq import $ git checkout master $ gbp import-orig --pristine-tar --uscan ... $ gbp pq rebase $ git checkout master $ gbp pq export $ gbp pq drop $ git add debian/patches $ dch -v <newversion> $ git commit -a -m "Refresh patches"
Tip | |
---|---|
If upstream uses a git repository, please also use the --upstream-vcs-tag option for the gbp import-orig command. |
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 | |
---|---|
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
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.
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:
building several binary packages with several different build conditions
excluding some packages for the bootstrapping process (see also BuildProfileSpec)
Hints for the following can be found in the dpkg-source(1) manpage:
naming convention for multiple upstream source tarballs
recording the Debian changes to the upstream source package
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.
#!/bin/sh 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 packagename.spec.in 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.
Update the “/etc/security/limits.conf” file to include the following:
* soft core unlimited
gdb - The GNU Debugger
strace - Trace system calls and signals
ltrace - Trace library calls
“perl -d:Trace script.pl” - Trace a Perl script
lsof - List open files by processes
Tip | |
---|---|
The script command records console outputs. |
Tip | |
---|---|
The screen and tmux commands used with the ssh command offer secure and robust remote connection terminals. |
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 re.pl command from the libdevel-repl-perl (old) package. |
Tip | |
---|---|
The rlwrap and rlfe commands add input line editing capability with history support to any interactive commands. E.g. “rlwrap dash -i”' . |
[20] The sbuild style chroot organization is deployed here. See https://wiki.debian.org/sbuild . Be careful since many HOWTOs use different chroot setups.
[21] 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.
[22] You can split the big.diff file into many small incremental patch files using the splitdiff command.