Contents
What is Debian packaging
A Debian package is a collection of files that allow for applications or libraries to be distributed via the Debian package management system. The aim of packaging is to allow the automation of installing, upgrading, configuring, and removing computer programs for Debian in a consistent manner. A Debian specific binary package is a .deb file used to install some software while a source package is .dsc file that can provide us with all of the necessary files to compile or otherwise, build the desired piece of software. The act of producing source packages (.dsc) and binary packages (.deb) usually from an upstream release tarball (.tar.gz) either manually or by using tools such as debmake and dpkg-buildpackage is called Debian packaging.
The main aim of this tutorial is to provide a basic overview of the whole packaging process without missing any important points rather than a detailed tutorial. For a detailed guide see Debian New Maintainer's Guide instead.
Structure of a source package
A source package not only contains the upstream source distribution and options for the Debian package build system but also lists of run-time dependencies and conflicting packages, a machine-readable description of copyright and license information, initial configurations, etc.
A source package in Debian consists of the following:
The upstream (original software source) tarball .tar.gz ending.
A tarball (usually with .debian.tar.gz or .debian.tar.xz ending), with any changes made to upstream source, plus all the files created for the Debian package.
A description file with .dsc ending which has checksums (md5, sha etc) for the above 2 files.
Structure of a binary package
A binary package (.deb) in Debian consists of the following:
debian-binary: version of the deb file format.
control.tar.gz: metadata about the package.
data.tar.gz: data files of the package.
Creating a basic source package
- Download the upstream source as tarball.
Rename it to <source_package>_<upstream_version>.orig.tar.gz (eg. node-pretty-hrtime_1.0.3.orig.tar.gz).
- Untar the tarball.
Rename the directory to <source_package>-<upstream_version> (eg. node-pretty-hrtime-1.0.3).
Switch to the above directory (eg. cd node-pretty-hrtime-1.0.3) and run debmake. This will create debian directory with all necessary files in it.
debmake will give us a generic debian folder if we give it any kind of tarball. But specialized tools like npm2deb (for node packages), gem2deb (for ruby packages), dh-make-golang, dh-make-perl, dh-make-php (for go, perl and php respectively), etc. are preferred over debmake if they could be used.
run this following commands and this should run fine (you can choose one of debmake or dh_make)
Option 1: debmake
apt install debmake cd <replace with unpacked directory> debmake
OR
Option 2: dh_make
apt install dh-make cd <replace with unpacked directory> dh_make
- The debian directory must have the following files:
changelog: history of the Debian package, can be edited manually or using dch tool. After installation this will go to /usr/share/doc/package/changelog.Debian.gz.
control: meta-data about the package such as package name, section, description, dependencies, maintainer, etc.
copyright: copyright information for the package.
rules: specifies how to build the package. We could write shell code directly or use any packaging helper like debhelper for this purpose.
- Create Debian source package using the following command:
dpkg-source -b .
The above command will generate a tarball of the debian folder (<source_package>_<version>.debian.tar.xz and <source_package>_<version>.dsc file in the parent directory).
- Build the binary package using the following command:
dpkg-buildpackage
The above command will generate one or more .deb file(s) (based on the configuration in the control file), .buildinfo and .changes files in the parent directory.
Import package to git using git-buildpackage. This is useful to track all changes we make to the package.
cd .. gbp import-dsc --pristine-tar <source_package>_<version>.dsc
The above command will create a new directory (repo) called <source_package> which is git tracked. This repo will have 3 branches as follows:
master: contains upstream source along with the debian directory.
upstream: contains the original source as provided by the upstream.
pristine-tar: contains essential data to recreate the exact upstream tarball used during import (line-endings for text files in different architectures may create tarballs with different checksum).
Switch to the newly created repo (cd <source_package>). You may run git branch and git tag commands to see the default branches and tag.
- Delete the debian tag by running the following command (we can add the tag later after making all necessary changes):
git tag -d debian/<version>
- Make package lintian clean.
Run lintian command and make sure to fix all the errors and warnings (lines starting with E: or W:) shown. Every time we make a change to any file inside debian directory, run dpkg-buildpackage and lintian commands to make sure the warning(s)/error(s) are actually fixed.
- Changelog file can be edited using the following command which will warn us if we make mistakes in formatting:
dch -e
Update debian/copyright with any missing information. We can use the package libconfig-model-dpkg-perl for this:
cme update dpkg-copyright
Commit related changes one by one. It should be noted that all the packaging work should be made by modifying files in the debian directory. Changes to the upstream source (for eg. bug fixes), if there are any, should be made as patch files in this folder (this can be done with the help of tools like quilt, dpatch, etc). Commit only the files that are edited or added (verify only the required files are getting committed). Run debclean or clean before running git commit to ensure files generated by dpkg-buildpackage are not committed. If you are using quilt, run quilt pop -a before commit.
- Run tests if available.
File ITP (Intend To Package).
Clean build with sbuild. Make sure that the package builds in a clean minimal chroot.
AptCacherNg can be set up to save bandwidth and make builds faster.
Push the repo to salsa.debian.org.
Request sponsorship. See The sponsoring process for more details.
See also
This tutorial is based on the following guides: