Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This guide was made using the following previous documents as its reference:

  • “Making a Debian Package (AKA the Debmake Manual)”, copyright © 1997 Jaldhar Vyas.

  • “The New-Maintainer’s Debian Packaging Howto”, copyright © 1997 Will Lowe.

  • “Debian New Maintainers’ Guide”, copyright © 1998-2002 Josip Rodin, 2005-2014 Osamu Aoki, 2010 Craig Small, and 2010 Raphaël Hertzog.

Newer versions of this guide should always be available in the debmake-doc package.

Preface

If you are a somewhat experienced Debian user
[You do need to know a little about Unix programming but you certainly don’t need to be a wizard. You can learn about the basic handling of a Debian system from the Debian Reference. It contains some pointers to learn about Unix programming, too.]
, you may have encountered following situations:

  • You wish to install a certain software package not yet found in the Debian archive.

  • You wish to update a Debian package with the newer upstream release.

  • You wish to fix bugs of a Debian package with some patches.

If you wanted to create a Debian package to fulfill these wishes and to share your work with the community, you are the target audience of this guide as a prospective Debian maintainer.
[If you are not interested in sharing the Debian package, you can certainly work around your local situation by compiling and installing the fixed upstream source package into /usr/local/.]
Welcome to the Debian community.

Debian has many social and technical rules and conventions to follow since it is a large volunteer organization with history. Debian also has developed huge array of packaging tools and archive maintenance tools to build consistent set of binary packages addressing many technical objectives:

  • clean build under clearly specified package dependencies and patches

  • packages build across many architectures

  • optimal splits into multiple binary packages

  • smooth library transitions

  • security enhancement using specific compiler flags

  • multiarch support

These make it somewhat overwhelming for many new prospective Debian maintainers to get involved with Debian. This guide tries to provide entry points for them to get started. It describes as follows:

  • What you should know before getting involved with Debian as a prospective maintainer.

  • What it looks like to make a simple Debian package.

  • What kind of rules exist for making the Debian package.

  • Tips for making the Debian package.

  • Examples of making Debian packages for several typical scenarios.

The author felt limitations of updating the original “New Maintainers' Guide” with the dh-make package and decided to create an alternative tool and its matching document to address modern requirements. The result is the debmake (version: 4.2.1) package and this updated “Guide for Debian Maintainers” in the debmake-doc (version: 1.0-1) package.

Many chores and tips have been integrated into the debmake command making this guide simple. This guide also offers many packaging examples.

Caution
It takes many hours to properly create and maintain Debian packages. The Debian maintainer must be both technically competent and diligent to take up this challenge.

Some important topics are explained in detail. Some of them may look irrelevant to you. Please be patient. Some corner cases are skipped. Some topics are only covered by the external pointers. These are intentional choices to keep this guide simple and maintainable.

Overview

The Debian packaging of the package-1.0.tar.gz, containing a simple C source following the GNU Coding Standards and FHS, can be done with the debmake command as follows.

 $ tar -xvzf package-1.0.tar.gz
 $ cd package-1.0
 $ debmake
   ... Make manual adjustments of generated configuration files
 $ debuild

If manual adjustments of generated configuration files are skipped, the generated binary package lacks meaningful package description but still functions well under the dpkg command to be used for your local deployment.

Caution
The debmake command only provides good template files. These template files must be manually adjusted to their perfection to comply with the strict quality requirements of the Debian archive, if the generated package is intended for the general consumption.

If you are new to the Debian packaging, do not worry about the details and just get the big picture instead.

If you have been exposed to the Debian packaging, this looks very much like the dh_make command. This is because the debmake command is intended to replace functions offered historically by the dh_make command.
[The deb-make command was popular before the dh_make command. The current debmake package starts its version from 4.0 to avoid version overlaps with obsolete debmake package which provided the deb-make command.]

The debmake command is designed with following features:

  • modern packaging style

    • debian/copyright: DEP-5 complient

    • debian/control: substvar support, multiarch support, multi binary packages, …

    • debian/rules: dh syntax, compiler hardening options, …

  • flexibility

  • sane default actions

    • execute non-stop with clean results

    • generate the multiarch package, unless -m option is explicitly specified.

    • generate the non-native Debian package with the “3.0 (quilt)” format, unless -n option is explicitly specified.

  • extra utility

    • verification of the debian/copyright file against the current source ([koption])

The debmake command delegates most of the heavy lifting to its back-end packages: debhelper, dpkg-dev, devscripts, pbuilder, etc.

Tip
Make sure to protect the arguments of the -b, -f, -l, and -w options from the shell interference by quoting them properly.
Tip
The non-native Debian package is the normal Debian package.
Note
The generation of the debian/copyright file, and the outputs from the -c ([coption]) and -k ([koption]) options involve heuristic operations on the copyright and license information. They may produce some erroneous results.

Prerequisites

Here are the prerequisites which you need to understand before you to get involved with Debian.

People around Debian

There are several types of people interacting around Debian with different roles:

  • upstream author: the person who made the original program.

  • upstream maintainer: the person who currently maintains the program.

  • maintainer: the person making the Debian package of the program.

  • sponsor: a person who helps maintainers to upload packages to the official Debian package archive (after checking their contents).

  • mentor: a person who helps novice maintainers with packaging etc.

  • Debian Developer (DD): a member of the Debian project with full upload rights to the official Debian package archive.

  • Debian Maintainer (DM): a person with limited upload rights to the official Debian package archive.

Please note that you can’t become an official Debian Developer (DD) overnight, because it takes more than technical skill. Please do not be discouraged by this. If it is useful to others, you can still upload your package either as a maintainer through a sponsor or as a Debian Maintainer.

Please note that you do not need to create any new packages to become an official Debian Developer. Contributing to the existing packages can provide a path to becoming an official Debian Developer too. There are many packages waiting for good maintainers (see [approaches]).

How to contribute

Please refer to the following to learn how to contribute to Debian:

Social dynamics of Debian

Please understand Debian’s social dynamics to prepare yourself for interactions with Debian:

  • We all are volunteers.

    • You can’t impose on others what to do.

    • You should be motivated to do things by yourself.

  • Friendly cooperation is the driving force.

    • Your contribution should not over-strain others.

    • Your contribution is valuable only when others appreciate it.

  • Debian is not your school where you get automatic attention of teachers.

    • You should be able to learn many things by yourself.

    • Attention from other volunteers is a very scarce resource.

  • Debian is constantly improving.

    • You are expected to make high quality packages.

    • You should adapt yourself to the change.

Since we focus only on the technical aspects of the packaging in the rest of this guide, please refer to the following to understand the social dynamics of Debian:

Technical reminders

Here are some technical reminders to accommodate other maintainers to work on your package easily and effectively to maximize the output of Debian as a whole.

  • Make your package easy to debug.

    • Keep your package simple.

    • Don’t over-engineer your package.

  • Keep your package well-documented.

    • Use readable code style.

    • Make comments in code.

    • Format code consistently.

    • Maintain the git repository
      [The overwhelming number of Debian maintainers use git over other VCS systems such as hg, bzr, etc.]
      of the package.

Note
Debugging of software tends to consume more time than writing the initial working software.

Debian documentation

Please make yourself ready to read the pertinent part of the official Debian documentation together with this guide as needed to generate perfect Debian packages:

If this guide contradicts with the official Debian documentation, they are correct. Please file a bug report on the debmake-doc package using the reportbug command.

Here are alternative tutorial documents which you may read along with this guide:

Tip
When reading these tutorials, you should consider to use the debmake command in place of the dh_make command for better template files.

Help resources

Before you decide to ask your question in some public place, please do your parts of efforts, i.e., read the fine documentation:

Your desired information can be found effectively by using the well-formend search string such as “keyword site:lists.debian.org” to limit the search domain of the web search engine.

Making a small test package is a good way to learn details of the packaging. Inspecting existing well maintained packages is the best way to learn how other people make packages.

If you still have questions about the packaging, you can ask them interactively:

The more experienced Debian developers will gladly help you, if you ask properly after making your required efforts.

Caution
Debian development is a moving target. Some information found on the web may be outdated, incorrect, and not-applicable. Please use them carefully.

Archive situation

Please realize the situation of the Debian archive.

  • Debian already has packages for most kinds of programs.

  • The number of packages already in the Debian archive is several tens of times greater than that of active maintainers.

  • Unfortunately, some packages lack appropriate level of attention by the maintainer.

Thus, contributions to packages already in the archive are far more appreciated (and more likely to receive sponsorship for the uploading) by other maintainers.

Tip
The wnpp-alert command from the devscripts package can check for installed packages up for adoption or orphaned.

Contribution approaches

Here is a pseudo-Python code for your contribution approaches to Debian with a program:

if exist_in_debian(program):
  if is_team_maintained(program):
    join_team(program)
  if is_orphaned(program) # maintainer: Debian QA Group
    adopt_it(program)
  elif is_RFA(program) # Request for Adoption
    adopt_it(program)
  else:
    if need_help(program):
      contact_maintainer(program)
      triaging_bugs(program)
      preparing_QA_or_NMU_uploads(program)
    else:
      leave_it(program)
else: # new packages
  if not is_good_program(program):
    give_up_packaging(program)
  elif not is_distributable(program):
    give_up_packaging(program)
  else: # worth packaging
    if is_ITPed_by_others(program):
      if need_help(program):
        contact_ITPer_for_collaboration(program)
      else:
        leave_it_to_ITPer(program)
    else: # really new
      if is_applicable_team(program):
        join_team(program)
      if is_DFSG(program) and is_DFSG(dependency(program)):
        file_ITP(program, area="main") # This is Debian
      elif is_DFSG(program):
        file_ITP(program, area="contrib") # This is not Debian
      else: # non-DFSG
        file_ITP(program, area="non-free") # This is not Debian
      package_it_and_close_ITP(program)

Here:

  • For exist_in_debian(), and is_team_maintained(); check:

  • For is_orphaned(), is_RFA(), and is_ITPed_by_others(); check:

  • For is_good_program(), check:

    • The program should be useful.

    • The program should not introduce security and maintenance concerns to the Debian system.

    • The program should be well documented and its code needs to be understandable (i.e. not obfuscated).

    • The program’s authors agree with the packaging and are amicable to Debian.
      [This is not the absolute requirement. The hostile upstream may become major resource drains for us all. The friendly upstream can be consulted to solve any problems with the program.]

  • For is_it_DFSG(), and is_its_dependency_DFSG(); check:

  • For is_it_distributable(), check:

    • The software must have a license and it should allow its distribution.

You either need to file an ITP or adopt a package to start working on it. See the “Debian Developer’s Reference”:

Novice maintainer

The novice maintainer should avoid packaging programs with the high security exposure:

  • setuid or setgid program

  • daemon program

  • program installed in the /sbin/ or /usr/sbin/ directories

When you gain more experience in packaging, you’ll be able to package such programs.

Tool Setups

The build-essential package must be installed in the build environment.

The devscripts package should be installed on the maintainer environment.

Although this is not necessary the absolute requirement, it is a good idea to install and setup all of the popular set of packages mentioned in this chapter on the maintainer environment. This enables us to share the common baseline working environment.

Please install the tools mentioned in the Overview of Debian Maintainer Tools of the “Debian Developer’s Reference”, as needed, too.

Tip
For the cut-and-paste from the code listing part, use this document in the HTML format.
[The cut-and-paste from the PDF format does not function well for U+0022 QUOTATION MARK (ASCII double quote), U+0027 APOSTROPHE (ASCII single quote), and U+0060 GRAVE ACCENT (ASCII back tick) since they are converted by the LaTeX to U+201D RIGHT DOUBLE QUOTATION MARK, U+2019 RIGHT SINGLE QUOTATION MARK, and U+2018 LEFT SINGLE QUOTATION MARK.]
Caution
Tool setups presented here are only meant as an example and may not be up-to-date with the latest packages on the system. Debian development is a moving target. Please make sure to read the pertinent documentation and update the configuration as needed.

Email address

Various Debian maintenance tools recognize your email address and name to use by the shell environment variables $DEBEMAIL and $DEBFULLNAME.

Let’s setup these packages by adding the following lines to ~/.bashrc
[This assumes you are using Bash as your login shell. If you use some other login shell such as Z shell, use their corresponding configuration files instead of ~/.bashrc.]
.

Add to the ~/.bashrc file
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME

mc

The mc command offers very easy ways to manage files. It can open the binary deb file to check its content by pressing the Enter key over the binary deb file. It uses the dpkg-deb command as its back-end. Let’s setup it to support easy chdir as follows.

Add to the ~/.bashrc file
# mc related
export HISTCONTROL=ignoreboth
. /usr/lib/mc/mc.sh

git

Nowadays, the git command is the essential tool to manage the source tree with history.

The global user configuration for the git command such as your name and email address can be set in ~/.gitconfig as follows.

$ git config --global user.name "Name Surname"
$ git config --global user.email yourname@example.com

If you are too accustomed to the CVS or Subversion commands, you may wish to set several command aliases as follows.

$ git config --global alias.ci "commit -a"
$ git config --global alias.co checkout

You can check your global configuration as follows.

$ git config --global --list
Tip
It is essential to use the gitk command to work effectively with the history of the git repository.

quilt

The quilt command offers a basic method for recording modifications. For the Debian packaging, it should be customized to record modifications in the debian/patches/ directory instead of its default patches/ directory.

In order to avoid changing the behavior of the quilt command itself, let’s create an alias dquilt for the Debian packaging by adding the following lines to the ~/.bashrc file. The second line provides the same shell completion feature of the quilt command to the dquilt command.

Add to the ~/.bashrc file
alias dquilt="quilt --quiltrc=${HOME}/.quiltrc-dpkg"
complete -F _quilt_completion $_quilt_complete_opt dquilt

Then let’s create ~/.quiltrc-dpkg as follows.

d=.
while [ ! -d $d/debian -a `readlink -e $d` != / ];
    do d=$d/..; done
if [ -d $d/debian ] && [ -z $QUILT_PATCHES ]; then
    # if in Debian packaging tree with unset $QUILT_PATCHES
    QUILT_PATCHES="debian/patches"
    QUILT_PATCH_OPTS="--reject-format=unified"
    QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
    QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
    QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:" + \
            "diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"
    if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
fi

See quilt(1) and How To Survive With Many Patches or Introduction to Quilt on how to use the quilt command.

See [alt-patch] for example usages.

devscripts

The debsign command, included in the devscripts package, is used to sign the Debian package with your private GPG key.

The debuild command, included in the devscripts package, builds the binary package and check them with the lintian command. It is useful to have verbose outputs from the lintian command.

You can setup these by the ~/.devscripts as follows.

DEBUILD_DPKG_BUILDPACKAGE_OPTS="-i -us -uc"
DEBUILD_LINTIAN_OPTS="-i -I --show-overrides"
DEBSIGN_KEYID="Your_GPG_keyID"

Currently, RSA key with 4096 bits is good idea. See Creating a new GPG key.

pbuilder

The pbuilder package provides the clean room (chroot) build environment.
[The sbuild package provides an alternative chroot platform.]

Let’s customize it with several helper packages.

  • The cowbuilder package to boost the chroot creation speed.

  • The lintian package to find bugs in the package.

  • The bash, mc, and vim packages in case build fails.

  • The ccache package to boost the gcc speed. (optional)

  • The libeatmydata1 package to boost the dpkg speed. (optional)

  • The parallel make to boost the build speed. (optional)

Warning
The optional customization may cause negative effects. In case of doubts, disable them.

Let’s create ~/.pbuilderrc as follows (all optional features are disabled).

AUTO_DEBSIGN="${AUTO_DEBSIGN:-no}"
PDEBUILD_PBUILDER=cowbuilder
HOOKDIR="/var/cache/pbuilder/hooks"
MIRRORSITE="http://httpredir.debian.org/debian/"
#APTCACHE=/var/cache/pbuilder/aptcache
APTCACHE=/var/cache/apt/archives
#BUILDRESULT=/var/cache/pbuilder/result/
BUILDRESULT=../
EXTRAPACKAGES="ccache lintian libeatmydata1"

# enable to use libeatmydata1 for pbuilder
#export LD_PRELOAD=${LD_PRELOAD+$LD_PRELOAD:}libeatmydata.so

# enable ccache for pbuilder
#export PATH="/usr/lib/ccache${PATH+:$PATH}"
#export CCACHE_DIR="/var/cache/pbuilder/ccache"
#BINDMOUNTS="${CCACHE_DIR}"

# parallel make
#DEBBUILDOPTS=-j8
Note
A symlink from /root/.pbuilderrc to /home/<user>/.pbuilderrc may help for the consistent experience.
Note
Due to Bug #606542, you may need to manually install packages listed in EXTRAPACKAGES into the chroot. See [chroot].
Note
Install libeatmydata1 (>=82-2) both inside and outside of the chroot or disable to use libeatmydata1. This may cause the race condition with some build systems.
Note
The parallel make may fail for some existing packages and may make the build log difficult to read.

Let’s create a hook scripts as follows.

/var/cache/pbuilder/hooks/A10ccache

#!/bin/sh
set -e
# increase the ccache caching size
ccache -M 4G
# output the current statistics
ccache -s

/var/cache/pbuilder/hooks/B90lintian

#!/bin/sh
set -e
apt-get -y --force-yes install lintian
echo "+++ lintian output +++"
su -c "lintian -i -I --show-overrides /tmp/buildd/*.changes; :" -l pbuilder
echo "+++ end of lintian output +++"

/var/cache/pbuilder/hooks/C10shell

#!/bin/sh
set -e
apt-get -y --force-yes install vim bash mc
# invoke shell if build fails
cd /tmp/buildd/*/debian/..
/bin/bash < /dev/tty > /dev/tty 2> /dev/tty
Note
All these scripts need to be set world executable: “-rwxr-xr-x 1 root root”.
Note
The ccache cache directory /var/cache/pbuilder/ccache needs to be set world writable: “-rwxrwxrwx 1 root root” for the pbuilder command. You should be aware of associated security concerns.

git-buildpackage

You may wish to set several global configurations in ~/.gbp.conf

# Configuration file for "gbp <command>"

[DEFAULT]
# the default build command:
builder = git-pbuilder -i -I -us -uc
# use pristine-tar:
pristine-tar = True
# Use color when on a terminal, alternatives: on/true, off/false or auto
color = auto
Tip
The gbp command is the alias of the git-buildpackage command.

HTTP proxy

You should set up a local HTTP caching proxy to save the bandwidth for the Debian package repository access. There are several choices:

  • Simple HTTP caching proxy using the squid package.

  • Specialized HTTP caching proxy using the apt-cacher-ng package.

Private Debian repository

You can set up a private Debian package repository with the reprepro package.

Simple Example

There is an old Latin saying: “Longum iter est per praecepta, breve et efficax per exempla” (“It’s a long way by the rules, but short and efficient with examples”).

Here is an example of creating a simple Debian package from a simple C source using the Makefile as its build system.

Let’s assume this upstream tarball to be debhello-0.0.tar.gz.

This type of source is meant to be installed as a non-system file as:

 $ tar -xzmf debhello-0.0.tar.gz
 $ cd debhello-0.0
 $ make
 $ make install

Debian packaging requires to change this “make install” process to install files to the target system image location instead of the normal location under /usr/local.

Note
Examples of creating Debian package from other complicated build systems are described in [more].

Big picture

The big picture for building a single non-native Debian package from the upstream tarball debhello-0.0.tar.gz can be summarized as:

  • The maintainer obtains the upstream tarball and untar its contents.

  • The debmake command debianize the upstream source tree by adding template files to it.

  • The maintainer customizes template files.

  • The debuild command builds the binary package from the debianized source tree.

Big picture of package building
 $ tar -xzmf debhello-0.0.tar.gz
 $ cd debhello-0.0
 $ debmake
   ... manual customization
 $ debuild
Tip
The debuild command in this and following examples may be substituted by the equivalent commands such as the pdebuild command.

What is debmake?

The debmake command is the helper script for the Debian packaging.

  • It always sets most of the obvious option states and values to reasonable defaults.

  • It generates the upstream tarball and its required symlink if they are missing.

  • It doesn’t overwrite the existing configuration files in the debian/ directory.

  • It supports the multiarch package.

  • It creates good template files such as the debian/copyright file complaint to DEP-5.

These features make Debian packaging with debmake simple and modern.

What is debuild?

Here is a summary of commands similar to the debuild command.

  • The debian/rules file defines how the Debian package is built.

  • The dpkg-buildpackage is the official command to invoke debian/rules to build the Debian package. Notably, it executes itself with the clean target before the binary one for the normal package build.

  • The debuild command is a wrapper script of dpkg-buidpackage to build a package under the proper environment variables.

  • The pdebuild command is a wrapper script to build a package under the proper chroot environment with the proper environment variables.

  • The git-pbuilder command is another wrapper script to build a package under the proper chroot environment with the proper environment variables. This provides an easier command line UI to switch among different build environments.

Step-by-step: upstream

Let’s get the source.

Download debhello-0.0.tar.gz
 $ wget http://www.example.org/download/debhello-0.0.tar.gz
 ...
 $ tar -xzmf debhello-0.0.tar.gz
 $ tree
.
├── debhello-0.0
│   ├── LICENSE
│   ├── Makefile
│   └── src
│       └── hello.c
└── debhello-0.0.tar.gz

2 directories, 4 files

Here, the C source hello.c is a very simple one.

hello.c
 $ cat debhello-0.0/src/hello.c
#include <stdio.h>
int
main()
{
        printf("Hello, world!\n");
        return 0;
}

Here, the Makefile supports GNU Coding Standards and FHS. Notably:

  • build binaries honoring $(CPPFLAGS), $(CFLAGS), $(LDFLAGS), etc.

  • install files with the $(DESTDIR) to the target system image

  • install files with the $(prefix) which can be overridden to be /usr

Makefile
 $ cat debhello-0.0/Makefile
prefix = /usr/local

all: src/hello

src/hello: src/hello.c
        @echo "CFLAGS=$(CFLAGS)" | \
                fold -s -w 70 | \
                sed -e 's/^/# /'
        $(CC) $(CPPFLAGS) $(CFLAGS) $(LDCFLAGS) -o $@ $^

install: src/hello
        install -D src/hello \
                $(DESTDIR)$(prefix)/bin/hello

clean:
        -rm -f src/hello

distclean: clean

uninstall:
        -rm -f $(DESTDIR)$(prefix)/bin/hello

.PHONY: all install clean distclean uninstall
Note
The echo of the $(CFLAGS) is used to verify the proper setting of the build flag in the following example.

Step-by-step: debmake

Tip
If the debmake command is invoked with the -T option, more verbose comments are generated for the template files.

The output from the debmake command is very verbose and explains what it does as follows.

 $ cd debhello-0.0
 $ debmake
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="0.0", rev="1"
I: *** start packaging in "debhello-0.0". ***
I: provide debhello_0.0.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-0.0.tar.gz debhello_0.0.orig.tar.gz
I: pwd = "/path/to/debhello-0.0"
I: parse binary package settings:
I: binary package=debhello Type=bin / Arch=any M-A=foreign
I: analyze the source tree
I: build_type = make
I: scan source for copyright+license text and file extensions
I: 100 %, ext = c
I: check_all_licenses
I: ..
I: check_all_licenses completed for 2 files.
I: bunch_all_licenses
I: format_all_licenses
I: make debian/* template files
I: single binary package
I: debmake -x "1" ...
I: creating => debian/control
I: creating => debian/copyright
I: substituting => /usr/share/debmake/extra0/changelog
I: creating => debian/changelog
I: substituting => /usr/share/debmake/extra0/rules
I: creating => debian/rules
I: substituting => /usr/share/debmake/extra1/README.Debian
I: creating => debian/README.Debian
I: substituting => /usr/share/debmake/extra1/compat
I: creating => debian/compat
I: substituting => /usr/share/debmake/extra1/watch
I: creating => debian/watch
I: substituting => /usr/share/debmake/extra1source/format
I: creating => debian/source/format
I: substituting => /usr/share/debmake/extra1source/local-options
I: creating => debian/source/local-options
I: substituting => /usr/share/debmake/extra1patches/series
I: creating => debian/patches/series
I: run "debmake -x2" to get more template files
I: $ wrap-and-sort

The debmake command generates all these template files based on the command line option. Since no options are specified, the debmake command choses reasonable default values for you:

  • The source package name: debhello

  • The upstream version: 0.0

  • The binary package name: debhello

  • The Debian revision: 1

  • The package type: bin (the ELF binary executable package)

  • The -x option: -x1 (default for the single binary package)

Let’s inspect generated template files.

The source tree after the basic debmake execution.
 $ cd ..
 $ tree
.
├── debhello-0.0
│   ├── LICENSE
│   ├── Makefile
│   ├── debian
│   │   ├── README.Debian
│   │   ├── changelog
│   │   ├── compat
│   │   ├── control
│   │   ├── copyright
│   │   ├── patches
│   │   │   └── series
│   │   ├── rules
│   │   ├── source
│   │   │   ├── format
│   │   │   └── local-options
│   │   └── watch
│   └── src
│       └── hello.c
├── debhello-0.0.tar.gz
└── debhello_0.0.orig.tar.gz -> debhello-0.0.tar.gz

5 directories, 15 files

The debian/rules file is the build script provided by the package maintainer. Here is its template file generated by the debmake command.

debian/rules (template file):
 $ cat debhello-0.0/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

#override_dh_auto_install:
#       dh_auto_install -- prefix=/usr

#override_dh_install:
#       dh_install --list-missing -X.pyc -X.pyo

This is essentially the standard debian/rules file with the dh command. (There are some commented out contents for you to customize it.)

The debian/control file provides the main meta data for the Debian package. Here is its template file generated by the debmake command.

debian/control (template file):
 $ cat debhello-0.0/debian/control
Source: debhello
Section: unknown
Priority: extra
Maintainer: "Firstname Lastname" <email.address@example.org>
Build-Depends: debhelper (>=9)
Standards-Version: 3.9.6
Homepage: <insert the upstream URL, if relevant>

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: auto-generated package by debmake
 This Debian binary package was auto-generated by the
 debmake(1) command provided by the debmake package.

Since this is the ELF binary executable package, the debmake command sets “Architecture: any” and “Multi-Arch: foreign”. Also, it sets required substvar parameters as “Depends: ${shlibs:Depends}, ${misc:Depends}”. These are explained in [basics].

Note
Please note this debian/control file uses the RFC-822 style as documented in 5.2 Source package control files — debian/control of the “Debian Policy Manual”. The use of the empty line and the leading space are significant.

The debian/copyright file provides the copyright summary data of the Debian package. Here is its template file generated by the debmake command.

debian/copyright (template file):
 $ cat debhello-0.0/debian/copyright
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: debhello
Source: <url://example.com>

Files:     Makefile
           src/hello.c
Copyright: __NO_COPYRIGHT_NOR_LICENSE__
License:   __UNKNOWN__

#----------------------------------------------------------------------------...
# Files marked as NO_LICENSE_TEXT_FOUND may be covered by the following
# license/copyright files.

#----------------------------------------------------------------------------...
# License file: LICENSE
 License:
 .
 All files in this archive are licensed under the MIT License as below.
 .
 Copyright 2015 Osamu Aoki <osamu@debian.org>
 .
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 and/or sell copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following conditions:
 .
 The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
 .
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Step-by-step: maintainer

Some manual modification is required to make the proper Debian package as a maintainer.

In order to install files as a part of the system files, the $(prefix) value of /usr/local in the Makefile should be overridden to be /usr. This can be accommodated by the following the debian/rules file with the override_dh_auto_install target setting “prefix=/usr”.

debian/rules (maintainer version):
 $ vim debhello-0.0/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-0.0/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

override_dh_auto_install:
        dh_auto_install -- prefix=/usr

Exporting the DH_VERBOSE in the debian/rules file as above forces the debhelper tool to make a fine grained build report.

Exporting the DEB_BUILD_MAINT_OPTION as above sets the hardening options as described in the “FEATURE AREAS/ENVIRONMENT” in dpkg-buildflags(1).
[This is a cliché to force read-only relocation link for the hardening and to prevent the lintian warning “W: debhello: hardening-no-relro usr/bin/hello”. This is not really needed for this example but should be harmless. The lintian seems to produce false positive warning for this case which has no linked library.]

Exporting the DEB_CFLAGS_MAINT_APPEND as above forces C compiler to emit all the warnings.

Exporting the DEB_LDFLAGS_MAINT_APPEND as above forces linker to link only when the library is actually needed.
[This is a cliché to prevent overlinking for the complex library dependency case such as Gnome programs. This is not really needed for this simple example but should be harmless.]

The dh_auto_install command for the Makefile based build system does essentially “$(MAKE) install DESTDIR=debian/debhello”. The creation of this override_dh_auto_install target changes its behavior to “$(MAKE) install DESTDIR=debian/debhello prefix=/usr”.

Here are the maintainer version of the debian/control and debian/copyright files.

debian/control (maintainer version):
 $ vim debhello-0.0/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-0.0/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: debhelper (>=9)
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: example package in the debmake-doc package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
debian/copyright (maintainer version):
 $ vim debhello-0.0/debian/copyright
 ... hack, hack, hack, ...
 $ cat debhello-0.0/debian/copyright
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: debhello
Source: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/tree/base...

Files:     *
Copyright: 2015 Osamu Aoki <osamu@debian.org>
License:   MIT
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 and/or sell copies of the Software, and to permit persons to whom the
 Software is furnished to do so, subject to the following conditions:
 .
 The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
 .
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

There are several other template files under the debian/ directory. These also needs to be updated.

Template files under debian/. (v=0.0):
 $ tree debhello-0.0/debian
debhello-0.0/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── patches
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 10 files
Tip
Configuration files used by the dh_* commands from the debhelper package usually treat # as the start of the comment line.

Step-by-step: debuild

You can create a non-native Debian package using the debuild command (or its equivalents) in this source tree. The command output is very verbose and explains what it does as follows.

 $ cd debhello-0.0
 $ debuild
 dpkg-buildpackage -rfakeroot -D -us -uc -i -i
 ...
 fakeroot debian/rules clean
dh clean
 ...
 debian/rules build
dh build
   dh_testdir
   dh_auto_configure
   dh_auto_build
        make -j1
make[1]: Entering directory '/path/to/debhello-0.0'
# CFLAGS=-g -O2 -fPIE -fstack-protector-strong -Wformat
# -Werror=format-security -Wall -pedantic
cc -D_FORTIFY_SOURCE=2 -g -O2 -fPIE -fstack-protector-strong -Wformat -Werror...
make[1]: Leaving directory '/path/to/debhello-0.0'
 ...
 fakeroot debian/rules binary
dh binary
 ...
Now running lintian...
 ...
W: debhello: binary-without-manpage usr/bin/hello
N:
N:    Each binary in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games should
N:    have a manual page
 ...
Finished running lintian.

You can verify CFLAGS is updated properly with -Wall and -pedantic by the DEB_CFLAGS_MAINT_APPEND variable.

The manpage should be added to the package as reported by the lintian package as shown in the later examples (see [more]). Let’s move on for now.

Let’s inspect the result.

The generated files of debhello version 0.0 by the debuild command:
 $ cd ..
 $ tree -FL 1
.
├── debhello-0.0/
├── debhello-0.0.tar.gz
├── debhello_0.0-1.debian.tar.xz
├── debhello_0.0-1.dsc
├── debhello_0.0-1_amd64.build
├── debhello_0.0-1_amd64.changes
├── debhello_0.0-1_amd64.deb
└── debhello_0.0.orig.tar.gz -> debhello-0.0.tar.gz

1 directory, 7 files

You see all the generated files.

  • The debhello_0.0.orig.tar.gz is a symlink to the upstream tarball.

  • The debhello_0.0-1.debian.tar.xz contains the maintainer generated contents.

  • The debhello_0.0-1.dsc is the meta data file for the Debian source package.

  • The debhello_0.0-1_amd64.deb is the Debian binary package.

  • The debhello_0.0-1_amd64.changes is the meta data file for the Debian binary package.

The debhello_0.0-1.debian.tar.xz contains the Debian changes to the upstream source as follows.

The compressed archive contents of debhello_0.0-1.debian.tar.xz:
 $ tar -tzf debhello-0.0.tar.gz
debhello-0.0/
debhello-0.0/Makefile
debhello-0.0/src/
debhello-0.0/src/hello.c
debhello-0.0/LICENSE
 $ tar --xz -tf debhello_0.0-1.debian.tar.xz
debian/
debian/patches/
debian/patches/series
debian/control
debian/changelog
debian/rules
debian/source/
debian/source/format
debian/README.Debian
debian/compat
debian/watch
debian/copyright

The debhello_0.0-1_amd64.deb contains the files to be installed as follows.

The binary package contents of debhello_0.0-1_amd64.deb:
 $ dpkg -c debhello_0.0-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/bin/
-rwxr-xr-x root/root ...  ./usr/bin/hello
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/debhello/
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/changelog.Debian.gz
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/copyright

The generated dependency of debhello_0.0-1_amd64.deb is as follows.

The generated dependency of debhello_0.0-1_amd64.deb:
 $ dpkg -f debhello_0.0-1_amd64.deb pre-depends depends recommends conflics b...
Depends: libc6 (>= 2.2.5)
Caution
Much more details need to be addressed before uploading the package to the Debian archive.
Note
If manual adjustments of auto-generated configuration files are skipped, the generated binary package may lack meaningful package description and some of the policy requirements may be missed. This sloppy package functions well under the dpkg command, and may be good enough for your local deployment.

Alternative: patch files

The above step-by-step example did not touch the upstream source to make the proper Debian package.

An alternative approach is to change the upstream source by creating the patch 000-prefix-usr.patch which modifies the upstream Makefile to set the $(prefix) value to /usr in advance.

create 000-prefix-usr.patch by the diff command:
 $ cp -a debhello-0.0 debhello-0.0.orig
 $ vim debhello-0.0/Makefile
 ... hack, hack, hack, ...
 $ diff -Nru debhello-0.0.orig debhello-0.0 >000-prefix-usr.patch
 $ cat 000-prefix-usr.patch
diff -Nru debhello-0.0.orig/Makefile debhello-0.0/Makefile
--- debhello-0.0.orig/Makefile  2015-06-07 10:13:30.656635296 +0900
+++ debhello-0.0/Makefile       2015-06-07 10:13:30.824635292 +0900
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

 $ rm -rf debhello-0.0
 $ mv -f debhello-0.0.orig debhello-0.0

Please note that the upstream source tree is restored to the original state.

The packaging is practically the same as the above step-by-step example except for 2 points of the maintainer modification.

The maintainer modification to the debian/rules file doesn’t have the override_dh_auto_install target as follows:

debian/rules (alternative maintainer version):
 $ vim debhello-0.0/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-0.0/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

The maintainer modification to the upstream source during the package building process is enabled by adding the corresponding patch file in the debian/patches/ directory and listing its file names in the debian/patches/series file.

Set of files to modify the upstream Makefile:
 $ echo '000-prefix-usr.patch' >debhello-0.0/debian/patches/series
 $ vim 000-prefix-usr.patch
 ... hack, hack, hack, ...
 $ mv -f 000-prefix-usr.patch debhello-0.0/debian/patches/000-prefix-usr.patc...
 $ cat debhello-0.0/debian/patches/000-prefix-usr.patch
From: Osamu Aoki <osamu@debian.org>
Description: set prefix=/usr patch
diff -Nru debhello-0.0.orig/Makefile debhello-0.0/Makefile
--- debhello-0.0.orig/Makefile
+++ debhello-0.0/Makefile
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

The rest of the packaging is the same as the step-by-step example.

As indicated in [patchapproach], there are several tools other than the diff command which generate patch files used for this alternative approach of packaging. Most frequently used ones are the dquilt or gbp-pq commands.

There is no need to create the patch file in advance for these commands since it can be generated as you make the maintainer modification. Here is an example for the dquilt command.

patch file generation using the dquilt command:
 $ cd debhello-0.0
 $ dquilt new 000-prefix-usr.patch
Patch debian/patches/000-prefix-usr.patch is now on top
 $ dquilt add Makefile
File Makefile added to patch debian/patches/000-prefix-usr.patch
 ... hack, hack, hack, ...
 $ head -1 Makefile
prefix = /usr
 $ dquilt refresh
Refreshed patch debian/patches/000-prefix-usr.patch
 $ dquilt header -e --dep3
 ... hack, hack, hack, ...
Replaced header of patch 000-prefix-usr.patch
 $ dquilt pop -a
Removing patch debian/patches/000-prefix-usr.patch
Restoring Makefile

No patches applied
 $ cat debian/patches/series
000-prefix-usr.patch
 $ cat debian/patches/000-prefix-usr.patch
Description: set prefix=/usr patch
Author: Osamu Aoki <osamu@debian.org>
Index: debhello-0.0/Makefile
===================================================================
--- debhello-0.0.orig/Makefile
+++ debhello-0.0/Makefile
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

 $ cd ..
Tip
If the package is maintained in the git repository using the gbp command, please use the gbp-pq command to manage patches.

This alternative approach to the Debian packaging using a series of patch files may be less robust for the future upstream changes but more flexible to cope with the difficult upstream source. (See [deb3].)

Basics

It’s time to learn the basic rules of the Debian packaging.

The Debian source package is a set of input files used to build the Debian binary package and is not a single file.

The Debian binary package is a special archive file which holds a set of installable binary data with their associated information.

A single Debian source package may generate multiple Debian binary packages defined in the debian/control file.

The non-native Debian package in the “3.0 (quilt)” format is the most normal Debian binary package format.

Note
There are many wrapper scripts. Use them to streamline your workflow but make sure to understand the basics of their internals.

Packaging workflow

The Debian packaging workflow to create the Debian binary package involves generating several specifically named files (see [name-version]) as defined in the “Debian Policy Manual”.

The oversimplified method for the Debian packaging workflow can be summarized in 5 steps as follows.

  1. The upstream tarball is downloaded as the package-version.tar.gz file.

  2. The upstream tarball is untarred to create many files under the package-version/ directory.

  3. The upstream tarball is copied (or symlinked) to the particular filename packagename_version.orig.tar.gz.

    • the character separating package and version is changed from - (hyphen) to _ (underscore)

    • .orig is added in the file extension.

  4. The Debian package specification files are added to the upstream source under the package-version/debian/ directory.

    • Required specification files under the debian/*:

      debian/rules

      The executable script for building the Debian package (see [rules])

      debian/control

      The package configuration file containing the source package name, the source build dependency, the binary package name, the binary dependency, etc. (see [control])

      debian/changelog

      The Debian package history file defining the upstream package version and the Debian revision in its first line (see [changelog])

      debian/copyright

      The copyright and license summary (see [copyright])

    • Optional specification files under the debian/* (see [debianconf]):

    • The debmake command invoked in the package-version/ directory provides the initial set of these template configuration files.

      • Required specification files are generated even with the -x0 option.

      • The debmake command does not overwrite any existing configuration files.

    • These files must be manually edited to their perfection according to the “Debian Policy Manual” and “Debian Developer’s Reference”.

  5. The dpkg-buildpackage command (usually from its wrapper debuild or pdebuild) is invoked in the package-version/ directory to make the Debian source and binary packages by invoking the debian/rules script.

    • The current directory is set as: $(CURDIR)=/path/to/package-version/

    • Create the Debian source package in the “3.0 (quilt)” format using dpkg-source(1)

      • package_version.orig.tar.gz (copy or symlink of package-version.tar.gz)

      • package_version-revision.debian.tar.xz (tarball of package-version/debian/*)

      • package_version-revision.dsc

    • Build the source using “debian/rules build” into $(DESTDIR)

      • DESTDIR=debian/binarypackage/ (single binary package)

      • DESTDIR=debian/tmp/ (multi binary package)

    • Create the Debian binary package using dpkg-deb(1), and dpkg-genchanges(1).

      • binarypackage_version-revision_arch.deb

      • … (There may be multiple Debian binary package files.)

      • package_version-revision_arch.changes

  6. Check the quality of the Debian package with the lintian command. (recommended)

  7. Sign the package_version-revision.dsc and package_version-revision_arch.changes with the debsign command using your private GPG key.

  8. Upload the set of the Debian source and binary package files with the dput command to the Debian archive.

Here, please replace each part of the filename as:

  • the package part with the Debian source package name

  • the binarypackage part with the Debian binary package name

  • the version part with the upstream version

  • the revision part with the Debian revision

  • the arch part with the package architecture

Tip
There is very extensive documentation in Chapter 6. Best Packaging Practices of the “Debian Developer’s Reference”. Please read it.

Package name and version

If the upstream source comes as hello-0.9.12.tar.gz, you can take hello as the upstream source package name and 0.9.12 as the upstream version.

debmake is meant to provide template files for the package maintainer to work on. Comment lines started by # contain the tutorial text. You must remove or edit such comment lines before uploading to the Debian archive.

There are some limitations for what characters may be used as a part of the Debian package. The most notable limitation is the prohibition of uppercase letters in the package name. Here is the summary in the regular expression.

  • Upstream package name (-p): [-+.a-z0-9]{2,}

  • Binary package name (-b): [-+.a-z0-9]{2,}

  • Upstream version (-u): [0-9][-+.:~a-z0-9A-Z]*

  • Debian revision (-r): [0-9][+.~a-z0-9A-Z]*

See the exact definition in Chapter 5 - Control files and their fields of the “Debian Policy Manual”.

You must adjust the package name and upstream version accordingly for the Debian packaging.

In order to manage the package name and version information effectively under popular tools such as the aptitude command, it is a good idea to keep the length of package name to be equal or less than 30 characters; and the total length of version and revision to be equal or less than 14 characters.
[For more than 90% of packages, the package name is equal or less than 24 characters; the upstream version is equal or less than 10 characters and the Debian revision is equal or less than 3 characters.]

In order to avoid name collisions, the user visible binary package name should not be chosen from any generic words.

If upstream does not use a normal versioning scheme such as 2.30.32 but uses some kind of date such as 11Apr29, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the debian/changelog file. If you need to invent a version string, use the YYYYMMDD format such as 20110429 as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as 0.1 in future, use the 0~YYMMDD format such as 0~110429 as upstream version, instead.

Version strings can be compared using the dpkg command as follows.

$ dpkg --compare-versions ver1 op ver2

The version comparison rule can be summarized as:

  • Strings are compared from the head to the tail.

  • Letters are larger than digits.

  • Numbers are compared as integers.

  • Letters are compared in ASCII code order.

There are special rules for period (.), plus (+), and tilde (~) characters, as follows.

0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0

One tricky case occurs when upstream releases hello-0.9.12-ReleaseCandidate-99.tar.gz as the pre-release of hello-0.9.12.tar.gz. You can ensure the upgrade to work properly by renaming the upstream source to hello-0.9.12~rc99.tar.gz having the proper version order.

Native Debian package

The non-native Debian package in the “3.0 (quilt)” format is the most normal Debian binary package format. The above workflow and the following packaging examples always use this format.

The native Debian package is the rare Debian binary package format. It may be used only when the package is useful and valuable only for Debian. Thus, its use is generally deprecated.

Caution
The native debian package is often accidentally built when its upstream tarball is not accessible from the dpkg-buildpackage command with its correct name package_version.orig.tar.gz . A typical newbie mistake is to make a symlink name with “-” instead of the correct one with “_”.

The native Debian package has no separation between the upstream code and the Debian changes and consists only with the following:

  • package_version.tar.gz (copy or symlink of package-version.tar.gz with debian/* files.)

  • package_version.dsc

If you need to create the native Debian package, create it in the “3.0 (native)” format using dpkg-source(1).

Tip
Some people promote to package even programs which have been written only for Debian in the non-native package format. The required tarball without debian/* files needs to be manually generated in advance before the standard workflow in [workflow].
[Use of the “debameke -t …” command can help this workflow. See [dt-option].]
They claim that the use of non-native package format eases communication with the downstream distributions.

debian/rules

The debian/rules script is the executable script to build the Debian package.

  • The debian/rules script re-targets the upstream build system (see [build]) to install files in the $(DESTDIR) and creates the archive file of the generated files as the deb file.

    • The deb file is used for the binary distribution and installed to the system using the dpkg command.

  • The dh command is normally used as the front-end to the build system inside the debian/rules script.

  • $(DESTDIR) path depends on the build type.

    • $(DESTDIR)=debian/binarypackage (single binary package)

    • $(DESTDIR)=debian/tmp (multiple binary package)

dh

The dh command from the debhelper package with the help from its associated packages functions as the wrapper to the typical upstream build systems and offers us with the uniform access to them by supporting all the Debian policy stipulated targets of the debian/rules file.

  • dh clean : clean files in the source tree.

  • dh build : build the source tree

  • dh build-arch : build the source tree for architecture dependent packages

  • dh build-indep : build the source tree for architecture independent packages

  • dh install : install the binary files to $(DESTDIR)

  • dh install-arch : install the binary files to $(DESTDIR) for architecture dependent packages

  • dh install-indep : install the binary files to $(DESTDIR) for architecture independent packages

  • dh binary : generate the deb file

  • dh binary-arch : generate the deb file for architecture dependent packages

  • dh binary-indep : generate the deb file for architecture independent packages

Note
For debhelper “compat >= 9”, the dh command exports compiler flags (CFLAGS, CXXFLAGS, FFLAGS, CPPFLAGS and LDFLAGS) with values as returned by dpkg-buildflags if they are not set previously. (The dh command calls set_buildflags defined in the Debian::Debhelper::Dh_Lib module.)

Simple debian/rules

Thanks to this abstraction of the dh command
[This simplicity is available since the version 7 of the debhelper package. This guide assumes the use of the debhelper version 9 or newer.]
, the Debian policy compliant debian/rules file supporting all the required targets can be written as simple as
[The debmake command generates a bit more complicated debian/rules file. But this is the core part.]
:

Simple debian/rules:
#!/usr/bin/make -f
#export DH_VERBOSE = 1

%:
        dh $@

Essentially, this dh command functions as the sequencer to call all required dh_* commands at the right moment.

Note
The debmake command sets the debian/control file with “Build-Depends: debhelper (>=9)” and the debian/compat file with “9”.
Tip
Setting “export DH_VERBOSE = 1” outputs every command that modifies files on the build system. Also it enables verbose build logs for some build systems.

Customized debian/rules

Flexible customization of the debian/rules is realized by adding appropriate override_dh_* targets and their rules.

Whenever some special operation is required for a certain dh_foo command invoked by the dh command, any automatic execution of it can be overridden by adding the makefile target override_dh_foo in the debian/rules file.

The debmake command creates the initial template file taking advantage of the above simple debian/rules while adding some extra customizations for the package hardening, etc.

You need to know how underlying build systems work under the hood (see [build]) to address their irregularities using the package customization.

See [simple] for the actual simple debian/rules generated by the debmake command which comes with the commented out parts addressing the hardening via compile options (see [harden]) and the multiarch customization (see [multiarch]).

Variables for debian/rules

Some variable definitions useful for customizing debian/rules can be found in files under /usr/share/dpkg/. Notably:

pkg-info.mk

DEB_SOURCE, DEB_VERSION, DEB_VERSION_EPOCH_UPSTREAM, DEB_VERSION_UPSTREAM_REVISION, DEB_VERSION_UPSTREAM, and DEB_DISTRIBUTION variables.
These are useful for the backport support etc..

vender.mk

DEB_VENDOR and DEB_PARENT_VENDOR variables; and dpkg_vendor_derives_from macro.
These are useful for the vendor support (Debian, Ubuntu, …).

architecture.mk

Set DEB_HOST_* and DEB_BUILD_* variables.
Only variables used explicitly in debian/rules need to be defined using dpkg-architecture. So there is no need to include architecture.mk in debian/rules.

buildflags.mk

Set CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS, FCFLAGS, and LDFLAGS build flags.

If you wish to use some of these useful variables in debian/rules, copy relevant codes to debian/rules or write a simpler alternative in it. Please keep debian/rules simple.

For example, you can add an extra option to CONFIGURE_FLAGS for linux-any target architectures by adding the followings to debian/rules:

DEB_HOST_ARCH_OS ?= $(shell dpkg-architecture -qDEB_HOST_ARCH_OS)
 ...
ifeq ($(DEB_HOST_ARCH_OS),linux)
CONFIGURE_FLAGS += --enable-wayland
endif
Tip
It was useful to include buildflags.mk in the debian/rules to set the build flags such as CPPFLAGS, CFLAGS, LDFLAGS, etc. properly while honoring DEB_CFLAGS_MAINT_APPEND, DEB_BUILD_MAINT_OPTIONS, etc. for the debhelper “compat <= 8”. Now you should use the debhelper “compat >= 9”, should not include buildflags.mk without specific reasons, and should let the dh command set these build flags.

See [multiarch], dpkg-architecture(1) and dpkg-buildflags(1).

Reproducible build

Here are some recommendations to attain the reproducible build result.

  • Don’t embed the timestamp based on the system time.

  • Use “dh $@” in the debian/rules to access the latest debhelper features.

  • Export the build environment as “LC_ALL=C.UTF-8” (see [utf-8-build]).

  • Read more at ReproducibleBuilds.

If the timestamp is needed, please consider to patch the upstream source to obtain the timestamp from the last entry in debian/changelog.

Shell code snippet example to obtain a formatted timestamp string:
date +'%Y-%m-%d' -d"`dpkg-parsechangelog -SDate`"

debian/control

The debian/control file consists of blocks of meta data separated by the blank line. Each block of meta data defines the following in this order:

  • meta data for the Debian source package

  • meta data for the Debian binary packages

See Chapter 7 - Declaring relationships between packages in the “Debian Policy Manual” for the definition of each meta data.

The debmake command with the -b option (see [boption]) creates the initial template debian/control file with followings:

  • a set of Package stanzas defining the split of the Debian binary packages

  • a basic set of substvar used in each pertinent stanza

Split of the Debian binary package

For well behaving build systems, the split of the Debian binary package into small ones can be realized as follows.

  • Create binary package entries for all binary packages in the debian/control file.

  • List all file paths (relative to debian/tmp) in the corresponding debian/binarypackage.install files.

Please check examples in this guide:

Substvar

The debian/control file also defines the package dependency in which the variable substitutions mechanism (substvar) may be used to free package maintainers from chores of tracking most of the simple package dependency cases. See deb-substvars(5).

The debmake command supports following substvars.

  • ${misc:Depends} for all binary packages

  • ${misc:Pre-Depends} for all multiarch packages

  • ${shlibs:Depends} for all binary executable and library packages

  • ${python:Depends} for all Python packages

  • ${python3:Depends} for all Python3 packages

  • ${perl:Depends} for all Perl packages

  • ${ruby:Depends} for all Ruby packages

For the shared library, required libraries found simply by "objdump -p /path/to/program | grep NEEDED" are covered by the shlib substvar.

For the Python and other interpreters, required modules found simply looking for lines with “import”, “use”, “require”, etc., are covered by the corresponding substvar.

For other programs which do not deploy their own substvar, the misc substvar covers their dependency.

For POSIX shell programs, there is no easy way to identify the dependency and no substvar covers their dependency.

For libraries and modules required via the dynamic loading mechanism including the GObject introspection mechanism, there is no easy way to identify the dependency and no substvar covers their dependency.

binNMU safe

For the safe binNMU, the dependency among binary packages from a same source package needs attention if there are both “Architecture: any” and “Architecture: all” packages involved in it.

  • Architecture: any” package depends on “Architecture: anyfoo package

    • Depends: foo (== ${binary:Version})

  • Architecture: any” package depends on “Architecture: allbar package

    • Depends: bar (== ${source:Version}

  • Architecture: all” package depends on “Architecture: anybaz package

    • Depends: baz (>= ${source:Version}), baz (<< ${source:Upstream-Version}.0~)

The library package name

Let’s consider that the upstream source tarball of the libfoo library is updated from libfoo-7.0.tar.gz to libfoo-8.0.tar.gz with the new SONAME major version which affects other packages.

The binary library package must be renamed from libfoo7 to libfoo8 to keep the unstable suite system working for all dependent packages after the upload of the package based on the libfoo-8.0.tar.gz.

Warning
If the binary library package isn’t renamed, many dependent packages in the unstable suite become broken just after the library upload even if the binNMU is requested. The binNMU may not happen immediately after the upload due to several reasons.

The -dev package must follow one of the following naming rules:

  • Use the unversioned -dev package name: libfoo-dev

    • This is the normal case.

    • Only one version of the library source package is allowed in the archive.

      • The associated library package needs to be renamed from libfoo7 to libfoo8 to prevent the dependency breakage in the unstable archive during the library transition.

    • This approach must be used if the simple binNMU resolves the library dependency. (ABI change)

    • This approach is still a good idea if manual code updates, etc. can be coordinated. (API change)

  • Use the versioned -dev package names: libfoo7-dev and libfoo8-dev

    • This is the special case.

    • Two versions of the library source packages are allowed simultaneously in the archive.

      • Make all dependent packages depend on libfoo-dev.

      • Make both libfoo7-dev and libfoo8-dev provide libfoo-dev.

      • The source package needs to be renamed as libfoo7-7.0.tar.gz and libfoo8-8.0.tar.gz respectively from libfoo-?.0.tar.gz.

      • The package specific install file path including libfoo7 and libfoo8 respectively for header files etc. needs to be chosen to make them co-installable.

    • Do not use this approach, if possible.

    • This approach may be useful if the update of dependent packages require major manual code updates, etc. (API change)

See [lib].

debmake -b

The -b option of the debmake command provides intuitive and flexible methods to customize packaging parameters in the debian/control file. It sets the following stanza values.

  • Package:

  • Architecture:

  • Multi-Arch:

  • Depends:

  • Pre-Depends:

Let’s quote the pertinent part from the debmake manpage here.

-b "binarypackage[:type],…", --binaryspec "binarypackage[:type],…"

set binary package specs by the comma separated list of binarypackage:type pairs, e.g., in full form “foo:bin,foo-doc:doc,libfoo1:lib,libfoo1-dbg:dbg,libfoo-dev:dev” or in short form “,-doc,libfoo1,libfoo1-dbg, libfoo-dev”.

Here, binarypackage is the binary package name; and optional type is chosen from the following type values:

  • bin: C/C++ compiled ELF binary code package (any, foreign) (default, alias: "", i.e., null-string)

  • data: Data (fonts, graphics, …) package (all, foreign) (alias: da)

  • dbg: Debug symbol package (any, same) (alias: db)

  • dev: Library development package (any, same) (alias: de)

  • doc: Documentation package (all, foreign) (alias: do)

  • lib: Library package (any, same) (alias: l)

  • perl: Perl script package (all, foreign) (alias: pl)

  • python: Python script package (all, foreign) (alias: py)

  • python3: Python3 script package (all, foreign) (alias: py3)

  • ruby: Ruby script package (all, foreign) (alias: rb)

  • script: Shell script package (all, foreign) (alias: sh)

The pair values in the parentheses, such as (any, foreign), are the Architecture and Multi-Arch stanza values set in the debian/control file.

In many cases, the debmake command makes good guesses for type from binarypackage. If type is not obvious, type is set to bin. For example, libfoo sets type to lib, and font-bar sets type to data, …

If the source tree contents do not match settings for type, debmake warns you.

Here are some typical multiarch package split scenarios for the following upstream source examples:

  • a library source libfoo-1.0.tar.gz

  • a tool source bar-1.0.tar.gz written in a compiled language

  • a tool source baz-1.0.tar.gz written in an interpreted language

binarypackage type Architecture: Multi-Arch: Package content

libfoo1

lib*

any

same

the shared library, co-installable

libfoo1-dbg

dbg*

any

same

the shared library debug symbols, co-installable

libfoo-dev

dev*

any

same

the shared library header files etc., co-installable

libfoo-tools

bin*

any

foreign

the run-time support programs, not co-installable

libfoo-doc

doc*

all

foreign

the shared library documentation files

bar

bin*

any

foreign

the compiled program files, not co-installable

bar-doc

doc*

all

foreign

the documentation files for the program

baz

script

all

foreign

the interpreted program files

Tip
The binary package name starting with a “-” (hyphen) is treated as the abbreviated name. The real binary package name is generated by attaching it to the source package name.

For the cases marked with * in the above table, the type values are guessed right from the package names.

The default type is the bin type which means the compiled ELF binary executables. This is why the example in [simple] does not specify -b option.

For programs written in other compiled languages, you may need to add its run-time library package dependency to the resulting binary package by adjusting the Depends: stanza of the debian/control file.

The development package for the shared library should depend on it and should contain a version numberless symlink to it. E.g.: /usr/lib/x86_64-linux-gnu/libfoo.solibfoo.so.1

Note
The dbg type package can be made either one-on-one for each bin and lib type package or one-on-all for all bin and lib type packages.

debian/changelog

The debian/changelog file records the Debian package history and defines the upstream package version and the Debian revision in its first line.

The debmake command creates the initial template file with the upstream package version and the Debian revision. The distribution is set to UNRELEASED to prevent accidental upload to the Debian archive.

The debchange command (alias dch) is used to edit this.

Tip
The date string used in the debian/changelog file can be manually generated by “LC_ALL=C date -R”.

This is installed in the /usr/share/doc/binarypackage directory as changelog.Debian.gz by the dh_installchangelogs.

The upstream changelog is installed in the /usr/share/doc/binarypackage directory as changelog.gz.

The upstream changelog is automatically found by the dh_installchangelogs using the case insensitive match of its file name to changelog, changes, changelog.txt, changes.txt, history, history.txt, or changelog.md and searched in the ./ doc/, or docs/ directories.

After finishing your packaging and verifying its quality, please execute the “dch -r” and save the finalized debian/changelog file with the distribution normally set to unstable.
[If you are using the vim editor, make sure to save this with the “:wq” command.]
If you are packaging for the backports, security updates, LTS, etc., please use the appropriate distribution names, instead.

Debian takes the copyright and license matters very seriously. The “Debian Policy Manual” enforces to have summary of them in the debian/copyright file in the package.

You should format it as the machine-readable debian/copyright file (DEP-5).

Caution
The debian/copyright file should be sorted to keep the generic file patterns at the top of the list. See [koption].

The debmake command creates the initial DEP-5 compatible template file by scanning the entire source tree. It uses an internal license checker to classify each license text.
[The licensecheck command from the devscripts package was referenced to make this internal checker.]

Unless specifically requested to be pedantic with the -P option, the debmake command skips reporting for auto-generated files with permissive licenses to be practical.

Note
If you find issues with this license checker, please file a bug report to the debmake package with the problematic part of text containing the copyright and license.

DFSG

Debian takes software freedom seriously and follows the DFSG.

The non-DFSG components in the upstream source tarball can be easily removed when the uscan command is used to update the Debian package.

  • List the files to be removed in the Files-Excluded stanza of the debian/copyright file.

  • List the URL to download the upstream tarball in the debian/watch file.

  • Run the uscan command to download the new upstream tarball.

    • Alternatively, use the “gbp import-orig --uscan --pristine-tar” command.

  • The resulting tarball has the version number with an additional suffix +dfsg.

Other debian/*

Optional configuration files may be added under the debian/ directory. Most of them are to control dh_* commands offered by the debhelper package but there are some for lintian and gbp commands. Here is the alphabetical list of notable optional configuration files.

binarypackage.bug-control -x3

installed as usr/share/bug/binarypackage/control in binarypackage. See [bug].

binarypackage.bug-presubj -x3

installed as usr/share/bug/binarypackage/presubj in binarypackage. See [bug].

binarypackage.bug-script -x3

installed as usr/share/bug/binarypackage or usr/share/bug/binarypackage/script in binarypackage. See [bug].

clean -x2

List files which should be removed but are not cleaned by the dh_auto_clean command.

See dh_auto_clean(1) and dh_clean(1).

compat -x1

Set the debhelper compatibility level (currently, “9”).

See “COMPATIBILITY LEVELS” in debhelper(8).

binarypackage.conffile

No need for this file under “compat >= 3” since all files in the etc/ directory are conffiles.

See dh_installdeb(1).

If the program you’re packaging requires every user to modify the configuration files in the /etc directory, there are two popular ways to arrange for them to not be conffiles, keeping the dpkg command happy and quiet.

  • Create a symlink under the /etc directory pointing to a file under the /var directory generated by the maintainer scripts.

  • Create a file generated by the maintainer scripts under the /etc directory.

binarypackage.config

This is the debconf config script used for asking any questions necessary to configure the package. See [debconf].

binarypackage.cron.hourly -x3

Installed into the etc/cron/hourly/binarypackage file in binarypackage.

See dh_installcron(1) and cron(8).

binarypackage.cron.daily -x3

Installed into the etc/cron/daily/binarypackage file in binarypackage.

See dh_installcron(1) and cron(8).

binarypackage.cron.weekly -x3

Installed into the etc/cron/weekly/binarypackage file in binarypackage.

See dh_installcron(1) and cron(8).

binarypackage.cron.monthly -x3

Installed into the etc/cron/monthly/binarypackage file in binarypackage.

See dh_installcro*(1) and cron(8).

binarypackage.cron.d -x3

Installed into the etc/cron.d/binarypackage file in binarypackage.

See dh_installcron(1), cron(8), and crontab(5).

binarypackage.default -x3

If this exists, it is installed into etc/default/binarypackage in binarypackage.

See dh_installinit(1).

binarypackage.dirs -x3

List directories to be created in binarypackage.

See dh_installdirs(1).

Usually, this is not needed since all dh_install* commands create required directories automatically. Use this only when you run into trouble.

binarypackage.doc-base -x2

Installed as the doc-base control file in binarypackage.

See dh_installdocs(1) and Debian doc-base Manual provided by the doc-base package.

binarypackage.docs -x2

List documentation files to be installed in binarypackage.

See dh_installdocs(1).

binarypackage.emacsen-compat -x3

Installed into usr/lib/emacsen-common/packages/compat/binarypackage in binarypackage.

See dh_installemacsen(1).

binarypackage.emacsen-install -x3

Installed into usr/lib/emacsen-common/packages/install/binarypackage in binarypackage.

See dh_installemacsen(1).

binarypackage.emacsen-remove -x3

Installed into usr/lib/emacsen-common/packages/remove/binarypackage in binarypackage.

See dh_installemacsen(1).

binarypackage.emacsen-startup -x3

Installed into usr/lib/emacsen-common/packages/startup/binarypackage in binarypackage.

See dh_installemacsen(1).

binarypackage.examples -x2

List example files or directories to be installed into usr/share/doc/binarypackage/examples/ in binarypackage.

See dh_installexamples(1).

gbp.conf

If this exists, it functions as the configuration file for the gbp command.

See gbp.conf(5), gbp(1), and git-buildpackage(1).

binarypackage.info -x2

List info files to be installed in binarypackage.

See dh_installinfo(1).

binarypackage.init -x3

Installed into etc/init.d/binarypackage in binarypackage.

See dh_installinit(1).

binarypackage.install -x2

List files which should be installed but are not installed by the dh_auto_install command.

See dh_install(1) and dh_auto_install(1).

license-examples/* -x4

These are copyright file examples generated by the debmake command. Use these as the reference for making copyright file.

Please make sure to erase these files.

binarypackage.links -x2

List pairs of source and destination files to be symlinked. Each pair should be put on its own line, with the source and destination separated by the whitespace.

See dh_link(1).

binarypackage.lintian-overrides -x3

Installed into usr/share/lintian/overrides/binarypackage in the package build directory. This file is used to suppress erroneous lintian diagnostics.

See dh_lintian(1) and lintian(1).

manpage.* -x3

These are manpage template files generated by the debmake command. Please rename these to appropriate file names and update their contents.

Debian Policy requires that each program, utility, and function should have an associated manual page included in the same package. Manual pages are written in nroff(1).

If you are new to making manpage, use manpage.asciidoc or manpage.1 as the starting point.

binarypackage.manpages -x2

List man pages to be installed.

See dh_installman(1).

binarypackage.menu -x2

Debian menu file installed into usr/share/menu/binarypackage in binarypackage.

See menufile(5) for its format. See dh_installmenu(1).

NEWS

Installed into usr/share/doc/binarypackage/NEWS.Debian.

See dh_installchangelogs(1).

patches/*

Collection of -p1 patch files which are applied to the upstream source before building the source.

See dpkg-source(8), [quilt-setup] and [alt-patch].

No patch files are generated by the debmake command.

patches/series -x1

The application sequence of the patches/* patch files.

binarypackage.preinst -x2
binarypackage.postinst -x2
binarypackage.prerm -x2
binarypackage.postrm -x2

These maintainer scripts are installed into the DEBIAN directory.

Inside the scripts, the token #DEBHELPER# is replaced with shell script snippets generated by other debhelper commands.

See dh_installdeb(1) and Chapter 6 - Package maintainer scripts and installation procedure of the “Debian Policy Manual”.

See also debconf-devel(7) and 3.9.1 Prompting in maintainer scripts of the “Debian Policy Manual”.

README.Debian -x1

Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/README.Debian.

See dh_installdocs(1).

This file provides the information specific to the Debian package.

binarypackage.service -x3

If this exists, it is installed into lib/systemd/system/binarypackage.service in binarypackage.

See dh_systemd_enable(1), dh_systemd_start(1), and dh_installinit(1).

source/format -x1

The Debian package format.

  • Use “3.0 (quilt)” to make this non-native package (recommended)

  • Use “3.0 (native)” to make this native package

    See “SOURCE PACKAGE FORMATS” in dpkg-source(8).

source/lintian-overrides or source.lintian-overrides -x3

These files are not installed, but will be scanned by the lintian command to provide overrides for the source package.

See dh_lintian(1) and lintian(1).

source/local-options -x1

This is not included in the generated source package but committed to the VCS for its smooth operation.

See “FILE FORMATS” in dpkg-source(8).

source/options

See the dpkg-source(1) manpage under "FILE FORMATS" to learn about the package formats and the patch mechanisms.

See “FILE FORMATS” in dpkg-source(8).

binarypackage.symbols -x2

The symbols files, if present, are passed to the dpkg-gensymbols command to be processed and installed.

See dh_makeshlibs(1) and [symbols]..

binarypackage.templates

This is the debconf templates file used for asking any questions necessary to configure the package. See [debconf].

tests/control

This is the RFC822-style test metadata file defined in DEP-8. See adt-run(1) and [ci].

TODO

Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/TODO.Debian.

See dh_installdocs(1).

binarypackage.tmpfile -x3

If this exists, it is installed into usr/lib/tmpfiles.d/binarypackage.conf in binarypackage.

See dh_systemd_enable(1), dh_systemd_start(1), and dh_installinit(1).

binarypackage.upstart -x3

If this exists, it is installed into etc/init/package.conf in the package build directory.

See dh_installinit(1) and [emptypkg].

watch -x1

The control file for the uscan command to download the latest upstream version

This control file may be configured to verify the authenticity of the tarball using its GPG signature (see [signing-key]).

See [dfsg] and uscan(1).

Here are a few reminders to the above list.

  • For the single binary package, binarypackage. part of the filename in the list may be removed.

  • For the multi binary package, configuration file missing binarypackage. part of the filename is applied to the first binary package listed in the debian/control.

  • When there are many binary packages, their configurations can be specified independently by prefixing their name to their configuration filenames such as package-1.install, package-2.install, etc.

  • Configuration template filenames with -x1, -x2, -x3, or -x4 in the above mean that they are generated by the debmake command with that -x option (see [xoption]).

  • Some template configuration files may not be created by the debmake command. In such cases, you need to create them with an editor.

  • Unusual configuration template files generated by the debmake command with the extra .ex suffix needs to be activated by removing that suffix.

  • Unused configuration template files generated by the debmake command should be removed.

  • Copy configuration template files as needed to the filenames matching their pertinent binary package names.

signing-key.pgp

Some packages are signed by the GPG key.

For example, GNU hello can be downloaded via HTTP from http://ftp.gnu.org/gnu/hello/ . There are sets of files:

  • hello-version.tar.gz (upstream source)

  • hello-version.tar.gz.sig (detached signature)

Let’s pick the latest version set.

$ wget http://ftp.gnu.org/gnu/hello/hello-2.9.tar.gz
 ...
$ wget http://ftp.gnu.org/gnu/hello/hello-2.9.tar.gz.sig
 ...
$ gpg --verify hello-2.9.tar.gz.sig
gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00
gpg: Can't check signature: public key not found

If you know the public GPG key of the upstream from the mailing list, use it as the debian/upstream/signing-key.pgp file. Otherwise, use the hkp keyserver and check it via your web of trust.

$ gpg --keyserver hkp://keys.gnupg.net --recv-key 80EE4A00
gpg: requesting key 80EE4A00 from hkp server keys.gnupg.net
gpg: key 80EE4A00: public key "Reuben Thomas <rrt@sc3d.org>" imported
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:               imported: 1
$ gpg --verify hello-2.9.tar.gz.sig
gpg: Signature made Thu 10 Oct 2013 08:49:23 AM JST using DSA key ID 80EE4A00
gpg: Good signature from "Reuben Thomas <rrt@sc3d.org>"
  ...
Primary key fingerprint: 9297 8852 A62F A5E2 85B2  A174 6808 9F73 80EE 4A00
Tip
If your network environment blocks access to the HPK port 11371, use “hkp://keyserver.ubuntu.com:80” instead.

After confirming the key ID 80EE4A00 is trust worthy one, download its public key into the debian/upstream/signing-key.pgp file.

$ gpg --armor --export 80EE4A00 >debian/upstream/signing-key.pgp

Then set the corresponding debian/watch file as follows.

version=3
pgpsigurlmangle=s/$/.sig/  http://ftp.gnu.org/gnu/hello/ hello-(\d[\d.]*)\.tar\.(?:gz|bz2|xz)

Now the uscan command will check the authenticity of the package using the GPG signature.

Package customization

Some upstream sources do not behave well and you may need to add customization to the build system of those upstream sources.

The package should be customized by the least invasive way to address the root cause of the Debian packaging problem. Your packaging shall be more robust for the future upgrades in this way. (You should also solve the root cause of the problem and send its patch to the upstream.)

Here, there are a few technical approaches to customize the build system:

  • debian/rules approach

  • debian/bianrypackage.* approach

  • patches/* approach

debian/rules approach

The customization to the Debian package build system can be done through the debian/rules file.

debian/binarypackage.* approach

Add customized configuration files for the dh_* command from the debhelper package in the debian/ directory.

patches/* approach

Modifications to the upstream source before building it can be done by placing the collection of the -p1 patches in the patches/ directory and applying them in sequence defined in the patches/series file.

There are several methods to prepare the required -p1 patches for this.

  • The diff command (manual)

  • The “git format-patches” command (manual for the git repository)

  • The dquilt command (manual, elegant) (alias of the quilt command, see [quilt-setup])

  • The gbp-pq command (specialized, simple)

  • The git-dpm command (specialized, elegant)

  • Patches used in other distros and floating on the mailing list

Wherever these patches come from, it is good idea to tag them with DEP-3 compatible header.

These patches should apply cleanly. For new upstream releases, you must normalize them by the dquilt command (see [quilt-setup]).

 $ while dquilt push; do dquilt refresh ; done
 $ dquilt pop -a
Caution
Don’t forget to normalize patches when you upgrade to the new upstream source or import the externally generated patches.

See [alt-patch] for example.

Upstream build systems

Upstream build systems are designed to go through several steps to install generated binary files to the system from the source distribution.

Autotools

Autotools (autoconf + automake) has 4 steps.

  1. setup the build system (“vim configure.ac Makefile.am” and “autoreconf -ivf”)

  2. configure the build system (“./configure”)

  3. build the source tree (“make”)

  4. install the binary files (“make install”)

The upstream usually performs the step 1 and builds the upstream tarball for distribution using the “make dist” command. (The generated tarball contains not only the pristine upstream VCS contents but also other generated files.)

The package maintainer needs to take care steps 2 to 4 at least. This is realized by the “dh $@ --with autotools-dev” command used in the debian/rules file.

The package maintainer may wish to take care all steps 1 to 4. This is realized by the “dh $@ --with autoreconf” command used in the debian/rules file. This rebuilds all auto-generated files to the latest version ones and provides better supports for the porting to the newer architectures.

If you wish to learn more on the Autotools, please see:

CMake

CMake has 4 steps.

  1. setup the build system (“vim CMakeLists.txt config.h.in”)

  2. configure the build system (“cmake”)

  3. build the source tree (“make”)

  4. install the binary files (“make install”)

The upstream tarball contains no auto-generated files and is generated by the tar command after the step 1.

The package maintainer needs to take care steps 2 to 4.

If you wish to learn more on the CMake, please see:

Python distutils

Python distutils has 3 steps.

  1. setup and configure the build system (“vim setup.py”)

  2. build the source tree (“python setup.py build”)

  3. install the binary files (“python setup.py install”)

The upstream usually performs the step 1 and builds the upstream tarball for distribution using the “python setup.py sdist” command.

The package maintainer needs to take care the step 2. This is realized simply by the “dh $@” command used in the debian/rules file, after jessie.

The situation of other build systems, such as CMake, are very similar to this Python one.

If you wish to learn more on the Python3 and distutils, please see:

Debugging information

The Debian package is built with the debugging information but packaged into the binary package after stripping the debugging information as required by Chapter 10 - Files of the “Debian Policy Manual”.

The debugging information can be packaged separately as the debug package using the “dh_strip --dbg-package=package” command in the override_dh_strip: target of the debian/rules file. The name of such debug package normally has the -dbg suffix.

Note
The creation of the -dbg package is optional. In future, it may be superseded by some new mechanism to provide the debugging information.

The installation path of the debugging information is as follows to enable auto-loading of it by the gdb command.

  • /usr/lib/debug/.build-id/12/3456… (compat>=9, for buildID=123456…)

  • /usr/lib/debug/path/to/binary (compat<<9, for /path/to/binary)

See

Library package

Packaging the library software requires you to perform much more work than usual. Here are some reminders for packaging the library software:

  • The library binary package must be named as [libnames].

  • Debian ships shared library such as /usr/lib/<triplet>/libfoo-0.1.so.1.0.0 (see [multiarch]).

  • Debian encourages to use versioned symbols in the shared library (see [symbols]).

  • Debian doesn’t ship *.la libtool library archive files.

  • Debian discourages to use and ship *.a static library files.

Before packaging the shared library software, see:

For the historic background study, see:

  • Escaping the Dependency Hell
    [This document was written before the introduction of the symbols file.]

    • This encourages to have versioned symbols in the shared library.

  • Debian Library Packaging guide
    [The strong preference to use the SONAME versioned -dev package names over the single -dev package name in its Chapter 6. Development (-DEV) packages does not seem to be shared by the former ftp-master (Steve Langasek). This document was written before the introduction of the multiarch system and the symbols file.]

Multiarch

The multiarch support for cross-architecture installation of binary packages (particularly i386 and amd64, but also other combinations) in the dpkg and apt packages introduced to Debian wheezy (7.0, May 2013) demands us to pay extra attention for the packaging.

You should read the following references in detail.

The multiarch is enabled by using the <triplet> value such as i386-linux-gnu and x86_64-linux-gnu in the install path of shared libraries as /usr/lib/<triplet>/, etc..

  • The <triplet> value required internally by debhelper scripts is implicitly set in themselves. The maintainer doesn’t need to worry.

  • The <triplet> value used in override_dh_* target scripts must be explicitly set in the debian/rules by the maintainer. The <triplet> value is stored in $(DEB_HOST_MULTIARCH) variable in the following debian/rules snippet example:

    DEB_HOST_MULTIARCH = $(shell dpkg-architecture -qDEB_HOST_MULTIARCH)
    ...
    override_dh_install:
            mkdir -p package1/lib/$(DEB_HOST_MULTIARCH)
            cp -dR tmp/lib/. package1/lib/$(DEB_HOST_MULTIARCH)

See [variablesrules] and dpkg-architecture.

The multiarch library path

Debian policy requires to follow Filesystem Hierarchy Standard. Its /usr/lib : Libraries for programming and packages states "/usr/lib includes object files, libraries, and internal binaries that are not intended to be executed directly by users or shell scripts."

Debian policy makes an exception to Filesystem Hierarchy Standard to use /usr/lib/<triplet>/ instead of /usr/lib<qual>/ (e.g., /lib32/ and /lib64/) to support the multiarch library.

Table 1. The multiarch library path options
Classic path i386 multiarch path amd64 multiarch path

/lib/

/lib/i386-linux-gnu/

/lib/x86_64-linux-gnu/

/usr/lib/

/usr/lib/i386-linux-gnu/

/usr/lib/x86_64-linux-gnu/

For Autotools based packages under the debhelper package (compat>=9), this path setting is automatically taken care by the dh_auto_configure command.

For other packages with non-supported build systems, you need to manually adjust the install path as follows.

  • If ./configure is used in the part of override_dh_auto_configure target in debian/rules, make sure to replace it with “dh_auto_configure --” while re-targeting the install path from /usr/lib/ to /usr/lib/$(DEB_HOST_MULTIARCH)/.

  • Replace all occurrences of /usr/lib/ with /usr/lib/*/ in debian/foo.install files.

All files installed simultaneously as the multiarch package to the same file path should have exactly the same file content. You must be careful on differences generated by the data byte order and by the compression algorithm.

Note
The --libexecdir option of the ./configure command specifies the default path to install executable programs run by other programs rather than by users. Its Autotools default is /usr/libexec/ but its Debian non-multi-arch default is /usr/lib/. If such executables are a part of a "Multi-arch: foreign" package, path such as /usr/lib/ or /usr/lib/packagename may be more desirable than /usr/lib/<triplet>/ which dh_auto_configure uses. The GNU Coding Standards: 7.2.5 Variables for Installation Directories has description for libexecdir as "The definition of libexecdir is the same for all packages, so you should install your data in a subdirectory thereof. Most packages install their data under $(libexecdir)/package-name/ …". (It is always good idea to follow GNU unless it conflicts with the Debian policy)

The shared library files in the default path /usr/lib/ and /usr/lib/<triplet>/ are loaded automatically.

For the shared library files in the other path, GCC option -l must be set by the pkg-config command to make them loaded properly.

The multiarch header file path

GCC includes both /usr/include/ and /usr/include/<triplet>/ by default on the multiarch Debian system.

If the header file is not in those paths, GCC option -I must be set by the pkg-config command to make "#include <foo.h>" work properly.

Table 2. The multiarch header file path options
Classic path i386 multiarch path amd64 multiarch path

/usr/include/

/usr/include/i386-linux-gnu/

/usr/include/x86_64-linux-gnu/

/usr/include/packagename/

/usr/include/i386-linux-gnu/packagename/

/usr/include/x86_64-linux-gnu/packagename/

/usr/lib/i386-linux-gnu/packagename/

/usr/lib/x86_64-linux-gnu/packagename/

The use if the /usr/lib/<triplet>/packagename/ path for the header files allows the upstream to use the same install script for the multiatch system with /usr/lib/<triplet> and the biarch system with /usr/lib<qual>/.
[This path is compliant to the FHS. Filesystem Hierarchy Standard: /usr/lib : Libraries for programming and packages states "Applications may use a single subdirectory under /usr/lib. If an application uses a subdirectory, all architecture-dependent data exclusively used by the application must be placed within that subdirectory."]

The use of the file path containing packagename enables to have more than 2 development libraries simultaneously installed on a system.

The multiarch *.pc file path

The pkg-config program is used to retrieve information about installed libraries in the system. It stores its configuration parameters in the *.pc file and is used for setting the -I and -l options for GCC.

Table 3. The *.pc file path options
Classic path i386 multiarch path amd64 multiarch path

/usr/lib/pkgconfig/

/usr/lib/i386-linux-gnu/pkgconfig/

/usr/lib/x86_64-linux-gnu/pkgconfig/

Library symbols

The symbols support in the dpkg introduced to Debian lenny (5.0, May 2009) helps us to manage the backward ABI compatibility of the library package with the same package name. The DEBIAN/symbols file in the binary package provides the minimal version associated to each symbol.

The oversimplified method for the library packaging is as follows.

  • Extract the old DEBIAN/symbols file of the immediate previous binary package with the “dpkg-deb -e” command.

    • Alternatively, the mc command may be used to extract the DEBIAN/symbols file.

  • Copy it to the debian/binarypackage.symbols file.

    • If this is the first package, use an empty content file instead.

  • Build the binary package.

    • If the dpkg-gensymbols command warns some new symbols:

      • Extract the updated DEBIAN/symbols file with the “dpkg-deb -e” command.

      • Trim the Debian revision such as -1 in it.

      • Copy it to the debian/binarypackage.symbols file.

      • Re-build the binary package.

    • If the dpkg-gensymbols command does not warn new symbols:

      • You are done with the library packaging.

For the details, you should read the following primary references.

  • 8.6.3 The symbols system of the “Debian Policy Manual”

  • dh_makeshlibs(1)

  • dpkg-gensymbols(1)

  • dpkg-shlibdeps(1)

  • deb-symbols(5)

Yous should also check:

Tip
For C++ libraries and other cases where the tracking of the symbols is problematic, follow 8.6.4 The shlibs system of the “Debian Policy Manual”, instead. Please make sure to erase the empty debian/binarypackage.symbols file generated by the debmake command. For this case, the DEBIAN/shlibs file is used.

Compiler hardening

The compiler hardening support spreading for Debian jessie (8.0, TBA) demands us to pay extra attention for the packaging.

You should read the following references in detail.

The debmake command adds template comments to the debian/rules file as needed for DEB_BUILD_MAINT_OPTIONS, DEB_CFLAGS_MAINT_APPEND, and DEB_LDFLAGS_MAINT_APPEND (see [simple] and dpkg-buildflags(1)).

Bug report

The reportbug command used for the bug report of binarypackage can be customized by the files in usr/share/bug/binarypackage/.

The dh_bugfiles command installs these files from the template files in the debian/ directory.

  • debian/binarypackage.bug-controlusr/share/bug/binarypackage/control

    • This file contains some directions such as redirecting the bug report to another package.

  • debian/binarypackage.bug-presubjusr/share/bug/binarypackage/presubj

    • This file is displayed to the user by the reportbug command.

  • debian/binarypackage.bug-scriptusr/share/bug/binarypackage or usr/share/bug/binarypackage/script

    • The reportbug command runs this script to generate a template file for the bug report.

debconf

The debconf package enables us to configure packages during their installation in 2 main ways:

  • non-interactively from the debian-installer pre-seeding.

  • interactively from the menu interface (dialog, gnome, kde, …)

    • the package installation: invoked by the dpkg command

    • the installed package: invoked by the dpkg-reconfigure command

All user interactions for the package installation must be handled by this debconf system using the following files.

  • debian/binarypackage.cofig

    • This is the debconf config script used for asking any questions necessary to configure the package.

  • debian/binarypackage.template

    • This is the debconf templates file used for asking any questions necessary to configure the package.

  • package configuration scripts

    • debian/binarypackage.preinst

    • debian/binarypackage.prerm

    • debian/binarypackage.postinst

    • debian/binarypackage.postrm

See dh_installdebconf(1), debconf(7), debconf-devel(7) and 3.9.1 Prompting in maintainer scripts of the “Debian Policy Manual”.

Continuous integration

DEP-8 defines the debian/tests/control file as the RFC822-style test metadata file for the continuous integration (CI) of the Debian package.

It is used after building the binary packages from the source package containing this debian/tests/control file. When the adt-run command provided by the autopkgtest package is run, the generated binary packages are installed and tested in the virtual environment according to this file.

See documents in the /usr/share/doc/autopkgtest/ directory and 3. autopkgtest: Automatic testing for packages of the “Ubuntu Packaging Guide”.

There are several other CI tools on Debian for you to explore.

  • The debci package: CI platform on the top of the autopkgtest package

  • The jenkins package: generic CI platform

Options

Here are some notable options for the debmake command.

Shortcut options (-a, -i)

The debmake command offers 2 shortcut options.

  • -a : open the upstream tarball

  • -i : execute script to build the binary package

The example in the above [simple] can be done simply as follows.

 $ debmake -a package-1.0.tar.gz -i debuild
Tip
URL such as “http://www.example.org/DL/package-1.0.tar.gz” may be used for the -a option.
Tip
URL such as “http://arm.koji.fedoraproject.org/packages/ibus/1.5.7/3.fc21/src/ibus-1.5.7-3.fc21.src.rpm” may be used for the -a option, too.

Upstream snapshot (-d, -t)

The upstream snapshot from the upstream source tree in VCS can be made with the -d option if the upstream supports the “make dist” equivalence.

 $ cd /path/to/upstream-vcs
 $ debmake -d -i debuild

Alternatively, the same can be made with the -t option if the upstream tarball can be made with the tar command.

 $ cd /path/to/upstream-vcs
 $ debmake -p package -t -i debuild

Unless you provide the upstream version with the -u option or with the debian/changelog file, a snapshot upstream version is generated in the 0~%y%m%d%H%M format, e.g., 0~1403012359, from the UTC date and time.

If the upstream VCS is hosted in the package/ directory instead of the upstream-vcs/ directory, the “-p package” can be skipped.

If the upstream source tree in the VCS contains the debian/* files, the debmake command with either the -d option or the -t option combined with the -i option automates making of the non-native Debian packages from the VCS snapshot while using these debian/* files.

 $ cp -r /path/to/package-0~1403012359/debian/. /path/to/upstream-vcs/debian
 $ dch
   ... update debian/changelog
 $ git add -A .; git commit -m "vcs with debian/*"
 $ debmake -t -p package -i debuild

This Debian non-native binary package building scheme using the “debmake -t -i debuild” command may be considered as the quasi-native Debian package scheme since the packaging situation resembles the Debian native binary package building case using the debuild command without the upstream tarball.

Use of the non-native Debian package helps to ease communication with the downstream distros such as Ubuntu for bug fixes etc.

Python module

You can generate a functioning single binary Debian package with a reasonable package description directly from the Python module package offered as a tarball pythonmodule-1.0.tar.gz. The -b option specifying the package type python and the -s option to copy the package description from the upstream package need to be specified.

 $ debmake -s -b':python' -a pythonmodule-1.0.tar.gz -i debuild

For other interpreted languages with the -b option support, specify the pertinent type for the -b option.

For interpreted languages without the -b option support, specify the script type instead and add the interpreter package as the dependency of the resulting binary package by adjusting the debian/control file.

debmake -cc

The debmake command with the -cc option can make a summary of the copyright and license for the entire source tree to the standard output.

 $ tar -xvzf package-1.0.tar.gz
 $ cd package-1.0
 $ debmake -cc | less

With -c, this provides shorter report.

debmake -k

When updating a package for the new upstream release, the debmake command can verify the content of the existing debian/copyright file against the copyright and license situation of the entire updated source tree.

 $ cd package-vcs
 $ gbp import-orig --uscan --pristine-tar
 ... update source with the new upstream release
 $ debmake -k | less

The “debmake -k” command parses the debian/copyright file from the top to the bottom and compare the license of all the non-binary files in the current package with the license described in the last matching file pattern entry of the debian/copyright file.

When editing the auto-generated debian/copyright file, please make sure to keep the generic file patterns at the top of the list.

Tip
For all new upstream releases, run the “debmake -k” command to ensure that the debian/copyright file is current.

debmake -j

The generation of the functioning multi binary package always requires extra manual works than that of the functioning single binary package. The test build of the source package is essential part of it.

For example, let’s package the same package-1.0.tar.gz (see [simple]) into a multi binary package. At the line invoking the debmake command, let’s invoke it with the -j option instead for the test building and the report generation.

 $ debmake -j
Note
The -j option for debmake invokes dpkg-depcheck(1) to run debian/rules under strace(1) to obtain library dependencies. Unfortunately, this is very slow. If you know the library package dependencies from other sources such as the SPEC file in the source, you may just run "debmake …" without -j and “debian/rules install” to check the install paths of the generated files.
  • Check the last lines of package.build-dep.log to judge build dependencies for Build-Depends. (You do not need to list packages used by debhelper, perl, or fakeroot explicitly in Build-Depends. This technique is useful for the generation of the single binary package, too.)

  • Check the contents of package.install.log to identify the install paths for files to decide how you split them into multiple packages.

 $ rm -rf package-1.0
 $ tar -xvzf package-1.0.tar.gz
 $ cd package-1.0
 $ debmake -b"package1:type1, ..."
  • Update debian/control and debian/binarypackage.install files using the above information.

  • Update other debian/* files as needed.

 $ debuild
  • Each binarypackage_version-revision_arch.deb has files specified by the debian/binarypackage.install file.

debmake -x

The amount of template files generated by the debmake command depends on the -x[01234] option.

  • See [emptypkg] for the cherry-picking of the template files.

Note
None of the existing configuration files are modified by the debmake command.

debmake -T

The debmake command invoked with the -T option additionally prints the verbose tutorial comment lines. The lines marked with ### in the template files are part of the verbose tutorial comment lines.

Tips

Here are some notable tips around the Debian packaging.

debdiff

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.

dget

You can download the set of files for the Debian source package with the dget command.

$ dget http://www.example.org/path/to/package_version-rev.dsc

debc

You should install generated packages with the debc command to test it locally.

$ debc package_version-rev_arch.changes

piuparts

You should install generated packages with the piuparts command to test it automatically.

$ sudo piuparts package_version-rev_arch.changes
Note
This is very slow proess with the remote APT package repository access.

debsign

After completing the test of the package, you can sign it with the debsign command.

$ debsign package_version-rev_arch.changes

dput

After signing the package with the debsign command, you can upload the set of files for the Debian source and binary package with the dput command.

$ dput package_version-rev_arch.changes

bts

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 Debian Bug Tracking System.

$ bts severity 123123 wishlist , tags -1 pending

git-buildpackage

The git-buildpackage package offers many commands to automate packaging activities using the git repository.

  • git-import-dsc: import the previous Debian source package to the git repository.

  • git-import-orig: import the new upstream tar to the git repository.

  • git-dch: generate the Debian changelog from the git commit messages.

  • git-buildpackage: build the Debian binary package from the git repository. (alias gbp)

    • The --pristine-tar option for the git-buildpackage command enables to store the upstream tarball in the same git repository.

    • The --uscan option for the git-buildpackage command enables to download and commit the new upstream tarball into the git repository.

    • The “gbp pull” command updates 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 use of 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 use of the “gbp pq” command provides the equivalent functionality of the patch set management without using dquilt and eases including upstream git repository changes by the cherry-picking.

    • The use of the “gbp dpm” command provides the more enhanced functionality than that of the ‘gbp pq’' command.

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

Package history

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.

$ git-import-dscs --debsnap --pristine-tar '<source-package>'

Upstream git repository

For the 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 git-import-orig command with the --upstream-vcs-tag option can create a nice packaging history by making a merge commit into 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, …)

chroot

The chroot for the clean package build environment can be created and managed using the tools described in [setup].
[The git-pbuilder style organization is deployed here. See https://wiki.debian.org/git-pbuilder . Be careful since many HOWTOs use different organization.]

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 the 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

    • /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 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 sid 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
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
If your old chroot 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
The chroot filesystem can be cloned simply by copying with “cp -a base-dist.cow base-customdist.cow”. The new chroot can be accessed as “gbp buildpackage --git-dist=customdist” and “DIST=customdist git-pbuilder …”.
Tip
When the orig.tar.gz file needs to be upload for the Debian revision other than 0 and 1 (e.g., for the 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
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.

New Debian revision

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

New upstream release

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 “tar -xvzf /path/to/foo_oldversion.debian.tar.gz” in the new extracted source.
[If a package foo is packaged in the old 1.0 format, this can be done by running “zcat /path/to/foo_oldversion.diff.gz|patch -p1” in the new extracted source, instead.]
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.

uupdate + tarball

You can update to the new upstream source with the uupdate command from the devscripts package. It requires to have the old Debian source package and the new upstream tarball.

 $ wget http://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

uscan

You can update to the new upstream source with the uscan command from the devscripts package. It requires to have the old Debian source package and the debian/watch file in it.

 $ cd foo-oldversion
 $ uscan
 ...
 $ while dquilt push; do dquilt refresh; done
 $ dch

gbp

You can update to the new upstream source with the “gbp import-orig --pristine-tar” command from the git-buildpackage package. It requires to have 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 the git repository, please also use --upstream-vcs-tag option for the gbp import-orig command.

gbp + uscan

You can update to the new upstream source with the “gbp import-orig --pristine-tar --uscan” command from the git-buildpackage package. It requires to have 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 the git repository, please also use --upstream-vcs-tag option for the gbp import-orig command.

Library transition

When you package a new library package version which affects other packages, you must file a transition bug report against the release.debian.org psuedo package using the reportbug command with the ben file and wait for the approval for its upload from the Release Team.

Release team has the transition tracker. See Transitions.

Caution
Please make sure to rename binary packages as [libnames].

3.0 source format

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.

  • If you need to recreate deleted template files for any reason, you can run debmake again in the same Debian package source tree. Then edit them appropriately.

  • If the package has not been updated to use the dh command for the debian/rules file, update it to use it (see [simplerules]). Update the debian/control file accordingly.

  • If you have a 1.0 source package with the foo.diff.gz file, you can update it to the newer “3.0 (quilt)” source format by creating debian/source/format with “3.0 (quilt)”. The rest of the debian/* files can just be copied. Import the big.diff file generated by the command “filterdiff -z -x /debian/ foo.diff.gz > big.diff” to your quilt system, if needed.
    [You can split big.diff into many small incremental patches using the splitdiff command.]

  • If it was packaged using another patch system such as dpatch, dbs, or cdbs with -p0, -p1, or -p2, convert it to the quilt command using the deb3 script in the quilt package.

  • If it was packaged with the dh command with the “--with quilt” option or with the dh_quilt_patch and dh_quilt_unpatch commands, remove these and make it use the newer “3.0 (quilt)” source format.

  • If you have a 1.0 source package without the foo.diff.gz file, you can update it to the newer “3.0 (native)” source format by creating debian/source/format with “3.0 (native)”. The rest of the debian/* files can just be copied.

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.

CDBS

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
“The CDBS magically does the job for me with less typing” nor “I don’t understand the new dh syntax” can’t be the 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 reasons. 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:

Build under UTF-8

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 to build the program under the C.UTF-8 locale.

LC_ALL := C.UTF-8
export LC_ALL

UTF-8 conversion

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.

Upload orig.tar.gz

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
On the other hand, the -sd option will force the exclusion of the original orig.tar.gz source.
Tip
Security uploads require to include the orig.tar.gz.

Skipped uploads

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.

Advanced packaging

Hints for the following can be found in the debhelper(7) manpage:

  • differences of the debhelper tool behavior under “compat <= 8”

  • building several binary packages with several different build conditions

    • making multiple copies of the upstream source

    • invoking multiple “dh_auto_configure -S …” commands in the override_dh_auto_configure target

    • invoking multiple “dh_auto_build -S …” commands in the override_dh_auto_build target

    • invoking multiple “dh_auto_install -S …” commands in the override_dh_auto_install target

  • building udeb packages with “Package-Type: udeb” in debian/control (see Package-Type)

  • excluding some packages for the bootstrapping (see also BuildProfileSpec)

    • adding the Build-Profiles fields in binary package stanzas in debian/control

    • building packages with the DEB_BUILD_PROFILES environment variable set to the pertinent profile name

Hints for the following can be found in the dpkg-source(1) manpage:

  • naming convention for the multiple upstream source tarballs

    • packagename_version.orig.tar.gz

    • packagename_version.orig-componentname.tar.gz

  • recording the Debian changes to the upstream binary file

    • dpkg-source --commit

Other distros

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 may be more focused on the feature enhancements and may be less eager for backward compatibilities etc. which are important aspect of the Debian packaging practice.

The leveraging of information from other distributions is an option to address above issues.

If the other distribution in interest is a Debian derivative one, it is trivial to reuse it.

If the other distribution in interest is a 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.

More Examples

There is an old Latin saying: “fabricando fit faber” (“practice makes perfect”).

It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages. This chapter provides you with the many upstream cases for your practice.

This should also serve as introductory examples for many programing topics.

  • Programing in the POSIX shell, Python3, and C.

  • Method to create the desktop GUI program launcher with the icon graphics.

  • Conversion of command from CLI to GUI.

  • Conversion of program to use gettext for internationalization and localization: POSIX shell, Python3, and C sources.

  • Overview of many build systems: Makefile, Python distutils, Autotools, and CMake.

Please note Debian takes few things serious.

  • Free software (a.k.a. Libre software)

  • Stability and security of OS.

  • Universal OS realized via:

    • free choice for upstream sources,

    • free choice of CPU architectures, and

    • free choice of UI languages.

The typical packaging example presented in [simple] is the prerequisite for this chapter.

Some details are intentionally left vague. Please try to read the pertinent documentation and practice yourself to find them out. You can cheat this by following the instruction in [details].

Tip
The best source of example is the Debian archive itself. Please use Debian Code Search to find pertinent examples

Cherry-pick templates

Here is an example of creating a simple Debian package from a zero content source on an empty directory.

This is a good platform to get all the template files without making mess in the upstream source tree you are working on.

Let’s assume this empty directory to be debhello-0.1.

 $ mkdir debhello-0.1
 $ tree
.
└── debhello-0.1

1 directory, 0 files

Let’s generate the maximum amount of template files by specifying the -x4 option.

Let’s also use the “-p debhello -t -u 0.1 -r 1” options to make missing upstream tarball.

 $ debmake -t -p debhello -u 0.1 -r 1 -x4
I: set parameters
 ...
I: debmake -x "4" ...
I: creating => debian/control
I: creating => debian/copyright
I: substituting => /usr/share/debmake/extra0/changelog
 ...
I: substituting => /usr/share/debmake/extra4/LGPL-3.0+
I: creating => debian/license-examples/LGPL-3.0+
I: substituting => /usr/share/debmake/extra4/Artistic-1.0
I: creating => debian/license-examples/Artistic-1.0
I: substituting => /usr/share/debmake/extra4/BSD-3-Clause
I: creating => debian/license-examples/BSD-3-Clause
I: $ wrap-and-sort

Let’s inspect generated template files.

 $ cd ..
 $ tree
.
├── debhello-0.1
│   └── debian
│       ├── README.Debian
│       ├── changelog
│       ├── clean
│       ├── compat
│       ├── control
│       ├── copyright
│       ├── debhello.bug-control.ex
│       ├── debhello.bug-presubj.ex
│       ├── debhello.bug-script.ex
│       ├── debhello.conffiles.ex
 ...
│       ├── source.lintian-overrides.ex
│       └── watch
├── debhello-0.1.tar.gz
└── debhello_0.1.orig.tar.gz -> debhello-0.1.tar.gz

5 directories, 52 files

Now you can copy any of these generated template files in the debhello-0.1/debian/ directory to your package as needed while renaming them as needed.

Tip
The generated template files can be made more verbose ones by invoking the debmake command with the -T option (tutorial mode).

No Makefile (shell, CLI)

Here is an example of creating a simple Debian package from a POSIX shell CLI program without its build system.

Let’s assume this upstream tarball to be debhello-0.2.tar.gz.

This type of source has no automated means and files must be installed manually.

 $ tar -xzmf debhello-0.2.tar.gz
 $ cd debhello-0.2
 $ sudo cp scripts/hello /bin/hello
 ...

Let’s get the source and make the Debian package.

Download debhello-0.2.tar.gz
 $ wget http://www.example.org/download/debhello-0.2.tar.gz
 ...
 $ tar -xzmf debhello-0.2.tar.gz
 $ tree
.
├── debhello-0.2
│   ├── LICENSE
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── man
│   │   └── hello.1
│   └── scripts
│       └── hello
└── debhello-0.2.tar.gz

4 directories, 6 files

Here, the POSIX shell script hello is a very simple one.

hello (v=0.2)
 $ cat debhello-0.2/scripts/hello
#!/bin/sh -e
echo "Hello from the shell!"
echo ""
echo -n "Type Enter to exit this program: "
read X

Here, the hello.desktop supports Desktop Entry Specification.

hello.desktop (v=0.2)
 $ cat debhello-0.2/data/hello.desktop
[Desktop Entry]
Name=Hello
Name[fr]=Bonjour
Comment=Greetings
Comment[fr]=Salutations
Type=Application
Keywords=hello
Exec=hello
Terminal=true
Icon=hello.png
Categories=Utility;

Here, the hello.png is the icon graphics file.

Let’s package this with the debmake command. Here, the -b':sh' option is used to specify the generated binary package is a shell script.

 $ cd debhello-0.2
 $ debmake -b':sh'
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="0.2", rev="1"
I: *** start packaging in "debhello-0.2". ***
I: provide debhello_0.2.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-0.2.tar.gz debhello_0.2.orig.tar.gz
I: pwd = "/path/to/debhello-0.2"
I: parse binary package settings: :sh
I: binary package=debhello Type=script / Arch=all M-A=foreign
...

Let’s inspect notable template files generated.

The source tree after the basic debmake execution. (v=0.2)
 $ cd ..
 $ tree
.
├── debhello-0.2
│   ├── LICENSE
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── debian
│   │   ├── README.Debian
│   │   ├── changelog
│   │   ├── compat
│   │   ├── control
│   │   ├── copyright
│   │   ├── patches
│   │   │   └── series
│   │   ├── rules
│   │   ├── source
│   │   │   ├── format
│   │   │   └── local-options
│   │   └── watch
│   ├── man
│   │   └── hello.1
│   └── scripts
│       └── hello
├── debhello-0.2.tar.gz
└── debhello_0.2.orig.tar.gz -> debhello-0.2.tar.gz

7 directories, 17 files
debian/rules (template file, v=0.2):
 $ cat debhello-0.2/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1

%:
        dh $@

This is essentially the standard debian/rules file with the dh command. Since this is the script package, this template debian/rules file has no build flag related contents.

debian/control (template file, v=0.2):
 $ cat debhello-0.2/debian/control
Source: debhello
Section: unknown
Priority: extra
Maintainer: "Firstname Lastname" <email.address@example.org>
Build-Depends: debhelper (>=9)
Standards-Version: 3.9.6
Homepage: <insert the upstream URL, if relevant>

Package: debhello
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}
Description: auto-generated package by debmake
 This Debian binary package was auto-generated by the
 debmake(1) command provided by the debmake package.

Since this is the shell script package, the debmake command sets “Architecture: all” and “Multi-Arch: foreign”. Also, it sets required substvar parameters as “Depends: ${misc:Depends}”. These are explained in [basics].

Since this upstream source lacks the upstream Makefile, that functionality needs to be provided by the maintainer. This upstream contains only a script file and data files and no C source files, the build process can be skipped but the install process needs to be implemented. For this case, this is achieved cleanly by adding the debian/install and debian/manpages files without complicating the debian/rules file.

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=0.2):
 $ vim debhello-0.2/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-0.2/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1

%:
        dh $@
debian/control (maintainer version, v=0.2):
 $ vim debhello-0.2/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-0.2/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: debhelper (>=9)
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/

Package: debhello
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}
Description: example package in the debmake-doc package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
debian/install (maintainer version, v=0.2):
 $ vim debhello-0.2/debian/install
 ... hack, hack, hack, ...
 $ cat debhello-0.2/debian/install
data/hello.desktop usr/share/applications
data/hello.png usr/share/pixmaps
scripts/hello usr/bin
debian/manpages (maintainer version, v=0.2):
 $ vim debhello-0.2/debian/manpages
 ... hack, hack, hack, ...
 $ cat debhello-0.2/debian/manpages
man/hello.1

There are several other template files under the debian/ directory. These also needs to be updated.

Template files under debian/. (v=0.2):
 $ tree debhello-0.2/debian
debhello-0.2/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── install
├── manpages
├── patches
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 12 files

You can create a non-native Debian package using the debuild command (or its equivalents) in this source tree. The command output is very verbose and explains what it does as follows.

 $ cd debhello-0.2
 $ debuild
 dpkg-buildpackage -rfakeroot -D -us -uc -i -i
 ...
 fakeroot debian/rules clean
dh clean
 ...
 debian/rules build
dh build
   dh_testdir
   dh_auto_configure
   dh_auto_build
   dh_auto_test
 fakeroot debian/rules binary
dh binary
   dh_testroot
   dh_prep
        rm -f debian/debhello.substvars
 ...
 fakeroot debian/rules binary
dh binary
 ...
Finished running lintian.

Let’s inspect the result.

The generated files of debhello version 0.2 by the debuild command:
 $ cd ..
 $ tree -FL 1
.
├── debhello-0.2/
├── debhello-0.2.tar.gz
├── debhello_0.2-1.debian.tar.xz
├── debhello_0.2-1.dsc
├── debhello_0.2-1_all.deb
├── debhello_0.2-1_amd64.build
├── debhello_0.2-1_amd64.changes
└── debhello_0.2.orig.tar.gz -> debhello-0.2.tar.gz

1 directory, 7 files

You see all the generated files.

  • The debhello_0.2.orig.tar.gz is a symlink to the upstream tarball.

  • The debhello_0.2-1.debian.tar.xz contains the maintainer generated contents.

  • The debhello_0.2-1.dsc is the meta data file for the Debian source package.

  • The debhello_0.2-1_amd64.deb is the Debian binary package.

  • The debhello_0.2-1_amd64.changes is the meta data file for the Debian binary package.

The debhello_0.2-1.debian.tar.xz contains the Debian changes to the upstream source as follows.

The compressed archive contents of debhello_0.2-1.debian.tar.xz:
 $ tar -tzf debhello-0.2.tar.gz
debhello-0.2/
debhello-0.2/LICENSE
debhello-0.2/man/
debhello-0.2/man/hello.1
debhello-0.2/data/
debhello-0.2/data/hello.desktop
debhello-0.2/data/hello.png
debhello-0.2/scripts/
debhello-0.2/scripts/hello
 $ tar --xz -tf debhello_0.2-1.debian.tar.xz
debian/
debian/patches/
debian/patches/series
debian/control
debian/changelog
debian/manpages
debian/rules
debian/source/
debian/source/format
debian/README.Debian
debian/compat
debian/install
debian/watch
debian/copyright

The debhello_0.2-1_amd64.deb contains the files to be installed as follows.

The binary package contents of debhello_0.2-1_amd64.deb:
 $ dpkg -c debhello_0.2-1_all.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/bin/
-rwxr-xr-x root/root ...  ./usr/bin/hello
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/pixmaps/
-rw-r--r-- root/root ...  ./usr/share/pixmaps/hello.png
drwxr-xr-x root/root ...  ./usr/share/applications/
-rw-r--r-- root/root ...  ./usr/share/applications/hello.desktop
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/debhello/
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/changelog.Debian.gz
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/debhello/copyright
drwxr-xr-x root/root ...  ./usr/share/man/
drwxr-xr-x root/root ...  ./usr/share/man/man1/
-rw-r--r-- root/root ...  ./usr/share/man/man1/hello.1.gz

Makefile (shell, CLI)

Here is an example of creating a simple Debian package from a POSIX shell CLI program using the Makefile as its build system.

Let’s assume its upstream tarball to be debhello-1.0.tar.gz.

This type of source is meant to be installed as a non-system file as:

 $ tar -xzmf debhello-1.0.tar.gz
 $ cd debhello-1.0
 $ make install

Debian packaging requires to change this “make install” process to install files to the target system image location instead of the normal location under /usr/local.

Let’s get the source and make the Debian package.

Download debhello-1.0.tar.gz
 $ wget http://www.example.org/download/debhello-1.0.tar.gz
 ...
 $ tar -xzmf debhello-1.0.tar.gz
 $ tree
.
├── debhello-1.0
│   ├── LICENSE
│   ├── Makefile
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── man
│   │   └── hello.1
│   └── scripts
│       └── hello
└── debhello-1.0.tar.gz

4 directories, 7 files

Here, the Makefile uses $(DESTDIR) and $(prefix) properly. All other files are the same as [nomakefile] and most of the packaging activities are the same.

Makefile (v=1.0)
 $ cat debhello-1.0/Makefile
prefix = /usr/local

all:
        : # do nothing

install:
        install -D scripts/hello \
                $(DESTDIR)$(prefix)/bin/hello
        install -m 644 -D data/hello.desktop \
                $(DESTDIR)$(prefix)/share/applications/hello.desktop
        install -m 644 -D data/hello.png \
                $(DESTDIR)$(prefix)/share/pixmaps/hello.png
        install -m 644 -D man/hello.1 \
                $(DESTDIR)$(prefix)/share/man/man1/hello.1

clean:
        : # do nothing

distclean: clean

uninstall:
        -rm -f $(DESTDIR)$(prefix)/bin/hello
        -rm -f $(DESTDIR)$(prefix)/share/applications/hello.desktop
        -rm -f $(DESTDIR)$(prefix)/share/pixmaps/hello.png
        -rm -f $(DESTDIR)$(prefix)/share/man/man1/hello.1

.PHONY: all install clean distclean uninstall

Let’s package this with the debmake command. Here, the -b':sh' option is used to specify the generated binary package is a shell script.

 $ cd debhello-1.0
 $ debmake -b':sh'
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.0", rev="1"
I: *** start packaging in "debhello-1.0". ***
I: provide debhello_1.0.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.0.tar.gz debhello_1.0.orig.tar.gz
I: pwd = "/path/to/debhello-1.0"
I: parse binary package settings: :sh
I: binary package=debhello Type=script / Arch=all M-A=foreign
...

Let’s inspect notable template files generated.

debian/rules (template file, v=1.0):
 $ cat debhello-1.0/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1

%:
        dh $@

#override_dh_auto_install:
#       dh_auto_install -- prefix=/usr

#override_dh_install:
#       dh_install --list-missing -X.pyc -X.pyo

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=1.0):
 $ vim debhello-1.0/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-1.0/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1

%:
        dh $@

override_dh_auto_install:
        dh_auto_install -- prefix=/usr

Since this upstream source has the proper upstream Makefile, there are no needs to create debian/install and debian/manpages files.

The debian/control file is exactly the same as the one in [nomakefile].

There are several other template files under the debian/ directory. These also needs to be updated.

Template files under debian/. (v=1.0):
 $ tree debhello-1.0/debian
debhello-1.0/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── patches
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 10 files

The rest of the packaging activities are practically the same as the one in [nomakefile].

setup.py (Python3, CLI)

Here is an example of creating a simple Debian package from a Python3 CLI program using the setup.py as its build system.

Let’s assume its upstream tarball to be debhello-1.1.tar.gz.

This type of source is meant to be installed as a non-system file as:

 $ tar -xzmf debhello-1.1.tar.gz
 $ cd debhello-1.1
 $ python3 setup.py install

Debian packaging requires to change the last line to “python3 setup.py install --install-layout=deb” to install files to the target system image location. This issue is automatically addressed when using the dh command for the Debian packaging.

Let’s get the source and make the Debian package.

Download debhello-1.1.tar.gz
 $ wget http://www.example.org/download/debhello-1.1.tar.gz
 ...
 $ tar -xzmf debhello-1.1.tar.gz
 $ tree
.
├── debhello-1.1
│   ├── LICENSE
│   ├── MANIFEST.in
│   ├── PKG-INFO
│   ├── hello_py
│   │   └── __init__.py
│   ├── scripts
│   │   └── hello
│   └── setup.py
└── debhello-1.1.tar.gz

3 directories, 7 files

Here, the hello script and its associated hello_py module are as follows.

hello (v=1.1)
 $ cat debhello-1.1/scripts/hello
#!/usr/bin/python3
import hello_py

if __name__ == '__main__':
    hello_py.main()
hello_py/__init__.py (v=1.1)
 $ cat debhello-1.1/hello_py/__init__.py
#!/usr/bin/python3
def main():
    print('Hello Python3!')
    input("Press Enter to continue...")
    return

if __name__ == '__main__':
    main()

These are packaged using the Python distutils with the setup.py and MANIFEST.in files.

setup.py (v=1.1)
 $ cat debhello-1.1/setup.py
#!/usr/bin/python3
# vi:se ts=4 sts=4 et ai:
from distutils.core import setup

setup(name='debhello',
    version='4.0',
    description='Hello Python',
    long_description='Hello Python program.',
    author='Osamu Aoki',
    author_email='osamu@debian.org',
    url='http://people.debian.org/~osamu/',
    packages=['hello_py'],
    package_dir={'hello_py': 'hello_py'},
    scripts=['scripts/hello'],
    classifiers = ['Development Status :: 3 - Alpha',
        'Environment :: Console',
        'Intended Audience :: Developers',
        'License :: OSI Approved :: MIT License',
        'Natural Language :: English',
        'Operating System :: POSIX :: Linux',
        'Programming Language :: Python :: 3',
        'Topic :: Utilities',
    ],
    platforms   = 'POSIX',
    license     = 'MIT License'
)
MANIFEST.in (v=1.1)
 $ cat debhello-1.1/MANIFEST.in
include MANIFEST.in
include LICENSE
Tip
Many modern Python packages are distributed using setuptools. Since setuptools is an enhanced alternative to distutils, this example is useful for them.

Let’s package this with the debmake command. Here, the -b':py3' option is used to specify the generated binary package contain Python3 script and module files.

 $ cd debhello-1.1
 $ debmake -b':py3'
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.1", rev="1"
I: *** start packaging in "debhello-1.1". ***
I: provide debhello_1.1.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.1.tar.gz debhello_1.1.orig.tar.gz
I: pwd = "/path/to/debhello-1.1"
I: parse binary package settings: :py3
I: binary package=debhello Type=python3 / Arch=all M-A=foreign
...

Let’s inspect notable template files generated.

debian/rules (template file, v=1.1):
 $ cat debhello-1.1/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1

%:
        dh $@ --with python3 --buildsystem=pybuild

This is essentially the standard debian/rules file with the dh command.

The use of “--with python3” option invokes dh_python3 to calculate Python dependencies, adds maintainer scripts to byte compile files, etc. See dh_python3(1).

The use of “--buildsystem=pybuild” option invokes various build systems for requested Python versions in order to build modules and extensions. See pybuild(1).

debian/control (template file, v=1.1):
 $ cat debhello-1.1/debian/control
Source: debhello
Section: unknown
Priority: extra
Maintainer: "Firstname Lastname" <email.address@example.org>
Build-Depends: debhelper (>=9), dh-python, python3-all
Standards-Version: 3.9.6
Homepage: <insert the upstream URL, if relevant>
X-Python3-Version: >= 3.2

Package: debhello
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}, ${python3:Depends}
Description: auto-generated package by debmake
 This Debian binary package was auto-generated by the
 debmake(1) command provided by the debmake package.

Since this is the Python3 package, the debmake command sets “Architecture: all” and “Multi-Arch: foreign”. Also, it sets required substvar parameters as “Depends: ${python3:Depends}, ${misc:Depends}”. These are explained in [basics].

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=1.1):
 $ vim debhello-1.1/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-1.1/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1

%:
        dh $@ --with python3 --buildsystem=pybuild
debian/control (maintainer version, v=1.1):
 $ vim debhello-1.1/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-1.1/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: debhelper (>=9), dh-python, python3-all
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/
X-Python3-Version: >= 3.2

Package: debhello
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}, ${python3:Depends}
Description: example package in the debmake-doc package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.

The hello command does not come with the upstream provided manpage, let’s add it as the maintainer.

debian/manpages etc. (maintainer version, v=1.1):
 $ vim debhello-1.1/debian/hello.1
 ... hack, hack, hack, ...
 $ vim debhello-1.1/debian/manpages
 ... hack, hack, hack, ...
 $ cat debhello-1.1/debian/manpages
debian/hello.1

There are several other template files under the debian/ directory. These also needs to be updated.

The rest of the packaging activities are practically the same as the one in [makefile-sh].

Template files under debian/. (v=1.1):
 $ tree debhello-1.1/debian
debhello-1.1/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── hello.1
├── manpages
├── patches
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 12 files

Here is the generated dependency list of binary packages.

The generated dependency list of binary packages (v=1.1):
 $ dpkg -f debhello_1.1-1_all.deb pre-depends depends recommends conflics bre...
Depends: python3, python3:any (>= 3.3.2-2~)

Makefile (shell, GUI)

Here is an example of creating a simple Debian package from a POSIX shell GUI program using the Makefile as its build system.

This upstream is based in [makefile-sh] with enhanced GUI support.

Let’s assume its upstream tarball to be debhello-1.2.tar.gz.

Let’s get the source and make the Debian package.

Download debhello-1.2.tar.gz
 $ wget http://www.example.org/download/debhello-1.2.tar.gz
 ...
 $ tar -xzmf debhello-1.2.tar.gz
 $ tree
.
├── debhello-1.2
│   ├── LICENSE
│   ├── Makefile
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── man
│   │   └── hello.1
│   └── scripts
│       └── hello
└── debhello-1.2.tar.gz

4 directories, 7 files

Here, the hello has been re-written to use the zenity command to make this a GTK+ GUI program.

hello (v=1.2)
 $ cat debhello-1.2/scripts/hello
#!/bin/sh -e
zenity --info --title "hello" --text "Hello from the shell!"

Here, the desktop file is updated to be Terminal=false as a GUI program.

hello.desktop (v=1.2)
 $ cat debhello-1.2/data/hello.desktop
[Desktop Entry]
Name=Hello
Name[fr]=Bonjour
Comment=Greetings
Comment[fr]=Salutations
Type=Application
Keywords=hello
Exec=hello
Terminal=false
Icon=hello.png
Categories=Utility;

All other files are the same as [makefile-sh].

Let’s package this with the debmake command. Here, the -b':sh' option is used to specify the generated binary package is a shell script.

 $ cd debhello-1.2
 $ debmake -b':sh'
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.2", rev="1"
I: *** start packaging in "debhello-1.2". ***
I: provide debhello_1.2.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.2.tar.gz debhello_1.2.orig.tar.gz
I: pwd = "/path/to/debhello-1.2"
I: parse binary package settings: :sh
I: binary package=debhello Type=script / Arch=all M-A=foreign
...

Let’s inspect notable template files generated.

debian/control (template file, v=1.2):
 $ cat debhello-1.2/debian/control
Source: debhello
Section: unknown
Priority: extra
Maintainer: "Firstname Lastname" <email.address@example.org>
Build-Depends: debhelper (>=9)
Standards-Version: 3.9.6
Homepage: <insert the upstream URL, if relevant>

Package: debhello
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}
Description: auto-generated package by debmake
 This Debian binary package was auto-generated by the
 debmake(1) command provided by the debmake package.

Let’s make this Debian package better as the maintainer.

debian/control (maintainer version, v=1.2):
 $ vim debhello-1.2/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-1.2/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: debhelper (>=9)
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/

Package: debhello
Architecture: all
Multi-Arch: foreign
Depends: zenity, ${misc:Depends}
Description: example package in the debmake-doc package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.

Please note manually added zenity.

The debian/rules file is exactly the same as the one in [makefile-sh].

There are several other template files under the debian/ directory. These also needs to be updated.

Template files under debian/. (v=1.2):
 $ tree debhello-1.2/debian
debhello-1.2/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── patches
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 10 files

The rest of the packaging activities are practically the same as the one in [makefile-sh].

Here is the generated dependency list of binary packages.

The generated dependency list of binary packages (v=1.2):
 $ dpkg -f debhello_1.2-1_all.deb pre-depends depends recommends conflics bre...
Depends: zenity

setup.py (Python3, GUI)

Here is an example of creating a simple Debian package from a Python3 GUI program using the setup.py as its build system.

This upstream is based in [setup-py] with enhanced GUI, desktop icon, and manpage supports.

Let’s assume this upstream tarball to be debhello-1.3.tar.gz.

Let’s get the source and make the Debian package.

Download debhello-1.3.tar.gz
 $ wget http://www.example.org/download/debhello-1.3.tar.gz
 ...
 $ tar -xzmf debhello-1.3.tar.gz
 $ tree
.
├── debhello-1.3
│   ├── LICENSE
│   ├── MANIFEST.in
│   ├── PKG-INFO
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── hello_py
│   │   └── __init__.py
│   ├── man
│   │   └── hello.1
│   ├── scripts
│   │   └── hello
│   └── setup.py
└── debhello-1.3.tar.gz

5 directories, 10 files

Here are the upstream sources.

hello (v=1.3)
 $ cat debhello-1.3/scripts/hello
#!/usr/bin/python3
import hello_py

if __name__ == '__main__':
    hello_py.main()
hello_py/__init__.py (v=1.3)
 $ cat debhello-1.3/hello_py/__init__.py
#!/usr/bin/python3
from gi.repository import Gtk

class TopWindow(Gtk.Window):

    def __init__(self):
        Gtk.Window.__init__(self)
        self.title = "Hello World!"
        self.counter = 0
        self.border_width = 10
        self.set_default_size(400, 100)
        self.set_position(Gtk.WindowPosition.CENTER)
        self.button = Gtk.Button(label="Click me!")
        self.button.connect("clicked", self.on_button_clicked)
        self.add(self.button)
        self.connect("delete-event", self.on_window_destroy)

    def on_window_destroy(self, *args):
        Gtk.main_quit(*args)

    def on_button_clicked(self, widget):
        self.counter += 1
        widget.set_label("Hello, World!\nClick count = %i" % self.counter)

def main():
    window = TopWindow()
    window.show_all()
    Gtk.main()

if __name__ == '__main__':
    main()
setup.py (v=1.3)
 $ cat debhello-1.3/setup.py
#!/usr/bin/python3
# vi:se ts=4 sts=4 et ai:
from distutils.core import setup

setup(name='debhello',
    version='4.1',
    description='Hello Python',
    long_description='Hello Python program.',
    author='Osamu Aoki',
    author_email='osamu@debian.org',
    url='http://people.debian.org/~osamu/',
    packages=['hello_py'],
    package_dir={'hello_py': 'hello_py'},
    scripts=['scripts/hello'],
    data_files=[
        ('share/applications', ['data/hello.desktop']),
        ('share/pixmaps', ['data/hello.png']),
        ('share/man/man1', ['man/hello.1']),
    ],
    classifiers = ['Development Status :: 3 - Alpha',
        'Environment :: Console',
        'Intended Audience :: Developers',
        'License :: OSI Approved :: MIT License',
        'Natural Language :: English',
        'Operating System :: POSIX :: Linux',
        'Programming Language :: Python :: 3',
        'Topic :: Utilities',
    ],
    platforms   = 'POSIX',
    license     = 'MIT License'
)
MANIFEST.in (v=1.3)
 $ cat debhello-1.3/MANIFEST.in
include MANIFEST.in
include LICENSE
include data/hello.deskto
include data/hello.png
include man/hello.1

Let’s package this with the debmake command. Here, the -b':py3' option is used to specify the generated binary package contain Python3 script and module files.

 $ cd debhello-1.3
 $ debmake -b':py3'
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.3", rev="1"
I: *** start packaging in "debhello-1.3". ***
I: provide debhello_1.3.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.3.tar.gz debhello_1.3.orig.tar.gz
I: pwd = "/path/to/debhello-1.3"
I: parse binary package settings: :py3
I: binary package=debhello Type=python3 / Arch=all M-A=foreign
...

The result is practically the same as [setup-py].

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=1.3):
 $ vim debhello-1.3/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-1.3/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1

%:
        dh $@ --with python3 --buildsystem=pybuild
debian/control (maintainer version, v=1.3):
 $ vim debhello-1.3/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-1.3/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: debhelper (>=9), dh-python, python3-all
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/
X-Python3-Version: >= 3.2

Package: debhello
Architecture: all
Multi-Arch: foreign
Depends: gir1.2-gtk-3.0, python3-gi, ${misc:Depends}, ${python3:Depends}
Description: example package in the debmake-doc package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.

Please note manually added python3-gi and gir1.2-gtk-3.0.

Since this upstream source has manpage and other files with matching entries in the setup.py file, there are no needs to create them and add debian/install and debian/manpages files which was required in [setup-py].

The rest of the packaging activities are practically the same as the one in [setup-py].

Here is the generated dependency list of binary packages.

The generated dependency list of binary packages (v=1.3):
 $ dpkg -f debhello_1.3-1_all.deb pre-depends depends recommends conflics bre...
Depends: gir1.2-gtk-3.0, python3-gi, python3, python3:any (>= 3.3.2-2~)

Makefile (single-binary)

Here is an example of creating a simple Debian package from a simple C source using the Makefile as its build system.

This is an enhanced upstream source example for [simple]. This comes with the manpage, the desktop file, and the desktop icon. This also links to an external library libm to be a more practical example.

Let’s assume this upstream tarball to be debhello-1.4.tar.gz.

This type of source is meant to be installed as a non-system file as:

 $ tar -xzmf debhello-1.4.tar.gz
 $ cd debhello-1.4
 $ make
 $ make install

Debian packaging requires to change this “make install” process to install files to the target system image location instead of the normal location under /usr/local.

Let’s get the source and make the Debian package.

Download debhello-1.4.tar.gz
 $ wget http://www.example.org/download/debhello-1.4.tar.gz
 ...
 $ tar -xzmf debhello-1.4.tar.gz
 $ tree
.
├── debhello-1.4
│   ├── LICENSE
│   ├── Makefile
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── man
│   │   └── hello.1
│   └── src
│       ├── config.h
│       └── hello.c
└── debhello-1.4.tar.gz

4 directories, 8 files

Here, the contents of this source are as follows.

src/hello.c (v=1.4):
 $ cat debhello-1.4/src/hello.c
#include "config.h"
#include <math.h>
#include <stdio.h>
int
main()
{
        printf("Hello, I am " PACKAGE_AUTHOR "!\n");
        printf("4.0 * atan(1.0) = %10f8\n", 4.0*atan(1.0));
        return 0;
}
src/config.h (v=1.4):
 $ cat debhello-1.4/src/config.h
#define PACKAGE_AUTHOR "Osamu Aoki"
Makefile (v=1.4):
 $ cat debhello-1.4/Makefile
prefix = /usr/local

all: src/hello

src/hello: src/hello.c
        $(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) -o $@ $^ -lm

install: src/hello
        install -D src/hello \
                $(DESTDIR)$(prefix)/bin/hello
        install -m 644 -D data/hello.desktop \
                $(DESTDIR)$(prefix)/share/applications/hello.desktop
        install -m 644 -D data/hello.png \
                $(DESTDIR)$(prefix)/share/pixmaps/hello.png
        install -m 644 -D man/hello.1 \
                $(DESTDIR)$(prefix)/share/man/man1/hello.1

clean:
        -rm -f src/hello

distclean: clean

uninstall:
        -rm -f $(DESTDIR)$(prefix)/bin/hello
        -rm -f $(DESTDIR)$(prefix)/share/applications/hello.desktop
        -rm -f $(DESTDIR)$(prefix)/share/pixmaps/hello.png
        -rm -f $(DESTDIR)$(prefix)/share/man/man1/hello.1

.PHONY: all install clean distclean uninstall

Please note that this Makefile has the proper install target for the manpage, the desktop file, and the desktop icon.

Let’s package this with the debmake command.

 $ cd debhello-1.4
 $ debmake
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.4", rev="1"
I: *** start packaging in "debhello-1.4". ***
I: provide debhello_1.4.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.4.tar.gz debhello_1.4.orig.tar.gz
I: pwd = "/path/to/debhello-1.4"
I: parse binary package settings:
I: binary package=debhello Type=bin / Arch=any M-A=foreign
...

The result is practically the same as [step-debmake].

Let’s make this Debian package better as the maintainer which is practically the same as [step-maintainer].

If the DEB_BUILD_MAINT_OPTIONS is not exported in the debian/rules, the lintian warns "W: debhello: hardening-no-relro usr/bin/hello" for the linking of the libm.

The debian/control file making it exactly the same as one in [step-maintainer], since the libm library is always available as a part of the libc6 (Priority: required).

There are several other template files under the debian/ directory. These also needs to be updated.

Template files under debian/. (v=1.4):
 $ tree debhello-1.4/debian
debhello-1.4/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── patches
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 10 files

The rest of the packaging activities are practically the same as the one in [step-debuild].

Here is the generated dependency list of binary packages.

The generated dependency list of binary packages (v=1.4):
 $ dpkg -f debhello_1.4-1_amd64.deb pre-depends depends recommends conflics b...
Depends: libc6 (>= 2.3.4)

Makefile.in + configure (single-binary)

Here is an example of creating a simple Debian package from a simple C source using the Makefile.in and configure as its build system.

This is an enhanced upstream source example for [makefile-single]. This also links to an external library libm and this source is configurable using arguments to the configure script which generates the Makefile and src/config.h files.

Let’s assume this upstream tarball to be debhello-1.5.tar.gz.

This type of source is meant to be installed as a non-system file, for example, as:

 $ tar -xzmf debhello-1.5.tar.gz
 $ cd debhello-1.5
 $ ./configure --with-math
 $ make
 $ make install

Let’s get the source and make the Debian package.

Download debhello-1.5.tar.gz
 $ wget http://www.example.org/download/debhello-1.5.tar.gz
 ...
 $ tar -xzmf debhello-1.5.tar.gz
 $ tree
.
├── debhello-1.5
│   ├── LICENSE
│   ├── Makefile.in
│   ├── configure
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── man
│   │   └── hello.1
│   └── src
│       └── hello.c
└── debhello-1.5.tar.gz

4 directories, 8 files

Here, the contents of this source are as follows.

src/hello.c (v=1.5):
 $ cat debhello-1.5/src/hello.c
#include "config.h"
#ifdef WITH_MATH
#  include <math.h>
#endif
#include <stdio.h>
int
main()
{
        printf("Hello, I am " PACKAGE_AUTHOR "!\n");
#ifdef WITH_MATH
        printf("4.0 * atan(1.0) = %10f8\n", 4.0*atan(1.0));
#else
        printf("I can't do MATH!\n");
#endif
        return 0;
}
Makefile.in (v=1.5):
 $ cat debhello-1.5/Makefile.in
prefix = @prefix@

all: src/hello

src/hello: src/hello.c
        $(CC) @VERBOSE@ \
                $(CPPFLAGS) \
                $(CFLAGS) \
                $(LDFLAGS) \
                -o $@ $^ \
                @LINKLIB@

install: src/hello
        install -D src/hello \
                $(DESTDIR)$(prefix)/bin/hello
        install -m 644 -D data/hello.desktop \
                $(DESTDIR)$(prefix)/share/applications/hello.desktop
        install -m 644 -D data/hello.png \
                $(DESTDIR)$(prefix)/share/pixmaps/hello.png
        install -m 644 -D man/hello.1 \
                $(DESTDIR)$(prefix)/share/man/man1/hello.1

clean:
        -rm -f src/hello

distclean: clean

uninstall:
        -rm -f $(DESTDIR)$(prefix)/bin/hello
        -rm -f $(DESTDIR)$(prefix)/share/applications/hello.desktop
        -rm -f $(DESTDIR)$(prefix)/share/pixmaps/hello.png
        -rm -f $(DESTDIR)$(prefix)/share/man/man1/hello.1

.PHONY: all install clean distclean uninstall
configure (v=1.5):
 $ cat debhello-1.5/configure
#!/bin/sh -e
# default values
PREFIX="/usr/local"
VERBOSE=""
WITH_MATH="0"
LINKLIB=""
PACKAGE_AUTHOR="John Doe"

# parse arguments
while [ "${1}" != "" ]; do
  VAR="${1%=*}" # Drop suffix =*
  VAL="${1#*=}" # Drop prefix *=
  case "${VAR}" in
  --prefix)
    PREFIX="${VAL}"
    ;;
  --verbose|-v)
    VERBOSE="-v"
    ;;
  --with-math)
    WITH_MATH="1"
    LINKLIB="-lm"
    ;;
  --author)
    PACKAGE_AUTHOR="${VAL}"
    ;;
  *)
    echo "W: Unknown argument: ${1}"
  esac
  shift
done

# setup configured Makefile and src/config.h
sed -e "s,@prefix@,${PREFIX}," \
    -e "s,@VERBOSE@,${VERBOSE}," \
    -e "s,@LINKLIB@,${LINKLIB}," \
    <Makefile.in >Makefile
if [ "${WITH_MATH}" = 1 ]; then
echo "#define WITH_MATH" >src/config.h
else
echo "/* not defined: WITH_MATH */" >src/config.h
fi
echo "#define PACKAGE_AUTHOR \"${PACKAGE_AUTHOR}\"" >>src/config.h

Please note that the configure command replaces strings with @…@ in the Makefile.in to produce Makefile and creates src/config.h.

Let’s package this with the debmake command.

 $ cd debhello-1.5
 $ debmake
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.5", rev="1"
I: *** start packaging in "debhello-1.5". ***
I: provide debhello_1.5.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.5.tar.gz debhello_1.5.orig.tar.gz
I: pwd = "/path/to/debhello-1.5"
I: parse binary package settings:
I: binary package=debhello Type=bin / Arch=any M-A=foreign
...

The result is similar to [step-debmake] but not exactly the same.

Let’s inspect notable template files generated.

debian/rules (template file, v=1.5):
 $ cat debhello-1.5/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=1.5):
 $ vim debhello-1.5/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-1.5/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

override_dh_auto_configure:
        dh_auto_configure -- \
                --with-math \
                --author="Osamu Aoki"

There are several other template files under the debian/ directory. These also needs to be updated.

The rest of the packaging activities are practically the same as the one in [step-debuild].

Autotools (single-binary)

Here is an example of creating a simple Debian package from a simple C source using the Autotools = Autoconf and Automake (Makefile.am and configure.ac) as its build system. See [autotools].

This source usually comes with the upstream auto-generated Makefile.in and configure files, too. This source can be packaged using these files as [configure-single] with the help of the autotools-dev package.

The better alternative is to regenerate these files using the latest Autoconf and Automake packages if the upstream provided Makefile.am and configure.ac are compatible with the latest version. This is advantageous for the porting to the new CPU architectures etc. This can be automated by using the “--with autoreconf” option for the dh command.

Let’s assume this upstream tarball to be debhello-1.6.tar.gz.

This type of source is meant to be installed as a non-system file, for example, as:

 $ tar -xzmf debhello-1.6.tar.gz
 $ cd debhello-1.6
 $ autoreconf -ivf # optional
 $ ./configure --with-math
 $ make
 $ make install

Let’s get the source and make the Debian package.

Download debhello-1.6.tar.gz
 $ wget http://www.example.org/download/debhello-1.6.tar.gz
 ...
 $ tar -xzmf debhello-1.6.tar.gz
 $ tree
.
├── debhello-1.6
│   ├── Makefile.am
│   ├── configure.ac
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── man
│   │   ├── Makefile.am
│   │   └── hello.1
│   └── src
│       ├── Makefile.am
│       └── hello.c
└── debhello-1.6.tar.gz

4 directories, 9 files

Here, the contents of this source are as follows.

src/hello.c (v=1.6):
 $ cat debhello-1.6/src/hello.c
#include "config.h"
#ifdef WITH_MATH
#  include <math.h>
#endif
#include <stdio.h>
int
main()
{
        printf("Hello, I am " PACKAGE_AUTHOR "!\n");
#ifdef WITH_MATH
        printf("4.0 * atan(1.0) = %10f8\n", 4.0*atan(1.0));
#else
        printf("I can't do MATH!\n");
#endif
        return 0;
}
Makefile.am (v=1.6):
 $ cat debhello-1.6/Makefile.am
SUBDIRS = src man
 $ cat debhello-1.6/man/Makefile.am
dist_man_MANS = hello.1
 $ cat debhello-1.6/src/Makefile.am
bin_PROGRAMS = hello
hello_SOURCES = hello.c
configure.ac (v=1.6):
 $ cat debhello-1.6/configure.ac
#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.69])
AC_INIT([debhello],[2.1],[foo@example.org])
AC_CONFIG_SRCDIR([src/hello.c])
AC_CONFIG_HEADERS([config.h])
echo "Standard customization chores"
AC_CONFIG_AUX_DIR([build-aux])
AM_INIT_AUTOMAKE([foreign])
# Add #define PACKAGE_AUTHOR ... in config.h with a comment
AC_DEFINE(PACKAGE_AUTHOR, ["Osamu Aoki"], [Define PACKAGE_AUTHOR])
echo "Add --with-math option functionality to ./configure"
AC_ARG_WITH([math],
  [AS_HELP_STRING([--with-math],
    [compile with math library  @<:@default=yes@:>@])],
  [],
  [with_math="yes"]
  )
echo "==== withval   := \"$withval\""
echo "==== with_math := \"$with_math\""
# m4sh if-else construct
AS_IF([test "x$with_math" != "xno"],[
  echo "==== Check include: math.h"
  AC_CHECK_HEADER(math.h,[],[
    AC_MSG_ERROR([Couldn't find math.h.] )
  ])
  echo "==== Check library: libm"
  AC_SEARCH_LIBS(atan, [m])
  #AC_CHECK_LIB(m, atan)
  echo "==== Build with LIBS := \"$LIBS\""
  AC_DEFINE(WITH_MATH, [1], [Build with the math library])
],[
  echo "==== Skip building with math.h."
  AH_TEMPLATE(WITH_MATH, [Build without the math library])
])
# Checks for programs.
AC_PROG_CC
AC_CONFIG_FILES([Makefile
                 man/Makefile
                 src/Makefile])
AC_OUTPUT

Let’s package this with the debmake command.

 $ cd debhello-1.6
 $ debmake
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.6", rev="1"
I: *** start packaging in "debhello-1.6". ***
I: provide debhello_1.6.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.6.tar.gz debhello_1.6.orig.tar.gz
I: pwd = "/path/to/debhello-1.6"
I: parse binary package settings:
I: binary package=debhello Type=bin / Arch=any M-A=foreign
...

The result is similar to [configure-single] but not exactly the same.

Let’s inspect notable template files generated.

debian/rules (template file, v=1.6):
 $ cat debhello-1.6/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@ --with autoreconf

#override_dh_install:
#       dh_install --list-missing -X.la -X.pyc -X.pyo

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=1.6):
 $ vim debhello-1.6/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-1.6/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@ --with autoreconf

override_dh_auto_configure:
        dh_auto_configure -- \
                --with-math

There are several other template files under the debian/ directory. These also needs to be updated.

The rest of the packaging activities are practically the same as the one in [step-debuild].

CMake (single-binary)

Here is an example of creating a simple Debian package from a simple C source using the CMake (CMakeLists.txt and some files such as config.h.in) as its build system. See [cmake].

The cmake command generates the Makefile file based on the CMakeLists.txt file and its -D option. It also configure the file as specified in its configure_file(…) by replacing strings with @…@ and changing #cmakedefine … line.

Let’s assume this upstream tarball to be debhello-1.7.tar.gz.

This type of source is meant to be installed as a non-system file, for example, as:

 $ tar -xzmf debhello-1.7.tar.gz
 $ cd debhello-1.7
 $ mkdir obj-x86_64-linux-gnu # for out-of-tree build
 $ cd obj-x86_64-linux-gnu
 $ cmake ..
 $ make
 $ make install

Let’s get the source and make the Debian package.

Download debhello-1.7.tar.gz
 $ wget http://www.example.org/download/debhello-1.7.tar.gz
 ...
 $ tar -xzmf debhello-1.7.tar.gz
 $ tree
.
├── debhello-1.7
│   ├── CMakeLists.txt
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── man
│   │   ├── CMakeLists.txt
│   │   └── hello.1
│   └── src
│       ├── CMakeLists.txt
│       ├── config.h.in
│       └── hello.c
└── debhello-1.7.tar.gz

4 directories, 9 files

Here, the contents of this source are as follows.

src/hello.c (v=1.7):
 $ cat debhello-1.7/src/hello.c
#include "config.h"
#ifdef WITH_MATH
#  include <math.h>
#endif
#include <stdio.h>
int
main()
{
        printf("Hello, I am " PACKAGE_AUTHOR "!\n");
#ifdef WITH_MATH
        printf("4.0 * atan(1.0) = %10f8\n", 4.0*atan(1.0));
#else
        printf("I can't do MATH!\n");
#endif
        return 0;
}
src/config.h.in (v=1.7):
 $ cat debhello-1.7/src/config.h.in
/* name of the package author */
#define PACKAGE_AUTHOR "@PACKAGE_AUTHOR@"
/* math library support */
#cmakedefine WITH_MATH
CMakeLists.txt (v=1.7):
 $ cat debhello-1.7/CMakeLists.txt
cmake_minimum_required(VERSION 2.8)
project(debhello)
set(PACKAGE_AUTHOR "Osamu Aoki")
add_subdirectory(src)
add_subdirectory(man)
 $ cat debhello-1.7/man/CMakeLists.txt
install(
  FILES ${CMAKE_CURRENT_SOURCE_DIR}/hello.1
  DESTINATION share/man/man1
)
 $ cat debhello-1.7/src/CMakeLists.txt
# Always define HAVE_CONFIG_H
add_definitions(-DHAVE_CONFIG_H)
# Interactively define WITH_MATH
option(WITH_MATH "Build with math support" OFF)
#variable_watch(WITH_MATH)
# Generate config.h from config.h.in
configure_file(
  "${CMAKE_CURRENT_SOURCE_DIR}/config.h.in"
  "${CMAKE_CURRENT_BINARY_DIR}/config.h"
)
include_directories("${CMAKE_CURRENT_BINARY_DIR}")
add_executable(hello hello.c)
install(TARGETS hello
  RUNTIME DESTINATION bin
)

Let’s package this with the debmake command.

 $ cd debhello-1.7
 $ debmake
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="1.7", rev="1"
I: *** start packaging in "debhello-1.7". ***
I: provide debhello_1.7.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-1.7.tar.gz debhello_1.7.orig.tar.gz
I: pwd = "/path/to/debhello-1.7"
I: parse binary package settings:
I: binary package=debhello Type=bin / Arch=any M-A=foreign
...

The result is similar to [configure-single] but not exactly the same.

Let’s inspect notable template files generated.

debian/rules (template file, v=1.7):
 $ cat debhello-1.7/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

#override_dh_auto_configure:
#       dh_auto_configure -- \
#             -DCMAKE_LIBRARY_ARCHITECTURE="$(DEB_TARGET_MULTIARCH)"
debian/control (template file, v=1.7):
 $ cat debhello-1.7/debian/control
Source: debhello
Section: unknown
Priority: extra
Maintainer: "Firstname Lastname" <email.address@example.org>
Build-Depends: cmake, debhelper (>=9)
Standards-Version: 3.9.6
Homepage: <insert the upstream URL, if relevant>

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: auto-generated package by debmake
 This Debian binary package was auto-generated by the
 debmake(1) command provided by the debmake package.

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=1.7):
 $ vim debhello-1.7/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-1.7/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

override_dh_auto_configure:
        dh_auto_configure -- -DWITH-MATH=1
debian/control (maintainer version, v=1.7):
 $ vim debhello-1.7/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-1.7/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: cmake, debhelper (>=9)
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: example package in the debmake-doc package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.

There are several other template files under the debian/ directory. These also needs to be updated.

The rest of the packaging activities are practically the same as the one in [configure-single].

Autotools (multi-binary)

Here is an example of creating a set of Debian binary packages including the executable package, the shared library package, the development file package, and the debug symbol package from a simple C source using the Autotools = Autoconf and Automake (Makefile.am and configure.ac) as its build system. See [autotools].

Let’s package this in the same way as [autotools-single].

Let’s assume this upstream tarball to be debhello-2.0.tar.gz.

This type of source is meant to be installed as a non-system file, for example, as:

 $ tar -xzmf debhello-2.0.tar.gz
 $ cd debhello-2.0
 $ autoreconf -ivf # optional
 $ ./configure --with-math
 $ make
 $ make install

Let’s get the source and make the Debian package.

Download debhello-2.0.tar.gz
 $ wget http://www.example.org/download/debhello-2.0.tar.gz
 ...
 $ tar -xzmf debhello-2.0.tar.gz
 $ tree
.
├── debhello-2.0
│   ├── Makefile.am
│   ├── configure.ac
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── lib
│   │   ├── Makefile.am
│   │   ├── sharedlib.c
│   │   └── sharedlib.h
│   ├── man
│   │   ├── Makefile.am
│   │   └── hello.1
│   └── src
│       ├── Makefile.am
│       └── hello.c
└── debhello-2.0.tar.gz

5 directories, 12 files

Here, the contents of this source are as follows.

src/hello.c (v=2.0):
 $ cat debhello-2.0/src/hello.c
#include "config.h"
#include <stdio.h>
#include <sharedlib.h>
int
main()
{
        printf("Hello, I am " PACKAGE_AUTHOR "!\n");
        sharedlib();
        return 0;
}
lib/sharedlib.h and lib/sharedlib.c (v=1.6):
 $ cat debhello-2.0/lib/sharedlib.h
int sharedlib();
 $ cat debhello-2.0/lib/sharedlib.c
#include <stdio.h>
int
sharedlib()
{
        printf("This is a shared library!\n");
        return 0;
}
Makefile.am (v=2.0):
 $ cat debhello-2.0/Makefile.am
# recursively process `Makefile.am` in SUBDIRS
SUBDIRS = lib src man
 $ cat debhello-2.0/man/Makefile.am
# manpages (distributed in the source package)
dist_man_MANS = hello.1
 $ cat debhello-2.0/lib/Makefile.am
# libtool librares to be produced
lib_LTLIBRARIES = libsharedlib.la

# source files used for lib_LTLIBRARIES
libsharedlib_la_SOURCES = sharedlib.c

# C pre-processor flags used for lib_LTLIBRARIES
#libsharedlib_la_CPPFLAGS =

# Headers files to be installed in <prefix>/include
include_HEADERS = sharedlib.h

# Versioning Libtool Libraries with version triplets
libsharedlib_la_LDFLAGS = -version-info 1:0:0
 $ cat debhello-2.0/src/Makefile.am
# program executables to be produced
bin_PROGRAMS = hello

# source files used for bin_PROGRAMS
hello_SOURCES = hello.c

# C pre-processor flags used for bin_PROGRAMS
AM_CPPFLAGS = -I$(srcdir) -I$(top_srcdir)/lib

# Extra options for the linker for hello
# hello_LDFLAGS =

# Libraries the `hello` binary to be linked
hello_LDADD = $(top_srcdir)/lib/libsharedlib.la
configure.ac (v=2.0):
 $ cat debhello-2.0/configure.ac
#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.69])
AC_INIT([debhello],[2.2],[foo@example.org])
AC_CONFIG_SRCDIR([src/hello.c])
AC_CONFIG_HEADERS([config.h])
echo "Standard customization chores"
AC_CONFIG_AUX_DIR([build-aux])

AM_INIT_AUTOMAKE([foreign])

# Set default to --enable-shared --disable-static
LT_INIT([shared disable-static])

# find the libltdl sources in the libltdl sub-directory
LT_CONFIG_LTDL_DIR([libltdl])

# choose one
LTDL_INIT([recursive])
#LTDL_INIT([subproject])
#LTDL_INIT([nonrecursive])

# Add #define PACKAGE_AUTHOR ... in config.h with a comment
AC_DEFINE(PACKAGE_AUTHOR, ["Osamu Aoki"], [Define PACKAGE_AUTHOR])
# Checks for programs.
AC_PROG_CC

# only for the recursive case
AC_CONFIG_FILES([Makefile
                 lib/Makefile
                 man/Makefile
                 src/Makefile])
AC_OUTPUT

Let’s package this with the debmake command into multiple packages:

  • debhello: type = bin

  • libsharedlib1: type = lib

  • libsharedlib-dev: type = dev

  • debhello-dbg: type = dbg

  • libsharedlib1-dbg: type = dbg

Here, the -b',libsharedlib1,libsharedlib-dev,-dbg,libsharedlib1-dbg' option is used to specify the generated binary packages.

 $ cd debhello-2.0
 $ debmake -b',libsharedlib1,libsharedlib-dev,-dbg,libsharedlib1-dbg'
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="2.0", rev="1"
I: *** start packaging in "debhello-2.0". ***
I: provide debhello_2.0.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-2.0.tar.gz debhello_2.0.orig.tar.gz
I: pwd = "/path/to/debhello-2.0"
I: parse binary package settings: ,libsharedlib1,libsharedlib-dev,-dbg,libsha...
I: binary package=debhello Type=bin / Arch=any M-A=foreign
I: binary package=libsharedlib1 Type=lib / Arch=any M-A=same
I: binary package=libsharedlib-dev Type=dev / Arch=any M-A=same
I: binary package=debhello-dbg Type=dbg / Arch=any M-A=same
I: binary package=libsharedlib1-dbg Type=dbg / Arch=any M-A=same
...

The result is similar to [configure-single] but with more template files.

Let’s inspect notable template files generated.

debian/rules (template file, v=2.0):
 $ cat debhello-2.0/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@ --with autoreconf

#override_dh_install:
#       dh_install --list-missing -X.la -X.pyc -X.pyo

override_dh_strip:
        dh_strip -Xlibsharedlib1 --dbg-package=debhello-dbg
        dh_strip -Xdebhello --dbg-package=libsharedlib1-dbg

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=2.0):
 $ vim debhello-2.0/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-2.0/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@ --with autoreconf

override_dh_install:
        dh_install --list-missing -X.la

override_dh_strip:
        dh_strip -Xlibsharedlib1 --dbg-package=debhello-dbg
        dh_strip -Xdebhello --dbg-package=libsharedlib1-dbg
debian/control (maintainer version, v=2.0):
 $ vim debhello-2.0/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-2.0/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: debhelper (>=9), dh-autoreconf
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: libsharedlib1 (= ${binary:Version}),
         ${misc:Depends},
         ${shlibs:Depends}
Description: example executable package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package provides the executable program.

Package: libsharedlib1
Section: libs
Architecture: any
Multi-Arch: same
Pre-Depends: ${misc:Pre-Depends}
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: example shared library package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the shared library.

Package: libsharedlib-dev
Section: libdevel
Architecture: any
Multi-Arch: same
Depends: libsharedlib1 (= ${binary:Version}), ${misc:Depends}
Description: example development package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the development files.

Package: debhello-dbg
Section: debug
Architecture: any
Multi-Arch: same
Depends: debhello (= ${binary:Version}), ${misc:Depends}
Description: example debugging package for debhello
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the debugging symbols for debhello.

Package: libsharedlib1-dbg
Section: debug
Architecture: any
Multi-Arch: same
Depends: libsharedlib1 (= ${binary:Version}), ${misc:Depends}
Description: example debugging package for libsharedlib1
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the debugging symbols for libsharedlib1.
debian/*.install (maintainer version, v=2.0):
 $ vim debhello-2.0/debian/debhello.install
 ... hack, hack, hack, ...
 $ cat debhello-2.0/debian/debhello.install
usr/bin/*
usr/share/man/*
 $ vim debhello-2.0/debian/libsharedlib1.install
 ... hack, hack, hack, ...
 $ cat debhello-2.0/debian/libsharedlib1.install
usr/lib/*/*.so.*
 $ vim debhello-2.0/debian/libsharedlib-dev.install
 ... hack, hack, hack, ...
 $ cat debhello-2.0/debian/libsharedlib-dev.install
###usr/lib/*/pkgconfig/*.pc
usr/include
usr/lib/*/*.so

Since this upstream source creates the proper auto-generated Makefile, there are no needs to create debian/install and debian/manpages files.

There are several other template files under the debian/ directory. These also needs to be updated.

Template files under debian/. (v=2.0):
 $ tree debhello-2.0/debian
debhello-2.0/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── debhello.install
├── libsharedlib-dev.install
├── libsharedlib1.install
├── libsharedlib1.symbols
├── patches
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 14 files

The rest of the packaging activities are practically the same as the one in [configure-single].

Here are the generated dependency lists of binary packages.

The generated dependency lists of binary packages (v=2.0):
 $ dpkg -f debhello-dbg_2.0-1_amd64.deb pre-depends depends recommends confli...
Depends: debhello (= 2.0-1)
 $ dpkg -f debhello_2.0-1_amd64.deb pre-depends depends recommends conflics b...
Depends: libsharedlib1 (= 2.0-1), libc6 (>= 2.2.5)
 $ dpkg -f libsharedlib-dev_2.0-1_amd64.deb pre-depends depends recommends co...
Depends: libsharedlib1 (= 2.0-1)
 $ dpkg -f libsharedlib1-dbg_2.0-1_amd64.deb pre-depends depends recommends c...
Depends: libsharedlib1 (= 2.0-1)
 $ dpkg -f libsharedlib1_2.0-1_amd64.deb pre-depends depends recommends confl...
Depends: libc6 (>= 2.2.5)

CMake (multi-binary)

Here is an example of creating a set of Debian binary packages including the executable package, the shared library package, the development file package, and the debug symbol package from a simple C source using the CMake (CMakeLists.txt and some files such as config.h.in) as its build system. See [cmake].

Let’s assume this upstream tarball to be debhello-2.1.tar.gz.

This type of source is meant to be installed as a non-system file, for example, as:

 $ tar -xzmf debhello-2.1.tar.gz
 $ cd debhello-2.1
 $ mkdir obj-x86_64-linux-gnu
 $ cd obj-x86_64-linux-gnu
 $ cmake ..
 $ make
 $ make install

Let’s get the source and make the Debian package.

Download debhello-2.1.tar.gz
 $ wget http://www.example.org/download/debhello-2.1.tar.gz
 ...
 $ tar -xzmf debhello-2.1.tar.gz
 $ tree
.
├── debhello-2.1
│   ├── CMakeLists.txt
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── lib
│   │   ├── CMakeLists.txt
│   │   ├── sharedlib.c
│   │   └── sharedlib.h
│   ├── man
│   │   ├── CMakeLists.txt
│   │   └── hello.1
│   └── src
│       ├── CMakeLists.txt
│       ├── config.h.in
│       └── hello.c
└── debhello-2.1.tar.gz

5 directories, 12 files

Here, the contents of this source are as follows.

src/hello.c (v=2.1):
 $ cat debhello-2.1/src/hello.c
#include "config.h"
#include <stdio.h>
#include <sharedlib.h>
int
main()
{
        printf("Hello, I am " PACKAGE_AUTHOR "!\n");
        sharedlib();
        return 0;
}
src/config.h.in (v=2.1):
 $ cat debhello-2.1/src/config.h.in
/* name of the package author */
#define PACKAGE_AUTHOR "@PACKAGE_AUTHOR@"
lib/sharedlib.c and lib/sharedlib.h (v=2.1):
 $ cat debhello-2.1/lib/sharedlib.h
int sharedlib();
 $ cat debhello-2.1/lib/sharedlib.c
#include <stdio.h>
int
sharedlib()
{
        printf("This is a shared library!\n");
        return 0;
}
CMakeLists.txt (v=2.1):
 $ cat debhello-2.1/CMakeLists.txt
cmake_minimum_required(VERSION 2.8)
project(debhello)
set(PACKAGE_AUTHOR "Osamu Aoki")
add_subdirectory(lib)
add_subdirectory(src)
add_subdirectory(man)
 $ cat debhello-2.1/man/CMakeLists.txt
install(
  FILES ${CMAKE_CURRENT_SOURCE_DIR}/hello.1
  DESTINATION share/man/man1
)
 $ cat debhello-2.1/src/CMakeLists.txt
# Always define HAVE_CONFIG_H
add_definitions(-DHAVE_CONFIG_H)
# Generate config.h from config.h.in
configure_file(
  "${CMAKE_CURRENT_SOURCE_DIR}/config.h.in"
  "${CMAKE_CURRENT_BINARY_DIR}/config.h"
  )
include_directories("${CMAKE_CURRENT_BINARY_DIR}")
include_directories("${CMAKE_SOURCE_DIR}/lib")

add_executable(hello hello.c)
target_link_libraries(hello sharedlib)
install(TARGETS hello
  RUNTIME DESTINATION bin
)

Let’s package this with the debmake command.

 $ cd debhello-2.1
 $ debmake -b',libsharedlib1,libsharedlib-dev,-dbg,libsharedlib1-dbg'
I: set parameters
I: sanity check of parameters
I: pkg="debhello", ver="2.1", rev="1"
I: *** start packaging in "debhello-2.1". ***
I: provide debhello_2.1.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf debhello-2.1.tar.gz debhello_2.1.orig.tar.gz
I: pwd = "/path/to/debhello-2.1"
I: parse binary package settings: ,libsharedlib1,libsharedlib-dev,-dbg,libsha...
I: binary package=debhello Type=bin / Arch=any M-A=foreign
...

The result is similar to [configure-single] but not exactly the same.

Let’s inspect notable template files generated.

debian/rules (template file, v=2.1):
 $ cat debhello-2.1/debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
#export DH_VERBOSE = 1
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

#override_dh_auto_configure:
#       dh_auto_configure -- \
#             -DCMAKE_LIBRARY_ARCHITECTURE="$(DEB_TARGET_MULTIARCH)"

override_dh_strip:
        dh_strip -Xlibsharedlib1 --dbg-package=debhello-dbg
        dh_strip -Xdebhello --dbg-package=libsharedlib1-dbg

Let’s make this Debian package better as the maintainer.

debian/rules (maintainer version, v=2.1):
 $ vim debhello-2.1/debian/rules
 ... hack, hack, hack, ...
 $ cat debhello-2.1/debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
DEB_HOST_MULTIARCH ?= $(shell dpkg-architecture -qDEB_HOST_MULTIARCH)

%:
        dh $@

override_dh_auto_configure:
        dh_auto_configure -- \
              -DCMAKE_LIBRARY_ARCHITECTURE="$(DEB_HOST_MULTIARCH)"

override_dh_install:
        dh_install --list-missing

override_dh_strip:
        dh_strip -Xlibsharedlib1 --dbg-package=debhello-dbg
        dh_strip -Xdebhello --dbg-package=libsharedlib1-dbg
debian/control (maintainer version, v=2.1):
 $ vim debhello-2.1/debian/control
 ... hack, hack, hack, ...
 $ cat debhello-2.1/debian/control
Source: debhello
Section: devel
Priority: extra
Maintainer: Osamu Aoki <osamu@debian.org>
Build-Depends: cmake, debhelper (>=9)
Standards-Version: 3.9.6
Homepage: http://anonscm.debian.org/cgit/collab-maint/debmake-doc.git/

Package: debhello
Architecture: any
Multi-Arch: foreign
Depends: libsharedlib1 (= ${binary:Version}),
         ${misc:Depends},
         ${shlibs:Depends}
Description: example executable package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package provides the executable program.

Package: libsharedlib1
Section: libs
Architecture: any
Multi-Arch: same
Pre-Depends: ${misc:Pre-Depends}
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: example shared library package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the shared library.

Package: libsharedlib-dev
Section: libdevel
Architecture: any
Multi-Arch: same
Depends: libsharedlib1 (= ${binary:Version}), ${misc:Depends}
Description: example development package
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the development files.

Package: debhello-dbg
Section: debug
Architecture: any
Multi-Arch: same
Depends: debhello (= ${binary:Version}), ${misc:Depends}
Description: example debugging package for debhello
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the debugging symbols for debhello.

Package: libsharedlib1-dbg
Section: debug
Architecture: any
Multi-Arch: same
Depends: libsharedlib1 (= ${binary:Version}), ${misc:Depends}
Description: example debugging package for libsharedlib1
 This is an example package to demonstrate the Debian packaging using
 the debmake command.
 .
 The generated Debian package uses the dh command offered by the
 debhelper package and the dpkg source format `3.0 (quilt)'.
 .
 This package contains the debugging symbols for libsharedlib1.
debian/*.install (maintainer version, v=2.1):
 $ vim debhello-2.1/debian/debhello.install
 ... hack, hack, hack, ...
 $ cat debhello-2.1/debian/debhello.install
usr/bin/*
usr/share/man/*
 $ vim debhello-2.1/debian/libsharedlib1.install
 ... hack, hack, hack, ...
 $ cat debhello-2.1/debian/libsharedlib1.install
usr/lib/*/*.so.*
 $ vim debhello-2.1/debian/libsharedlib-dev.install
 ... hack, hack, hack, ...
 $ cat debhello-2.1/debian/libsharedlib-dev.install
###usr/lib/*/pkgconfig/*.pc
usr/include
usr/lib/*/*.so

This upstream CMakeList.txt needs to be patched to cope with the multiarch path.

debian/patches/* (maintainer version, v=2.1):
 ... hack, hack, hack, ...
 $ cat debhello-2.1/debian/libsharedlib1.symbols
libsharedlib.so.1 libsharedlib1 #MINVER#
 sharedlib@Base 2.1

Since this upstream source creates the proper auto-generated Makefile, there are no needs to create debian/install and debian/manpages files.

There are several other template files under the debian/ directory. These also needs to be updated.

Template files under debian/. (v=2.1):
 $ tree debhello-2.1/debian
debhello-2.1/debian
├── README.Debian
├── changelog
├── compat
├── control
├── copyright
├── debhello.install
├── libsharedlib-dev.install
├── libsharedlib1.install
├── libsharedlib1.symbols
├── patches
│   ├── 000-cmake-multiarch.patch
│   └── series
├── rules
├── source
│   ├── format
│   └── local-options
└── watch

2 directories, 15 files

The rest of the packaging activities are practically the same as the one in [configure-single].

Here are the generated dependency lists of binary packages.

The generated dependency lists of binary packages (v=2.1):
 $ dpkg -f debhello-dbg_2.1-1_amd64.deb pre-depends depends recommends confli...
Depends: debhello (= 2.1-1)
 $ dpkg -f debhello_2.1-1_amd64.deb pre-depends depends recommends conflics b...
Depends: libsharedlib1 (= 2.1-1), libc6 (>= 2.2.5)
 $ dpkg -f libsharedlib-dev_2.1-1_amd64.deb pre-depends depends recommends co...
Depends: libsharedlib1 (= 2.1-1)
 $ dpkg -f libsharedlib1-dbg_2.1-1_amd64.deb pre-depends depends recommends c...
Depends: libsharedlib1 (= 2.1-1)
 $ dpkg -f libsharedlib1_2.1-1_amd64.deb pre-depends depends recommends confl...
Depends: libc6 (>= 2.2.5)

Internationalization

Here is an example of updating the simple upstream C source debhello-2.0.tar.gz presented in [autotools-multi] for the internationalization (i18n) and creating the updated upstream C source debhello-2.0.tar.gz.

In the real situation, the package should be already internationalized. So this example is educational for you to understand how this internationalization is implemented.

Tip
The routine maintainer activity for the i18n is simply to add translation po files reported to you via BTS system to the po/ directory and to update the language list in the po/LINGUAS.

Let’s get the source and make the Debian package.

Download debhello-2.0.tar.gz (i18n)
 $ wget http://www.example.org/download/debhello-2.0.tar.gz
 ...
 $ tar -xzmf debhello-2.0.tar.gz
 $ tree
.
├── debhello-2.0
│   ├── Makefile.am
│   ├── configure.ac
│   ├── data
│   │   ├── hello.desktop
│   │   └── hello.png
│   ├── lib
│   │   ├── Makefile.am
│   │   ├── sharedlib.c
│   │   └── sharedlib.h
│   ├── man
│   │   ├── Makefile.am
│   │   └── hello.1
│   └── src
│       ├── Makefile.am
│       └── hello.c
└── debhello-2.0.tar.gz

5 directories, 12 files

Internationalize this source tree with the gettextize command and remove files auto-generated by the Autotools.

run gettextize (i18n):
 $ cd debhello-2.0
 $ gettextize
Creating po/ subdirectory
Creating build-aux/ subdirectory
Copying file ABOUT-NLS
Copying file build-aux/config.rpath
Not copying intl/ directory.
Copying file po/Makefile.in.in
Copying file po/Makevars.template
Copying file po/Rules-quot
Copying file po/boldquot.sed
Copying file po/en@boldquot.header
Copying file po/en@quot.header
Copying file po/insert-header.sin
Copying file po/quot.sed
Copying file po/remove-potcdate.sin
Creating initial po/POTFILES.in
Creating po/ChangeLog
Creating directory m4
Copying file m4/gettext.m4
Copying file m4/iconv.m4
Copying file m4/lib-ld.m4
Copying file m4/lib-link.m4
Copying file m4/lib-prefix.m4
Copying file m4/nls.m4
Copying file m4/po.m4
Copying file m4/progtest.m4
Creating m4/ChangeLog
Updating Makefile.am (backup is in Makefile.am~)
Updating configure.ac (backup is in configure.ac~)
Creating ChangeLog

Please use AM_GNU_GETTEXT([external]) in order to cause autoconfiguration
to look for an external libintl.

Please create po/Makevars from the template in po/Makevars.template.
You can then remove po/Makevars.template.

Please fill po/POTFILES.in as described in the documentation.

Please run 'aclocal' to regenerate the aclocal.m4 file.
You need aclocal from GNU automake 1.9 (or newer) to do this.
Then run 'autoconf' to regenerate the configure file.

You will also need config.guess and config.sub, which you can get from the CV...
of the 'config' project at http://savannah.gnu.org/. The commands to fetch th...
are
$ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/conf...
$ wget 'http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/conf...

You might also want to copy the convenience header file gettext.h
from the /usr/share/gettext directory into your package.
It is a wrapper around <libintl.h> that implements the configure --disable-nl...
option.

Press Return to acknowledge the previous 6 paragraphs.
 $ rm -rf m4 build-aux *~

Let’s check generated files under the po/ directory.

files in po (i18n):
total 60
-rw-rw-r-- 1 osamu osamu   478 Jun  7 10:14 ChangeLog
-rw-r--r-- 1 osamu osamu 17259 Jun  7 10:14 Makefile.in.in
-rw-r--r-- 1 osamu osamu  3376 Jun  7 10:14 Makevars.template
-rw-rw-r-- 1 osamu osamu    59 Jun  7 10:14 POTFILES.in
-rw-r--r-- 1 osamu osamu  2165 Jun  7 10:14 Rules-quot
-rw-r--r-- 1 osamu osamu   217 Jun  7 10:14 boldquot.sed
-rw-r--r-- 1 osamu osamu  1337 Jun  7 10:14 en@boldquot.header
-rw-r--r-- 1 osamu osamu  1203 Jun  7 10:14 en@quot.header
-rw-r--r-- 1 osamu osamu   672 Jun  7 10:14 insert-header.sin
-rw-r--r-- 1 osamu osamu   153 Jun  7 10:14 quot.sed
-rw-r--r-- 1 osamu osamu   432 Jun  7 10:14 remove-potcdate.sin

Let’s update the configure.ac by adding “AM_GNU_GETTEXT([external])”, etc..

configure.ac (i18n):
 $ vim configure.ac
 ... hack, hack, hack, ...
 $ cat configure.ac
#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.69])
AC_INIT([debhello],[2.2],[foo@example.org])
AC_CONFIG_SRCDIR([src/hello.c])
AC_CONFIG_HEADERS([config.h])
echo "Standard customization chores"
AC_CONFIG_AUX_DIR([build-aux])

AM_INIT_AUTOMAKE([foreign])

# Set default to --enable-shared --disable-static
LT_INIT([shared disable-static])

# find the libltdl sources in the libltdl sub-directory
LT_CONFIG_LTDL_DIR([libltdl])

# choose one
LTDL_INIT([recursive])
#LTDL_INIT([subproject])
#LTDL_INIT([nonrecursive])

# Add #define PACKAGE_AUTHOR ... in config.h with a comment
AC_DEFINE(PACKAGE_AUTHOR, ["Osamu Aoki"], [Define PACKAGE_AUTHOR])
# Checks for programs.
AC_PROG_CC

# desktop file support required
AM_GNU_GETTEXT_VERSION([0.19.3])
AM_GNU_GETTEXT([external])

# only for the recursive case
AC_CONFIG_FILES([Makefile
                 po/Makefile.in
                 lib/Makefile
                 man/Makefile
                 src/Makefile])
AC_OUTPUT

Let’s create the po/Makevars from the po/Makevars.template.

po/Makevars (i18n):
 ... hack, hack, hack, ...
 $ diff -u po/Makevars.template po/Makevars
--- po/Makevars.template        2015-06-07 10:14:37.268633375 +0900
+++ po/Makevars 2015-06-07 10:14:39.688633305 +0900
@@ -18,14 +18,14 @@
 # or entity, or to disclaim their copyright.  The empty string stands for
 # the public domain; in this case the translators are expected to disclaim
 # their copyright.
-COPYRIGHT_HOLDER = Free Software Foundation, Inc.
+COPYRIGHT_HOLDER = Osamu Aoki <osamu@debian.org>

 # This tells whether or not to prepend "GNU " prefix to the package
 # name that gets inserted into the header of the $(DOMAIN).pot file.
 # Possible values are "yes", "no", or empty.  If it is empty, try to
 # detect it automatically by scanning the files in $(top_srcdir) for
 # "GNU packagename" string.
-PACKAGE_GNU =
+PACKAGE_GNU = no

 # This is the email address or URL to which the translators shall report
 # bugs in the untranslated strings:
 $ rm po/Makevars.template

Let’s update C sources for the i18n by wrapping strings with _(…).

src/hello.c (i18n):
 ... hack, hack, hack, ...
 $ cat src/hello.c
#include "config.h"
#include <stdio.h>
#include <sharedlib.h>
#define _(string) gettext (string)
int
main()
{
        printf(_("Hello, I am " PACKAGE_AUTHOR "!\n"));
        sharedlib();
        return 0;
}
lib/sharedlib.c (i18n):
 ... hack, hack, hack, ...
 $ cat lib/sharedlib.c
#include <stdio.h>
#define _(string) gettext (string)
int
sharedlib()
{
        printf(_("This is a shared library!\n"));
        return 0;
}

The new gettext (v=0.19) can handle the i18n of the desktop file directly.

data/hello.desktop.in (i18n):
 $ fgrep -v '[ja]=' data/hello.desktop > data/hello.desktop.in
 $ rm data/hello.desktop
 $ cat data/hello.desktop.in
[Desktop Entry]
Name=Hello
Comment=Greetings
Type=Application
Keywords=hello
Exec=hello
Terminal=true
Icon=hello.png
Categories=Utility;

Let’s list the input files to extract translatable strings in po/POTFILES.in.

po/POTFILES.in (i18n):
 ... hack, hack, hack, ...
 $ cat po/POTFILES.in
src/hello.c
lib/sharedlib.c
data/hello.desktop.in

Here is the updated root Makefile.am with po added to the SUBDIRS.

Makefile.am (i18n):
 $ cat Makefile.am
# recursively process `Makefile.am` in SUBDIRS
SUBDIRS = po lib src man

ACLOCAL_AMFLAGS = -I m4

EXTRA_DIST = build-aux/config.rpath m4/ChangeLog

Let’s make a translation template file debhello.pot.

po/debhello.pot (i18n):
 $ xgettext -f po/POTFILES.in -d debhello -o po/debhello.pot -k_
 $ cat po/debhello.pot
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2015-06-07 10:14+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

#: src/hello.c:8
#, c-format
msgid "Hello, I am "
msgstr ""

#: lib/sharedlib.c:6
#, c-format
msgid "This is a shared library!\n"
msgstr ""

#: data/hello.desktop.in:3
msgid "Hello"
msgstr ""

#: data/hello.desktop.in:4
msgid "Greetings"
msgstr ""

#: data/hello.desktop.in:6
msgid "hello"
msgstr ""

#: data/hello.desktop.in:9
msgid "hello.png"
msgstr ""

Let’s add Japanese translation.

po/LINGUAS and po/fr.po (i18n):
 $ echo 'fr' > po/LINGUAS
 $ cp po/debhello.pot po/fr.po
 $ vim po/fr.po
 ... hack, hack, hack, ...
 $ cat po/fr.po
# SOME DESCRIPTIVE TITLE.
# This file is put in the public domain.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
msgid ""
msgstr ""
"Project-Id-Version: debhello 2.2\n"
"Report-Msgid-Bugs-To: foo@example.org\n"
"POT-Creation-Date: 2015-03-01 20:22+0900\n"
"PO-Revision-Date: 2015-02-21 23:18+0900\n"
"Last-Translator: Osamu Aoki <osamu@debian.org>\n"
"Language-Team: French <LL@li.org>\n"
"Language: ja\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: src/hello.c:34
#, c-format
msgid "Hello, I am %s!\n"
msgstr "Bonjour, je suis %s!\n"

#: lib/sharedlib.c:29
#, c-format
msgid "This is a shared library!\n"
msgstr "Ceci est une bibliothèque partagée!\n"

#: data/hello.desktop.in:3
msgid "Hello"
msgstr ""

#: data/hello.desktop.in:4
msgid "Greetings"
msgstr "Salutations"

#: data/hello.desktop.in:6
msgid "hello"
msgstr ""

#: data/hello.desktop.in:9
msgid "hello.png"
msgstr ""

The packaging activities are practically the same as the one in [autotools-multi].

You can find more i18n examples in [details] for

  • the POSIX shell script with the Makefile (v=3.0),

  • the Python3 script with the distutils (v=3.1),

  • the C source with the Makefile.in + configure (v=3.2),

  • the C source with the Autotools (v=3.3), and

  • the C source with the CMake (v=3.4).

Details

Actual details of the examples presented and their variants can be obtained by the following.

How to get details
 $ apt-get source debmake-doc
 $ sudo apt-get install devscripts build-essentials
 $ sudo apt-get build-dep debmake-doc
 $ cd debmake-doc*
 $ make

Each directory with the -pkg[0-9] suffix contains the Debian packaging example.

  • emulated console command line activity log: the .log file

  • emulated console command line activity log (short): the .slog file

  • snapshot source tree image after the debmake command: the debmake directory

  • snapshot source tree image after the properly packaging: the packge directory

  • snapshot source tree image after the debuild command: the test directory

debmake(1) manpage

NAME

debmake - program to make the Debian source package

SYNOPSIS

debmake [-h] [-c | -k] [-n | -a package-version.orig.tar.gz | -d | -t ] [-p package] [-u version] [-r revision] [-z extension] [-b "binarypackage, …]" [-e foo@example.org] [-f "firstname lastname"] [-i "buildtool" | -j] [-l license_file] [-m] [-o file] [-q] [-s] [-v] [-w "addon, …"] [-x [01234]] [-y] [-P] [-T]

DESCRIPTION

debmake helps to build the Debian package from the upstream source. Normally, this is done as follows:

  • The upstream tarball is downloaded as the package-version.tar.gz file.

  • It is untared to create many files under the package-version/ directory.

  • debmake is invoked in the package-version/ directory possibly without any arguments.

  • Files in the package-version/debian/ directory are manually adjusted.

  • dpkg-buildpackage (usually from its wrapper debuild or pdebuild) is invoked in the package-version/ directory to make debian packages.

Make sure to protect the arguments of the -b, -f, -l, and -w options from the shell interference by quoting them properly.

optional arguments:

-h, --help

show this help message and exit.

-c, --copyright

scan source for copyright+license text and exit.

  • -c: sinple output style

  • -cc: normal output style (similar to the debian/copyright file)

  • -ccc: debug output style

-k, --kludge

compare the debian/copyright file with the source and exit.

The debian/copyright file must be organized to list the generic file patterns before the specific exceptions.

  • -k: basic output style

  • -kk: verbose output style

-n, --native

make a native Debian source package without .orig.tar.gz. This makes the “3.0 (native)” format package.

If you are thinking to package a Debian specific source tree with debian/* in it into a native Debian package, please think otherwise. You can use “debmake -d -i debuild” or “debmake -t -i debuild” to make the “3.0 (quilt)” format non-native Debian package. The only difference is that the debian/changelog file must use the non-native version scheme: version-revision. The non-native package is more friendly to the downstream distributions.

-a package-version.tar.gz, --archive package-version.tar.gz

use the upstream source tarball directly. (-p, -u, -z: overridden)

The upstream tarball may be specified as package_version.orig.tar.gz and tar.gz for all cases may be tar.bz2, or tar.xz.

If the specified upstream tarball name contains uppercase letters, the Debian package name is generated by converting them to lowercase letters.

If the specified argument is the URL (http://, https://, or ftp://) to the upstream tarball, the upstream tarball is downloaded from the URL using wget or curl.

-d, --dist

run “make dist” equivalent first to generate upstream tarball and use it.

debmake -d” is designed to run in the package/ directory hosting the upstream VCS with the build system supporting “make dist” equivalents. (automake/autoconf, Python distutils, …)

-t, --tar

run “tar” to generate upstream tarball and use it

debmake -t” is designed to run in the package/ directory hosting the upstream VCS. Unless you provide the upstream version with the -u option or with the debian/changelog file, a snapshot upstream version is generated in the 0~%y%m%d%H%M format, e.g., 0~1403012359, from the UTC date and time. The generated tarball excludes the debian/ directory found in the upstream VCS. (It also excludes typical VCS directories: .git/ .hg/ .svn/ .CVS/)

-p package, --package package

set the Debian package name.

-u version, --upstreamversion version

set the upstream package version.

-r revision, --revision revision

set the Debian package revision.

-z extension, --targz extension

set the tarball type, extension=(tar.gz|tar.bz2|tar.xz) (alias: z, b, x)

-b "binarypackage[:type],…", --binaryspec "binarypackage[:type],…"

set binary package specs by the comma separated list of binarypackage:type pairs, e.g., in full form “foo:bin,foo-doc:doc,libfoo1:lib,libfoo1-dbg:dbg,libfoo-dev:dev” or in short form “,-doc,libfoo1,libfoo1-dbg, libfoo-dev”.

Here, binarypackage is the binary package name; and optional type is chosen from the following type values:

  • bin: C/C++ compiled ELF binary code package (any, foreign) (default, alias: "", i.e., null-string)

  • data: Data (fonts, graphics, …) package (all, foreign) (alias: da)

  • dbg: Debug symbol package (any, same) (alias: db)

  • dev: Library development package (any, same) (alias: de)

  • doc: Documentation package (all, foreign) (alias: do)

  • lib: Library package (any, same) (alias: l)

  • perl: Perl script package (all, foreign) (alias: pl)

  • python: Python script package (all, foreign) (alias: py)

  • python3: Python3 script package (all, foreign) (alias: py3)

  • ruby: Ruby script package (all, foreign) (alias: rb)

  • script: Shell script package (all, foreign) (alias: sh)

The pair values in the parentheses, such as (any, foreign), are the Architecture and Multi-Arch stanza values set in the debian/control file.

In many cases, the debmake command makes good guesses for type from binarypackage. If type is not obvious, type is set to bin. For example, libfoo sets type to lib, and font-bar sets type to data, …

If the source tree contents do not match settings for type, debmake warns you.

-e foo@example.org, --email foo@example.org

set e-mail address.

The default is taken from the value of the environment variable $DEBEMAIL.

-f "firstname lastname", --fullname "firstname lastname"

set the fullname.

The default is taken from the value of the environment variable $DEBFULLNAME.

-i "buildtool", --invoke "buildtool"

invoke "buildtool" at the end of execution. buildtool may be “dpkg-buildpackage”, “debuild”, “pdebuild”, “pdebuild --pbuilder cowbuilder”, etc..

The default is not to execute any program.

-j, --judge

run dpkg-depcheck to judge build dependencies and identify file paths. Log files are in the parent directory.

  • package.build-dep.log: Log file for dpkg-depcheck.

  • package.install.log: Log file recording files in the debian/tmp directory.

-l "license_file,…", --license "license_file,…"

add formatted license text to the end of the debian/copyright file holding license scan results

The default is add COPYING and LICENSE and license_file needs to list only the additional file names all separated by “,”.

-m, --monoarch

force packages to be non-multiarch.

-o file, --option file

read optional parameters from the file. (This is not for everyday use.)

The file is sourced as the Python3 code at the end of para.py. For example, the package description can be specified by the following file.

para['desc'] = 'program short description'
para['desc_long'] = '''\
 program long description which you wish to include.
 .
 Empty line is space + .
 You keep going on ...
'''
-q, --quitearly

quit early before creating files in the debian/ directory.

-s, --spec

use upstream spec (setup.py for Python, etc.) for the package description.

-v, --version

show version information.

-w "addon,…", --with "addon,…"

add extra arguments to the --with option of the dh(1) command as addon in debian/rules.

The addon values are listed all separated by “,”, e.g., “-w "python2,autoreconf"”.

For Autotools based packages, setting autoreconf as addon forces to run “autoreconf -i -v -f” for every package building. Otherwise, autotools-dev as addon is used as default.

For Autotools based packages, if they install Python programs, python2 as addon is needed for packages with “compat < 9” since this is non-obvious. But for setup.py based packages, python2 as addon is not needed since this is obvious and it is automatically set for the dh(1) command by the debmake command when it is required.

-x n, --extra n

generate extra configuration files as templates.

The number n changes which configuration templates are generated.

  • -x0: bare minimum configuration files. (default if these files exist already)

  • -x1: ,, + desirable configuration files. (default for new packages)

  • -x2: ,, + interesting configuration files. (recommended for experts, multi binary aware)

  • -x3: ,, + unusual configuration template files with the extra .ex suffix to ease their removal. (recommended for new users) To use these as configuration files, rename their file names into ones without the .ex suffix.

  • -x4: ,, + copyright file examples.

-y, --yes

“force yes” for all prompts. (without option: “ask [Y/n]”; doubled option: “force no”)

-P, --pedantic

pedantically check auto-generated files.

-T, --tutorial

output tutorial comment lines in template files.

EXAMPLES

For a well behaving source, you can build a good-for-local-use installable single Debian binary package easily with one command. Test install of such a package generated in this way offers a good alternative to traditional “make install” to the /usr/local directory since the Debian package can be removed cleanly by the “dpkg -P …” command. Here are some examples of how to build such test packages. (These should work in most cases. If the -d does not work, try -t instead.)

For a typical C program source tree packaged with autoconf/automake:

  • debmake -d -i debuild

For a typical python module source tree:

  • debmake -s -d -b":python" -i debuild

For a typical python module in the package-version.tar.gz archive:

  • debmake -s -a package-version.tar.gz -b":python" -i debuild

For a typical perl module in the Package-version.tar.gz archive:

  • debmake -a Package-version.tar.gz -b":perl" -i debuild

HELPER PACKAGES

Packaging may require installation of some additional specialty helper packages.

  • Python3 program may require the dh-python package.

  • Autotools (Autoconf + Automake) build system may require autotools-dev or dh-autoreconf package.

  • Ruby program may require the gem2deb package.

  • Java program may require the javahelper package.

  • Gnome programs may require the gobject-introspection package.

  • etc.

CAVEAT

debmake is meant to provide template files for the package maintainer to work on. Comment lines started by # contain the tutorial text. You must remove or edit such comment lines before uploading to the Debian archive.

There are some limitations for what characters may be used as a part of the Debian package. The most notable limitation is the prohibition of uppercase letters in the package name. Here is the summary in the regular expression.

  • Upstream package name (-p): [-+.a-z0-9]{2,}

  • Binary package name (-b): [-+.a-z0-9]{2,}

  • Upstream version (-u): [0-9][-+.:~a-z0-9A-Z]*

  • Debian revision (-r): [0-9][+.~a-z0-9A-Z]*

See the exact definition in Chapter 5 - Control files and their fields of the “Debian Policy Manual”.

DEBUG

The character set in the environment variable $DEBUG determines the logging output level.

  • i: print information

  • p: list all global parameters

  • d: list parsed parameters for all binary packages

  • f: input filename for the copyright scan

  • y: year/name split of copyright line

  • s: line scanner for format_state

  • b: content_state scan loop: begin-loop

  • m: content_state scan loop: after regex match

  • e: content_state scan loop: end-loop

  • c: print copyright section text

  • l: print license section text

  • a: print author/translator section text

  • k: sort key for debian/copyright stanza

  • n: scan result of debian/copyright (“debmake -k”)

Use this as:

 $ DEBUG=pdfbmeclak debmake ...

AUTHOR

Copyright © 2014-2015 Osamu Aoki <osamu@debian.org>

LICENSE

MIT License

SEE ALSO

The debmake-doc package provides the “Guide for Debian Maintainers” in the plain text, HTML and PDF formats under the /usr/share/doc/debmake-doc/ directory.

Also, please read the original Debian New Maintainers’ Guide provided by the the maint-guide package.

See also dpkg-source(1), deb-control(5), debhelper(7), dh(1), dpkg-buildpackage(1), debuild(1), quilt(1), dpkg-depcheck(1), pdebuild(1), pbuilder(8), cowbuilder(8), gbp-buildpackage(1), gbp-pq(1), and git-pbuilder(1) manpages.