Home Projects

While rebuilding packages from their sources usually falls under administration tasks, also the average GNU/Linux user can certainly profit from it. The main advantage of a libre operating system is the control every user has on the software. A typical situation when this is much relevant is the case of a bug in a software released with the operating system. Debian provides easy access to the source files and complete tools to rebuild a package from scratch. We first provide an executive summary, and then describe a typical example where a bug is fixed by applying a patch.

Excellent references are the Debian manual and the Debian Administrator's Handbook.

Contents

  1. Steps
  2. Example
    1. Change the sources
    2. Build and install

Steps

First, we summarize the steps to take to provide a fast reference:
  1. Download the source files apt-get source package
  2. Access the build directory cd package-*
  3. Change the version number dch --local 'new version label'
  4. Change the source files as needed
  5. Install the building dependencies # apt-get build-dep package
  6. Rebuild the package dpkg-buildpackage -us -uc
  7. Install the package dpkg -i ../package.deb

Example

We take a bug in the emacs24 Debian package as typical example. The well known program is part of the GNU operating system, and the source code is of course available. A bug report for the version 24.5+1-6+b2 as been filed (the problem concerns missing toolbar icons, but it is irrelevant here). Fortunately, the bug report also provides a patch that can easily be applied to emacs source files. Such patches are not guaranteed to solve completely the problem or to function properly in all cases, but it is easy to revert the modified packages.

Change the sources

Let's start by checking the locally installed version:
    $ apt-cache show emacs24
    Package: emacs24
    Source: emacs24 (24.5+1-6)
    Version: 24.5+1-6+b2
    [...]

Make sure that the source repositories (starting by deb-src) are present in /etc/apt/sources.list. Download the source files into a temporary directory:
    $ cd Sources/emacs/
    $ apt-get source emacs24
    $ ls
    emacs24-24.5+1                  emacs24_24.5+1-6.dsc
    emacs24_24.5+1-6.debian.tar.xz  emacs24_24.5+1.orig.tar.bz2
We can access the source directory:
    $ cd emacs24-24.5+1/
The next step is to change version. It is useful to give priority to the modified version over the one available on Debian repositories already at this point, choosing an appropriate label. Here we choose the label +fm (my initials): 
    $ dch --local '+fm'
The new version 24.5+1-6+fm1 to be created has priority over the bugged 24.5+1-6+b2, because b precedes f alphabetically. If the new label does not give priority to the version, it is always possible to pin a particular package in /etc/apt/preferences (see man 5 apt_preferences).

The dch command opens the favorite editor in which the changes can be documented: 
    emacs24 (24.5+1-6+fm1) UNRELEASED; urgency=medium
    * Fix missing toolbar icons
    -- Francesco Montanari <francesco.montanari@xxx.xxx>  Tue, 26 Jul 2016 12:13:03 +0300
    [...]

The following procedure to apply the patch should always be adapted to the given case, as it is specific of this particular example. We download the patch fix-missing-icons.patch from the bug report in the current folder. The patch can applied with:
    $ patch -p1 < fix-missing-icons.patch
The argument -p1 (of the generic -p[num] option, see man 1 patch) is necessary because the format of the patch is:
    diff --git a/lisp/term/x-win.el b/lisp/term/x-win.el
hence we want to skip the first directory (a/ or b/), which is present only for illustrative purposes.

This patch added the true patch to the debian/patches/ directory for documentation purposes. This true patch can be applied to make the changes to emacs source files. To apply the patch it is easier to copy it as a temporary file in the current folder:

    $ cp debian/patches/0020-Handle-deprecated-Gtk-stuff-for-version-3.10.patch ./tmp.patch
    $ patch -p1 < tmp.patch
Now that the changes are applied, remove the temporary unnecessary files (or move them somewhere else), so that they will not be identified as new source files:
    $ rm fix-missing-icons.patch tmp.patch

Build and install

All the building dependencies has to be installed
    # apt-get build-dep emacs24
Keep track of the newly installed packages to remove them later, e.g., by saving the package names on a temporary file (or find them with apt-cache showsrc emacs24).
Rebuild the package:
    $ dpkg-buildpackage -us -uc
The re-built packages are available in the folder from where the sources were downloaded:
    $ ls ../*.deb
    emacs24_24.5+1-6+fm1_amd64.deb
    emacs24-bin-common_24.5+1-6+fm1_amd64.deb
    emacs24-bin-common-dbgsym_24.5+1-6+fm1_amd64.deb
    emacs24-common_24.5+1-6+fm1_all.deb
    emacs24-dbg_24.5+1-6+fm1_amd64.deb
    emacs24-el_24.5+1-6+fm1_all.deb
    emacs24-lucid_24.5+1-6+fm1_amd64.deb
    emacs24-lucid-dbg_24.5+1-6+fm1_amd64.deb
    emacs24-nox_24.5+1-6+fm1_amd64.deb
    emacs24-nox-dbg_24.5+1-6+fm1_amd64.deb
Note the new version +fm1, which acquire priority over the version downloaded from the Debian repositories and can then be installed with dpkg. Due to dependencies problems, in this case it was necessary to fix the broken packages before installing the new ones:

    # dpkg -i ../*.deb
    # apt full-upgrade
    # dpkg -i ../*.deb
    # dpkg -i ../emacs24_24.5+1-6+fm1_amd64.deb

Check that the new version is correctly installed and has priority over the bugged one. If the bugged version has priority, it is possible to pin it in /etc/apt/preferences to avoid that it will be re-installed at the next system upgrade.
    $ apt-cache policy emacs24
    emacs24:
    Installed: 24.5+1-6+fm1
    Candidate: 24.5+1-6+fm1
    Version table:
    *** 24.5+1-6+fm1 100
    100 /var/lib/dpkg/status
    24.5+1-6+b2 900
    -10 http://ftp.fi.debian.org/debian unstable/main amd64 Packages
    900 http://ftp.fi.debian.org/debian stretch/main amd64 Packages
    24.4+1-5 -10
    -10 http://ftp.fi.debian.org/debian jessie/main amd64 Packages

The version from Unstable has priority -10 and won't be installed. The version 24.5+1-6+b2 from Testing (Stretch) repositories has priority 900. This policy was set in /etc/apt/preferences (see man 5 apt_preferences) . The newly installed version has priority 100 (the default one for installed packages), but it is preferred since the label 24.5+1-6+fm1 turns to be more recent than 24.5+1-6+b2. When the emacs24 package on Debian repositories will be updated with a more recent version, the package will also be updated.

Finally, the building dependencies (previously saved in a dedicated temporary file) can be removed.

Back to top