Wiki

• FrontPage
• RecentChanges
• FindPage
• HelpContents
• SimplePackagingTutorial

Introduces the concept of Debian packages and describes tools to create them. For more tutorials, see Packaging.

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:

1. The upstream (original software source) tarball .tar.gz ending.

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

3. A description file with .dsc ending which has checksums (md5, sha etc) for the above 2 files.

Creating a basic source package

We will take pretty-ms node module as an example.

• Download the upstream source as tarball. Usually from the releases/tags pages of github.com or download page from the software's homepage.

• Rename it to <source_package>_<upstream_version>.orig.tar.gz (eg. node-pretty-ms_9.2.0.orig.tar.gz). This is the file name format expected by debian tools building the .deb file. We prefix node- to all node modules to avoid conflicts in the package name space (there can be a ruby-pretty-ms or rust-pretty-ms as well) and also to easily search / filter node modules.

• Extract the tarball tar -xvf node-pretty-ms_9.2.0.orig.tar.gz.

• Rename the directory to <source_package>-<upstream_version> (eg. node-pretty-ms-9.2.0).

• Switch to the above directory (eg. cd node-pretty-ms-9.2.0) 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

apt install debmake
cd <replace with unpacked directory>
debmake

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

• Build the binary package using the following command:

    debuild -us -uc

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

• Now install the generated .deb file with

   sudo apt install  ../node-pretty-ms_9.2.0-1_all.deb

• Optional: You can also test / verify that nodejs is able to find the module installed via apt with

   dpkg -L node-pretty-ms | grep index.js
   /usr/share/nodejs/pretty-ms/index.js

and

   nodejs -e "require('pretty-ms')"

Make sure index.js is installed in /usr/share/nodejs/pretty-ms and nodejs require command should not give an error.

If you get an error like,

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'parse-ms' imported from <packaging  path>/node-pretty-ms-9.2.0/index.js

Then you may need to make sure the dependency is available in node_modules directory (requirement of ES module imports).

   ln -s /usr/share/nodejs/parse-ms node_modules

Note: This testing / verification step can be different for different packages.

• Import package to git using git-buildpackage. This is useful to track all changes we make to the package.

   cd ..
   sudo apt install git-buildpackage
   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.

Next Steps

• 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:

• Packaging

• Packaging Intro

• Debian Packaging Tutorial

• Npm2Deb

• Basic Guide for Debian Packaging

CategoryPackaging