Debmake tutorial

Preface

The debmake command is a helper script to generate Debian packaging files.

The debmake command is intended to replace functions offered historically by deb-make
[This new debmake package starts its version from 4.0 to avoid version overlaps with its predecessor provided the deb-make command.]
and dh_make commands. Its features include:

keep pre-existing Debian package configuration files untouched
use of dh syntax under the new debhelper (> 9.0) package
- extensive check of copyright for DEP-5 (with licensecheck(1) and more)
- substvar supports for binary packages
- support of compiler hardening options
easy packaging command line UI supporting
- non-stop execution with clean results
- direct operation on the tarball archive
- direct operation on the source tree from VCS
- the multiarch Debian package
- the multi binary Debian package
- the non-native Debian packages from the VCS snapshot
- seamless work with debuild, pdebuild, etc.

Note	I wrote this debmake command because there was no easy command like "python setup.py bdist_deb" to create the Debian binary package. Now "debmake -d -s -b":python" -i debuild" does the job for me.

I will describe the following to get you started with the debmake command.

Quick guide for the debmake command
- This should be enough for you to get started with the debmake command, if you already know the similar dh_make command.
- Just browse this section first and come back later, if you are new to the Debian packaging.
Top down view of the Debian packaging
- A rewrite in progress of the “Debian New Maintainers' Guide” for the debmake command.
Bottom up tutorial for the Debian packaging
- Step-by-step examples of various packaging cases using simple model packages.
Appendix: the debmake(1) manpage.

The /usr/share/doc/debmake/examples.tar.xz tarball has the sources used for testing the debmake command and creating the examples in this document.

Caution

This document focuses to explain how to make a working set of installable Debian binary packages from the upstream source. Much more details need to be addressed before uploading the package to the Debian archive.

Please read the basic Debian documentations together with this manual to generate perfect Debian packages.

“Debian Policy Manual” — "must follow" documentation (http://www.debian.org/doc/devel-manuals#policy)
“Debian Developer’s Reference” — "best practice" documentation (http://www.debian.org/doc/devel-manuals#devref)
“Debian New Maintainers' Guide” — "tutorial" documentation (http://www.debian.org/doc/devel-manuals#maint-guide)
“Introduction to Debian packaging” — "tutorial" documentation (http://www.debian.org/doc/devel-manuals#packaging-tutorial)

Tip	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 while reading this tutorial.

Quick guide

This quick guide should be enough for you to get started with the debmake command, if you already know the Debian packaging with the dh_make command.

If you are new to the Debian packaging, do not worry about the details and get the big picture instead. The more detailed tutorial follows this section. There is also the debmake manpage which explains all the command options. It is included here in the appendix.

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.

debmake

The debmake command is the helper script
[I am prejudiced.]
for the Debian packaging.

It makes template files for the Debian packaging in the upstream source based on the type (the -b option).
- Use bin as the fallback type for the compiled program without its own type.
- Use script as the fallback type for the interpreted program without its own type.
It always sets most of the obvious option states and values to reasonable defaults.
- It aims to address typical packaging situation (90% of cases) only.
It always prepares to build the source for the multiarch package, unless -m option is explicitly specified.
It always prepares to build the non-native Debian package with the "3.0 (quilt)" format, unless -n option is explicitly specified.
It delegates most of the heavy lifting to its back-end packages: debhelper, dpkg-dev, devscripts, etc.
It can integrate the whole packaging process from the source archive to the binary package.
- It has the -a option to make it work directly with the tarball.
- It has the -t and -d options to make it work well with the snapshot source in VCS. These options also allow to make the non-native Debian package from the VCS source tree with the package-version/debian/ directory. Please note, the non-native Debian package is the normal Debian package.
- It has the -b option to make it work with various cases of Debian binary packages.
- It has the -i option to run the debuild command as its subprocess.

Tip	Make sure to protect the arguments of the -b, -f, -l, and -w options from the shell interference by quoting them properly.

Basics

Let’s consider a simple C source following the GNU Coding Standards and FHS, package-1.0.tar.gz.

The Debian packaging of this package-1.0.tar.gz into a single binary package can be done with the debmake command as follows.

 $ tar -xvzf package-1.0.tar.gz
 $ cd package-1.0
 $ debmake
 $ debuild

Since manual adjustments of configuration files are skipped, the generated package has problems like description of this autogenerated package lacks meaningful contents, etc. But this is still a functioning binary package which can be managed by the dpkg command.

Tip	The debuild command used to make Debian binary packages from the source package in examples may be substituted by the equivalent commands such as pdebuild run with the cowbuilder back-end.

The -x option

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

The debmake command generates more template files with the larger argument number of the -x option.
The debmake command is normally invoked without -x option and it assumes its -x option as follows:
- -x0 : for the previously Debianized source
  - A source tree with any one of the 4 required specification files is considered as Debianized.
- -x1 : for the new single binary package
- -x2 : for the new multi binary package
The novice users may use -x3 option for learning.
- With -x3, even unusual configuration template files are generated with the extra .ex suffix.
See [emptypkg] for the cherry-picking of the template files.

Note	None of the existing configuration files are modified by 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 [basics] 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	The debuild command may be substituted by the equivalent commands such as pdebuild etc.

Binary package

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:

The -b option syntax

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 guess 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 does 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

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 [basics] 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.so → libfoo.so.1

Note	If any dbg type packages are to be generated, they should be made for all bin and lib type packages.

Python module

You can generate a 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.

With the -s option, the package description is copied from the Python package.

Upstream snapshot

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

I call this Debian non-native binary package building scheme using the "debmake -t -i debuild" command as the quasi-native Debian package scheme since it looks like the Debian native binary package building scheme by 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.

Multi binary package

The generation of the functional multi binary package always requires extra manual works than that of the functional single binary package.

The Debian packaging of the same package-1.0.tar.gz (see [basics]) into a multi binary package can be done with the debmake command as follows.

 $ debmake -j -a package-1.0.tar.gz

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
 $ debmake -b"package1:type1, ..." -a package-1.0.tar.gz
 $ cd package-1.0

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.

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

Check copyright

The the debmake command can make a summary of the copyright and license for the entire source treeto the standard output. It also uses the licensecheck command.

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

Top down tutorial

Debian package

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

The Debian binary package is an 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.

Some people promote to package even programs which have been written especially for Debian in the non-native package format with the above workflow while generating the required tarball without debian/* files by oneself in advance. They claim that the use of non-native package format eases communication with the downstream distributions.

Debian packaging work flow

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

It can be summarized in 5 steps as follows.

The upstream tarball is downloaded as the package-version.tar.gz file.
The upstream tarball is untared to create many files under the package-version/ directory.
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.
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 (go back to see [quick]).
  - 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”.
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 package by invoking the debian/rules script.
- The current directory is set as: $(CURDIR)=/path/to/package-version/
- Create the Debian source package in "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

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.

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 “Debian Policy Manual”.

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

In order to manage these 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.]

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 need to make sure that the upgrade works properly by renaming the upstream source to hello-0.9.12~rc99.tar.gz.

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 : when building a single binary package, binarypackage.
- $(DESTDIR)=debian/tmp : when building multiple binary packages.

The dh command

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

Simple debian/rules

Thanks to this abstraction of the dh command
[This simplicity is available since the debhelper version 7. This document assumes that the debhelper version 9 or newer is used.]
, the Debian policy compliant debian/rules file supporting all the required targets can be written as simple as:

Simple debian/rules:

%:
        dh $@

Essentially, this dh command calls all required dh_* commands at the right moment.

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 [simplepkg] 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 the multiarch customization (see [multiarch]).

debian/control

The debian/control file is the primary configuration file defining what binary packages are generated.

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

a set of stanza defining the split of the Debian binary package
a basic set of substvar used for each 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, and
List all file paths (relative to debian/tmp) in the corresponding debian/binarypackage.install files.

Please check examples in this document:

[multi-ex] (simple)
[multipkg] (detailed)

Substvar

The debian/control file also defines the package dependency in which the variable substitutions mechanism (substvar) may be used. 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

binNMU safe

For 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: any" foo package
- Depends: foo (== ${binary:Version})
"Architecture: any" package depends on "Architecture: all" bar package
- Depends: bar (== ${source:Version}
"Architecture: all" package depends on "Architecture: any" baz package
- Depends: baz (>= ${source:Version}) (no way for a safe dependency but good enough for most cases)

The debian/control file needs to be be manually adjusted. See binNMU.

The library package name

Let’s assume we have libfoo-7.0.tar.gz as the upstream of the libfoo library.

The binary pakage of the the libfoo library is usually named as libfoo7 with its SONAME major version.

When naming the -dev package, there are two approaches:

libfoo-dev if you support only one libfoo7 only.
- This is good enough if the number of dependent packages are limitted.
libfoo7-dev and libfoo8-dev if you support both libfoo7 and libfoo8.
- Both libfoo7-dev and libfoo8-dev provide libfoo-dev to enable the automatic library transition via binNMU.

See Chapter 8 - Shared libraries in the “Debian Policy Manual”.

debian/changelog

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

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

The debmake command creates the initial template file with the upstream package version and the Debian revision.

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

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.

debian/copyright

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

The debmake command creates the initial DEP-5 compatible template file by scanning the entire source tree with its internal regular expression. It also use nternal license checker to clasify each license text.
[(The licensecheck command from the devscripts package was referenced to make this internal checker.]

Note	If you find issues with this license checker, please file bug to the debmake package with the header part of the problematic file.

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 dh_bugfiles(1) and reportbug’s Features for Developers

It is the bug control file containing some directions for the bug reporting tool such as redirecting bug report to another package.

binarypackage.bug-presubj ^-x3

installed as usr/share/bug/binarypackage/presubj in binarypackage

See dh_bugfiles(1) and reportbug’s Features for Developers

The contents of this file are displayed to the user by the bug reporting tool.

binarypackage.bug-script ^-x3

installed as usr/share/bug/binarypackage or usr/share/bug/binarypackage/script in binarypackage

See dh_bugfiles(1) and reportbug’s Features for Developers

This is the script to be run by the bug reporting program for generating a bug report template.

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.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 function 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. 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 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 template files to make a manpage.

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 applied to the upstream source before building the source.

See dpkg-source(8), [quilt] and [modpkg].

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

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

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

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

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

Package customization

There are some upstream sources which does 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:

patches/* approach
debian/rules approach
debian/bianrypackage.* approach

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 -p1 patches for this.

The diff command
The dquilt command (alias of the quilt command, see [quilt])
The git command with the --format-patches option
The git-dpm command
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 and normalizing it by the dquilt command (see [quilt]). This is also needed for upgrading to the newer upstream source or importing the externally generated security patch.

 $ dquilt push; dquilt refresh
  ... (repeat)
 $ dquilt push; dquilt refresh
File series fully applied, ends at patch ...
 $ pop -a

See [modpkg] for example.

debian/rules approach

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

See [customrules].

debian/binarypackage.* approach

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

See [debianconf].

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.

setup the build system ("vim configure.ac Makefile.am" and "autoreconf -ivf")
configure the build system ("./configure")
build the source tree ("make")
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 step 2 to 4 at least. This is realized by the "dh $@ --with autotools-dev" command used in the debian/rules file.

The package maintainer wishes to take care step 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 and provides better porting supports.

Python distutils

Python distutils has 3 steps.

setup and configure the build system ("vim setup.py")
build the source tree ("python setup.py build")
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 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.

Debugging information

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

The debugging information can be packaged separately as the debug packege using the "dh_strip --dbg-package=package" command in the override_dh_strip: target of the debian/rules file.

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

6.7.9. Best practices for debug packages of the “Debian Developer’s Reference”.
18.2 Debugging Information in Separate Files in the “Debugging with gdb”
dh_strip(1)
strip(1)
readelf(1)
objcopy(1)
Debian wiki DebugPackage
Debian wiki AutomaticDebugPackages

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 -x" command.
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 -x" 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 in the “Debian Policy Manual”
dh_makeshlibs(1)
dpkg-gensymbols(1)
dpkg-shlibdeps(1)
deb-symbols(5)

Yous should also check:

Debian wiki UsingSymbolsFiles
[librarypkg]

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

Multiarch

The multiarch support for cross-architecture installation of binary packages (particularly i386<->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.

Ubuntu wiki MultiarchSpec (upstream)
Debian wiki Multiarch/Implementation (Debian situation)

It uses the triplet such as i386-linux-gnu and x86_64-linux-gnu for the install path of shared libraries. The actual triplet path is dynamically set into $(DEB_HOST_MULTIARCH) value by dpkg-architecture for each build. For example, the path to install multiarch libraries are changed as follows. (Old special purpose library paths such as /lib32/ and /lib64/ are not used any more.)

Old 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 other packages with non-supported build systems, you need to manually adjust the install path as follows.

Call "DEB_HOST_MULTIARCH ?= $(shell dpkg-architecture -qDEB_HOST_MULTIARCH)" in the debian/rules file to set the DEB_HOST_MULTIARCH variable.
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 retargeting 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.

Please note that --libexecdir 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 default is /usr/lib/.

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.

Debian wiki Hardening
Debian wiki Hardening Walkthrough

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 [singlepkg]).

Tips

Basic tool list.

Please read the Overview of Debian Maintainer Tools in the “Debian Developer’s Reference”.

Few notes (Need BTS)

git-builpackage instead of cvs-buildpackage
cowbuilder is normally used with pbuilder

Package history

The best practice for tracking previous package history is as follows.

Search all previous Debian source package versions for the intended package at the snapshot.debian.org archive.
Use the dget command with the URL to the *.dsc file to download them.
Use the git-import-dscs command with the --pristine-tar option to import all versions at once.

UTF-8 conversion

If upstream documents are encoded in old encoding schemes, converting them to UTF-8 is a good idea.

Use iconv(1) 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=en_US.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.

Deb source 3.0

ProjectsDebSrc3.0

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.

Bottom up tutorial

Tool setups

Although these are not necessary the requirement, basic tool setups are described as below for us to share the common baseline working environment.

Setting up bash

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

Let’s set up these by adding the following lines to ~/.bashrc footnote[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

Setting up mc

The mc 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 by using the dpkg-deb command as its back-end. Let’s set up its easy chdir support as follows.

Add to the ~/.bashrc file

# mc related
export HISTCONTROL=ignoreboth
. /usr/lib/mc/mc.sh

Setting up quilt

The program quilt offers a basic method for recording modifications to the upstream source for the Debian packaging. It’s useful to have a slightly customized default suitable for the Debian packaging 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.

Setting up devscripts

The debuild command runs the dpkg-buildpackage and lintian commands under the current build environment with the sanitized environment variables to create all the files necessary for uploading a Debian package.

Let’s create ~/.devscripts as follows.

DEBSIGN_KEYID='Your_GPG_keyID'
DEBUILD_LINTIAN_OPTS=-i -I --show-overrides

With these, packages are signed by your specified GPG key ID (good for sponsoring packages) and checked in detail by the lintian command.

Setting up pbuilder + cowbuilder

The pbuilder package provides the clean room (chroot) build environment. The cowbuilder package boosts its processing speed. Let’s customize these packages to make the pdebuild command to run with the cowbuilder and *lintian commands.

Let’s create ~/.pbuilderrc as follows.

AUTO_DEBSIGN=${AUTO_DEBSIGN:-no}
HOOKDIR=/var/cache/pbuilder/hooks
PDEBUILD_PBUILDER=cowbuilder
BUILDRESULT=../

Let’s create a hook script /var/cache/pbuilder/hooks/B90lintian as follows.

#!/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 +++"

Setting up git

You may wish to set several global configuration in ~/.gitconfig such as your name and email address used by Git by the following.

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

If you are too used to CVS or Subversion commands, you may wish to set several command aliases by the following.

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

You can check your global configuration by the following.

$ git config --global --list

Tip	It is essential to use the gitk command to work with the Git repository.

Setting up git-buildpackage

You may wish to set several global configuration 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

Setting up chroot

The pbuilder, pdebuild, git-pbuilder, and gbp commands used after installing and configuring the pbuilder, cowbuilder, and git-buildpackage packages as described above offer us useful environments to build packages under the chroot.

A clean sid distribution chroot environment can be used as follows.

The chroot filesystem creation command for the sid distribution
- 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
- gbp buildpackage

An arbitrary dist distribution environment can be used as follows.

The chroot filesystem creation command for the dist distribution
- pbuilder create --distribution dist
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
- gbp buildpackage --git-dist=dist

You need to keep these chroot environments up-to-date using the following chupgrade command.

The chupgrade command

#!/bin/sh
# update original tree (not the COW copy)
DIST=$1
ARCH=$2
COW="/var/cache/pbuilder"
if [ "$DIST" = "" ] || [ "$DIST" = "sid" ] ; then
    COW="${COW}/base"
else
    COW="${COW}/base-${DIST}"
fi
if [ "$ARCH" = "" ] || [ "$ARCH" = "amd64" ] ; then
    COW="${COW}.cow"
else
    COW="${COW}-${ARCH}.cow"
fi
echo "update $COW"
sudo cowbuilder --update --basepath $COW

You can create a customized chroot environment by logging into the master chroot system using the following chlogin command to a copy of some distribution environment. (The chlogin command is essentially a wrapper command of the chroot command. It also mounts required console device etc.)

The chlogin command

#!/bin/sh
# login to chroot to update original tree (not the COW copy)
DIST=$1
ARCH=$2
COW="/var/cache/pbuilder"
if [ "$DIST" = "" ] || [ "$DIST" = "sid" ] ; then
    COW="${COW}/base"
else
    COW="${COW}/${DIST}"
fi
if [ "$ARCH" = "" ] || [ "$ARCH" = "amd64" ] ; then
    COW="${COW}.cow"
else
    COW="${COW}-${ARCH}.cow"
fi
echo "login to $COW (overwrite non-COW mode)"
sudo pbuilder --login --no-targz --buildplace $COW

If you wish to build a stable security update package etc. under a custom environment with some pre-loaded packages, this chlogin command is quite handy.

Single binary package

For the case of creating a single binary Debian package from the $(DESTDIR) and Filesystem Hierarchy Standard (FHS) supporting source, the packaging process can be practically automatic if you only wish to make it for your local use and do not worry about details of the Debian Policy.

Let’s assume you have a simple upstream source tarball hello-c-1.0.tar.gz.

 $ wget http://www.example.org/download/hello-c-1.0.tar.gz
 ...

Let’s untar it.

 $ tar -xvzmf hello-c-1.0.tar.gz
hello-c-1.0/
hello-c-1.0/Makefile
hello-c-1.0/hello.c

Let’s inspect files.

 $ tree
.
|-- hello-c-1.0
|   |-- hello.c
|   `-- Makefile
`-- hello-c-1.0.tar.gz

1 directory, 3 files

Makefile supports $(DESTDIR).

 $ cat hello-c-1.0/Makefile
all: hello

hello: hello.c
        gcc -Wall -o hello hello.c

install: hello
        install -D hello $(DESTDIR)/usr/bin/hello

clean:
        -rm -f hello

distclean: clean

.PHONY: all install clean distclean

The C source hello.c is a very simple one.

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

You create a non-native Debian package source tree from this upstream example using the debmake command.

 $ cd hello-c-1.0
 $ debmake
I: set parameters
I: sanity check of parameters
I: pkg="hello-c", ver="1.0", rev="1"
I: *** start packaging in "hello-c-1.0". ***
I: provide hello-c_1.0.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf hello-c-1.0.tar.gz hello-c_1.0.orig.tar.gz
I: pwd = "/path/to/hello-c-1.0"
I: parse binary package settings:
I: binary package=hello-c Type=bin / Arch=any M-A=foreign
I: analyze the source tree
I: build_type = make
I: 100 %, ext = c
I: make debian/* template files
I: single binary package
I: debmake -x "1" ...
I: creating => debian/control
I: creating => debian/copyright
I: creating => debian/changelog
I: creating => debian/rules
I: creating => debian/compat
I: creating => debian/watch
I: creating => debian/README.Debian
I: creating => debian/source/format
I: creating => debian/source/local-options
I: creating => debian/patches/series
I: run "debmake -x2" to get more template files
I: $ wrap-and-sort

Let’s inspect generated template files.

debian/rules:

 $ cat debian/rules
#!/usr/bin/make -f
# See debhelper(7) (uncomment to enable)
# output every command that modifies files on the build system.
#DH_VERBOSE = 1

# In case you want to add more flags to the defaults, use
# the followings to harden via compiler options
# see FEATURE AREAS in dpkg-buildflags(1))
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
# see ENVIRONMENT in dpkg-buildflags(1))
# package maintainers to append CFLAGS
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
# package maintainers to append LDFLAGS
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed



# main packaging script based on dh7 syntax
%:
        dh $@

# debmake generated override targets
# See dpkg-architecture(1) to set multiarch path as needed.
#DEB_HOST_MULTIARCH ?= $(shell dpkg-architecture -qDEB_HOST_MULTIARCH)
#
# This is example for Cmake (See http://bugs.debian.org/641051 )
#override_dh_auto_configure:
#       dh_auto_configure -- \
#       -DCMAKE_LIBRARY_PATH=$(DEB_HOST_MULTIARCH)

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

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

debian/control:

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

Package: hello-c
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.
 .
 ===== This comes from the unmodified template file =====
 .
 Please edit this template file (debian/control) and other package files...
 (debian/*) to make them meet all the requirements of the Debian Policy
 before uploading this package to the Debian archive.
 .
 See
  * http://www.debian.org/doc/manuals/maint-guide/dreq.en.html#control
  * http://www.debian.org/doc/manuals/developers-reference/best-pkging-p...
 .
 The synopsis description at the top should be about 60 characters and
 written as a phrase.  No extra capital letters or a final period.  No
 articles — "a", "an", or "the".
 .
 The package description for general-purpose applications should be
 written for a less technical user.  This means that we should avoid
 jargon.  GNOME or KDE is fine but GTK+ is probably not.
 .
 Use the canonical forms of words:
  * Use X Window System, X11, or X; not X Windows, X-Windows, or X Windo...
  * Use GTK+, not GTK or gtk.
  * Use GNOME, not Gnome.
  * Use PostScript, not Postscript or postscript.

Please note that the debmake command is run with the -x21 option as the default for the new single binary package.

Since this is the ELF binary executable package (type=bin), it is set to "Architecture: any" and "Multi-Arch: foreign". Also, required substvar parameters are set as "Depends: ${shlibs:Depends}, ${misc:Depends}" by the debmake command.

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

There are several other template files under the debian/ directory.

The source tree after the basic debmake execution.

 $ cd ..
 $ tree
.
|-- hello-c-1.0
|   |-- debian
|   |   |-- changelog
|   |   |-- compat
|   |   |-- control
|   |   |-- copyright
|   |   |-- patches
|   |   |   `-- series
|   |   |-- README.Debian
|   |   |-- rules
|   |   |-- source
|   |   |   |-- format
|   |   |   `-- local-options
|   |   `-- watch
|   |-- hello.c
|   `-- Makefile
|-- hello-c_1.0.orig.tar.gz -> hello-c-1.0.tar.gz
`-- hello-c-1.0.tar.gz

4 directories, 14 files

For the proper packaging, you are required to make further modification here.

For learning purpose, let’s leave such details and move on. You can create a non-native Debian package using the debuild command (or its equivalents) in this source tree.

 $ cd hello-c-1.0
 $ debuild
 dpkg-buildpackage -rfakeroot -D -us -uc -I -i
 ...
 fakeroot debian/rules clean
dh clean
 ...
 debian/rules build
dh build
 ...
 fakeroot debian/rules binary
dh binary
 ...
Finished running lintian.

Let’s inspect the result.

The generated files of version 1.0 by the debuild command:

 $ cd ..
 $ tree -L 1
.
|-- hello-c-1.0
|-- hello-c_1.0-1_amd64.build
|-- hello-c_1.0-1_amd64.changes
|-- hello-c_1.0-1_amd64.deb
|-- hello-c_1.0-1.debian.tar.xz
|-- hello-c_1.0-1.dsc
|-- hello-c_1.0.orig.tar.gz -> hello-c-1.0.tar.gz
`-- hello-c-1.0.tar.gz

1 directory, 7 files

The source package contents of version 1.0:

 $ tar -tJf hello-c_1.0-1.debian.tar.xz
debian/
debian/compat
debian/changelog
debian/watch
debian/control
debian/copyright
debian/README.Debian
debian/rules
debian/source/
debian/source/format
debian/patches/
debian/patches/series
 $ tar -tzf hello-c-1.0.tar.gz
hello-c-1.0/
hello-c-1.0/Makefile
hello-c-1.0/hello.c

The binary package contents of version 1.0:

 $ dpkg -c hello-c_1.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/hello-c/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/changelog.Debian.gz

Modifications

Let’s assume we have an older upstream source tarball hello-c-0.9.tar.gz. The Makefile of version 0.9 installs its binary to the fixed location /usr/local/bin/hello and does not support $(DESTDIR) like the one in the upstream source tarball hello-c-1.0.tar.gz.

There are several methods to prepare the -p1 patch needed for applying modifications to this 0.9 upstream source.

The diff command
The dquilt command (alias of the quilt command)
The git command with the --format-patches option.
The git-dpm command.
…

Patch file by the dquilt command

Here we show the method with the dquilt command.

The packaging procedure is the same as that of version 1.0 up to running the debmake command.

 $ cd hello-c-0.9
 $ debmake
I: set parameters
I: sanity check of parameters
I: pkg="hello-c", ver="0.9", rev="1"
 ...
 ... (snip)
 ...
I: run "debmake -x2" to get more template files
I: $ wrap-and-sort

The "dquilt new …" command sets the name of the patch.

The "dquilt add …" command sets the files to be modified.

 $ dquilt new 0001-destdir.patch
Patch 0001-destdir.patch is now on top
 $ dquilt add Makefile
File Makefile added to patch 0001-destdir.patch
 $ cat Makefile
all: hello

hello: hello.c
        gcc -Wall -o hello hello.c

install: hello
        install -D hello /usr/local/bin/hello

clean:
        -rm -f hello

distclean: clean

.PHONY: all install clean distclean

The vim command edits the Makefile to be modified to support $(DESTDIR)..

The "dquilt refresh …" command records the modification as the -p1 patch in the debian/patches/ directory.

 $ vim Makefile
 ...
 $ cat Makefile
all: hello

hello: hello.c
        gcc -Wall -o hello hello.c

install: hello
        install -D hello $(DESTDIR)/usr/bin/hello

clean:
        -rm -f hello

distclean: clean

.PHONY: all install clean distclean
 $ dquilt refresh
Refreshed patch 0001-destdir.patch
 $ cat debian/patches/0001-destdir.patch
--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@
        gcc -Wall -o hello hello.c

 install: hello
-       install -D hello /usr/local/bin/hello
+       install -D hello $(DESTDIR)/usr/bin/hello

 clean:
        -rm -f hello

The "dquilt header -e …" command adds the DEP-3: Patch Tagging Guidelines compatible patch header.

The "dquilt pop -a" command removes all applied patches from the source.

 $ dquilt header -e
 ...
 $ cat debian/patches/0001-destdir.patch
From: Foo Bar <foo@example.org>
Description: make Makefile to support GNU coding standard
 $DESTDIR: debian/hello-c
 $prefix:  /usr/local -> /usr

--- a/Makefile
+++ b/Makefile
@@ -4,7 +4,7 @@
        gcc -Wall -o hello hello.c

 install: hello
-       install -D hello /usr/local/bin/hello
+       install -D hello $(DESTDIR)/usr/bin/hello

 clean:
        -rm -f hello
 $ dquilt pop -a
Removing patch 0001-destdir.patch
Restoring Makefile

No patches applied
 $ cat debian/patches/series
# The patch files of the -p1 format included in the debian/patches direc...
# are applied to the upstream source in the order listed below.
# This is manually managed by users with dquilt (quilt(1) wrapper) etc.
# Also this may be updated by dpkg-source(1) when making a package.
0001-destdir.patch

For the proper packaging, you are required to make further modification here.

For learning purpose, let’s leave such details and move on. You can create a non-native Debian package using the debuild command (or its equivalents) in this source tree.

 $ cd hello-c-0.9
 $ debuild
 dpkg-buildpackage -rfakeroot -D -us -uc -I -i
 ...
dpkg-source: info: applying 0001-destdir.patch
 fakeroot debian/rules clean
dh clean
 ...
 debian/rules build
dh build
 ...
 fakeroot debian/rules binary
dh binary
 ...
Finished running lintian.

Let’s inspect files.

The generated files of version 0.9 by the debuild command:

 $ cd ..
 $ tree -L 1
.
|-- hello-c-0.9
|-- hello-c_0.9-1_amd64.build
|-- hello-c_0.9-1_amd64.changes
|-- hello-c_0.9-1_amd64.deb
|-- hello-c_0.9-1.debian.tar.xz
|-- hello-c_0.9-1.dsc
|-- hello-c_0.9.orig.tar.gz -> hello-c-0.9.tar.gz
`-- hello-c-0.9.tar.gz

1 directory, 7 files

The source package contents of version 0.9:

 $ dpkg -c hello-c_0.9-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/hello-c/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/changelog.Debian.gz

The binary package contents of version 0.9:

 $ tar -tJf hello-c_0.9-1.debian.tar.xz
debian/
debian/compat
debian/changelog
debian/watch
debian/control
debian/copyright
debian/README.Debian
debian/rules
debian/source/
debian/source/format
debian/patches/
debian/patches/0001-destdir.patch
debian/patches/series
 $ tar -tzf hello-c-0.9.tar.gz
hello-c-0.9/
hello-c-0.9/Makefile
hello-c-0.9/hello.c

Cherry-pick templates

Although executing the debmake command with the larger -x[01234] option in the upstream source adds new template files without overwriting the existing ones, it tends to leave too many unused ones and is quite messy.

If you wish to get some template files, I recommend to do it as follows with an empty directory, e.g., package/.

 $ tree
.
`-- package

1 directory, 0 files

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

Let’s also use the "-t -u 0.0" options to make missing upstream tarball with a version 0.0.

 $ cd package
 $ debmake -t -u 0.0 -x4
 ...
I: debmake -x "4" ...
I: creating => debian/control
I: creating => debian/copyright
I: creating => debian/changelog
 ...
I: creating => debian/license-examples/Artistic-1.0
I: creating => debian/license-examples/Apache-2.0
I: creating => debian/license-examples/LGPL-3.0+
I: $ wrap-and-sort
I: upon return to the shell, current directory becomes /path/to/package
I: please execute "cd /path/to/package-0.0" before building the binary p...
I: with dpkg-buildpackage (or debuild, pdebuild, sbuild, ...).

Let’s inspect generated template files.

 $ cd ..
 $ tree
.
|-- package
|-- package-0.0
|   `-- debian
|       |-- changelog
|       |-- clean
|       |-- compat
|       |-- control
|       |-- copyright
|       |-- install
|       |-- license-examples
|       |   |-- Apache-2.0
|       |   |-- Artistic-1.0
|       |   |-- BSD-3-Clause
|       |   |-- GPL-2.0+
|       |   |-- GPL-3.0+
|       |   |-- LGPL-2.1+
|       |   |-- LGPL-3.0+
|       |   `-- MIT
|       |-- links
|       |-- manpage.1.ex
|       |-- manpage.asciidoc.ex
|       |-- manpage.sgml.ex
|       |-- manpage.xml.ex
|       |-- menu
|       |-- package.bug-control.ex
|       |-- package.bug-presubj.ex
|       |-- package.bug-script.ex
|       |-- package.conffiles.ex
|       |-- package.cron.daily.ex
|       |-- package.cron.d.ex
|       |-- package.cron.hourly.ex
|       |-- package.cron.monthly.ex
|       |-- package.cron.weekly.ex
|       |-- package.default.ex
|       |-- package.dirs.ex
|       |-- package.emacsen-install.ex
|       |-- package.emacsen-remove.ex
|       |-- package.emacsen-startup.ex
|       |-- package.init.ex
|       |-- package.lintian-overrides.ex
|       |-- package.service.ex
|       |-- package.tmpfile.ex
|       |-- package.upstrat.ex
|       |-- patches
|       |   `-- series
|       |-- postinst
|       |-- postrm
|       |-- preinst
|       |-- prerm
|       |-- README.Debian
|       |-- rules
|       |-- source
|       |   |-- format
|       |   `-- local-options
|       |-- source.lintian-overrides.ex
|       `-- watch
|-- package_0.0.orig.tar.gz -> package-0.0.tar.gz
`-- package-0.0.tar.gz

6 directories, 52 files

Now you can copy any of these generated template files in the package-0.0/debian/ directory to your package as needed.

Snapshot (simple)

Let’s consider an upstream source in the VCS and make a snapshot package from it.

Let’s inspect files.

VCS source tree

 $ tree
.
`-- hello-c
    |-- hello.c
    `-- Makefile

1 directory, 2 files

The source is the same one as [singlepkg] but the parent directory lacks the version part since this is the VCS directory.

You create a non-native Debian package source tree from the above upstream example using the debmake(1) command.

git and debmake

 $ cd hello-c
 $ git init
Initialized empty Git repository in /path/to/hello-c/.git/
 $ git add .
 $ git commit -m "initial commit"
[master (root-commit) d829cfe] initial commit
 2 files changed, 21 insertions(+)
 create mode 100644 Makefile
 create mode 100644 hello.c
 $ git checkout -b devel
Switched to a new branch 'devel'
 $ git branch
* devel
  master
 $ debmake -t
I: set parameters
I: sanity check of parameters
I: pkg="hello-c", ver="0~1403311544", rev="1"
I: make the upstream tarball with "tar --exclude=debian"
I: pwd = "/path/to/hello-c"
I: pwd = "/path/to"
I: $ rsync -aCv --link-dest=/path/to/hello-c hello-c/. hello-c-0~1403311...
sending incremental file list
created directory hello-c-0~1403311544

 ...
I: debmake -x "1" ...
 ...
I: run "debmake -x2" to get more template files
I: $ wrap-and-sort
I: upon return to the shell, current directory becomes /path/to/hello-c
I: please execute "cd /path/to/hello-c-0~1403311544" before building the...
I: with dpkg-buildpackage (or debuild, pdebuild, sbuild, ...).

Let’s inspect files.

 $ cd ..
 $ tree
.
|-- hello-c
|   |-- hello.c
|   `-- Makefile
|-- hello-c-0~1403311544
|   |-- debian
|   |   |-- changelog
|   |   |-- compat
|   |   |-- control
|   |   |-- copyright
|   |   |-- patches
|   |   |   `-- series
|   |   |-- README.Debian
|   |   |-- rules
|   |   |-- source
|   |   |   |-- format
|   |   |   `-- local-options
|   |   `-- watch
|   |-- hello.c
|   `-- Makefile
|-- hello-c_0~1403311544.orig.tar.gz -> hello-c-0~1403311544.tar.gz
`-- hello-c-0~1403311544.tar.gz

5 directories, 16 files

There are many files:

the snapshot upstream tarball: hello-0~1403311544.tar.gz (hello-c_0~1403311544.orig.tar.gz)
the snapshot upstream source tree with template files generated by the debmake command: hello-c-0~1403311544/*
the cleaned VCS directory: hello-c-0~1403311544/*

For the proper packaging, you are required to make further modification using these auto-generated template files in the hello-c-0~1403311544/debian directory. For learning purpose, let’s leave such details and move on. You can create a non-native Debian package using the debuild command (or its equivalent) in this source tree.

 $ cd hello-c-0~1403311544
 $ debuild
 dpkg-buildpackage -rfakeroot -D -us -uc -I -i
 ...
 fakeroot debian/rules clean
dh clean
 ...
 debian/rules build
dh build
 ...
 fakeroot debian/rules binary
dh binary
 ...
Finished running lintian.

Let’s inspect the result.

 $ cd ..
 $ tree -L 1
.
|-- hello-c
|-- hello-c-0~1403311544
|-- hello-c_0~1403311544-1_amd64.build
|-- hello-c_0~1403311544-1_amd64.changes
|-- hello-c_0~1403311544-1_amd64.deb
|-- hello-c_0~1403311544-1.debian.tar.xz
|-- hello-c_0~1403311544-1.dsc
|-- hello-c_0~1403311544.orig.tar.gz -> hello-c-0~1403311544.tar.gz
`-- hello-c-0~1403311544.tar.gz

2 directories, 7 files

 $ dpkg -c hello-c_0~1403311544-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/hello-c/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/changelog.Debian.gz

 $ tar -tJf hello-c_0~1403311544-1.debian.tar.xz
debian/
debian/compat
debian/changelog
debian/watch
debian/control
debian/copyright
debian/README.Debian
debian/rules
debian/source/
debian/source/format
debian/patches/
debian/patches/series
 $ tar -tzf hello-c-0~1403311544.tar.gz
hello-c-0~1403311544/
hello-c-0~1403311544/Makefile
hello-c-0~1403311544/hello.c

Your development branch holding the real upstream source tree is the devel branch.

The following will import generated Debian packages to master, upstream, and pristine-tar branches.

 $ cd hello-c
 $ git-import-dsc ../hello-c_0~1403311544-1.dsc  \
                  --pristine-tar --create-missing-branches
gbp:info: Tag upstream/0_1403311544 not found, importing Upstream tarbal...
gbp:info: Creating missing branch 'upstream'
pristine-tar: committed hello-c_0~1403311544.orig.tar.gz.delta to branch...
gbp:info: Version '0~1403311544-1' imported under 'hello-c'
 $ git branch
* devel
  master
  pristine-tar
  upstream
 $ gitk --all

The gitk command shows the VCS history nicely.

Snapshot (Autotools)

Let’s consider an upstream source in the VCS and make a snapshot package from it.

Let’s make this more fun to use the Autotools (=Autoconf + Automake) its build system where the upstream VCS does not contain auto-generated files while the distributed tarball has many auto-generated files.

Let’s inspect files.

VCS source tree

 $ tree
.
`-- vcsdir
    |-- configure.ac
    |-- hello.c
    `-- Makefile.am

1 directory, 3 files

There are minimalistic configuration files for Autotools.

configure.ac:

 $ cat vcsdir/configure.ac
#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.
AC_PREREQ([2.69])
AC_INIT([hello-c], [1.5], [foo@example.org])
AC_CONFIG_SRCDIR([hello.c])
AC_CONFIG_HEADERS([config.h])
# Manually added
AM_INIT_AUTOMAKE([foreign])
# Checks for programs.
AC_PROG_CC
AC_CONFIG_FILES([Makefile])
AC_OUTPUT

Makefile.am:

 $ cat vcsdir/Makefile.am
bin_PROGRAMS = hello
hello_SOURCES = hello.c

The C source hello.c is the same one as before.

You create a non-native Debian package source tree from the above upstream example using the debmake(1) command.

git and debmake

 $ cd vcsdir
 $ git init
Initialized empty Git repository in /path/to/vcsdir/.git/
 $ git add .
 $ git commit -m "initial commit"
[master (root-commit) 7488d5e] initial commit
 3 files changed, 21 insertions(+)
 create mode 100644 Makefile.am
 create mode 100644 configure.ac
 create mode 100644 hello.c
 $ git checkout -b devel
Switched to a new branch 'devel'
 $ git branch
* devel
  master
 $ debmake -d
I: set parameters
I: sanity check of parameters
I: pkg="", ver="", rev="1"
I: make the upstream tarball with "make dist" equivalents
I: pwd = "/path/to/vcsdir"
I: $ autoreconf -ivf && ./configure --prefix "/usr" && make distcheck
autoreconf: Entering directory `.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force
 ...
I: debmake -x "1" ...
 ...
I: run "debmake -x2" to get more template files
I: $ wrap-and-sort
I: upon return to the shell, current directory becomes /path/to/vcsdir
I: please execute "cd /path/to/hello-c-1.5" before building the binary p...
I: with dpkg-buildpackage (or debuild, pdebuild, sbuild, ...).

Let’s clean vcsdir/ since it has so many Autotools generated files.

 $ git clean -d -f -x
Removing .deps/
Removing Makefile
Removing Makefile.in
Removing aclocal.m4
Removing autom4te.cache/
Removing compile
Removing config.h
Removing config.h.in
Removing config.log
Removing config.status
Removing configure
Removing depcomp
Removing hello-c-1.5.tar.gz
Removing install-sh
Removing missing
Removing stamp-h1

Let’s inspect files.

 $ cd ..
 $ tree
.
|-- hello-c-1.5
|   |-- aclocal.m4
|   |-- compile
|   |-- config.h.in
|   |-- configure
|   |-- configure.ac
|   |-- debian
|   |   |-- changelog
|   |   |-- compat
|   |   |-- control
|   |   |-- copyright
|   |   |-- patches
|   |   |   `-- series
|   |   |-- README.Debian
|   |   |-- rules
|   |   |-- source
|   |   |   |-- format
|   |   |   `-- local-options
|   |   `-- watch
|   |-- depcomp
|   |-- hello.c
|   |-- install-sh
|   |-- Makefile.am
|   |-- Makefile.in
|   `-- missing
|-- hello-c_1.5.orig.tar.gz -> hello-c-1.5.tar.gz
|-- hello-c-1.5.tar.gz
`-- vcsdir
    |-- configure.ac
    |-- hello.c
    `-- Makefile.am

5 directories, 26 files

There are many files:

the snapshot upstream tarball: hello-1.5.tar.gz (hello-c_1.5.orig.tar.gz)
the snapshot upstream source tree with template files generated by the debmake command: hello-c-1.5/*
the cleaned VCS directory: vcsdir/*

For the proper packaging, you are required to make further modification using these auto-generated template files in the hello-c-1.5/debian directory. For learning purpose, let’s leave such details and move on. You can create a non-native Debian package using the debuild command (or its equivalent) in this source tree.

 $ cd hello-c-1.5
 $ debuild
 dpkg-buildpackage -rfakeroot -D -us -uc -I -i
 ...
 fakeroot debian/rules clean
dh clean --with "autotools-dev"
 ...
 debian/rules build
dh build --with "autotools-dev"
 ...
 fakeroot debian/rules binary
dh binary --with "autotools-dev"
 ...
Finished running lintian.

Let’s inspect the result.

 $ cd ..
 $ tree -L 1
.
|-- hello-c-1.5
|-- hello-c_1.5-1_amd64.build
|-- hello-c_1.5-1_amd64.changes
|-- hello-c_1.5-1_amd64.deb
|-- hello-c_1.5-1.debian.tar.xz
|-- hello-c_1.5-1.dsc
|-- hello-c_1.5.orig.tar.gz -> hello-c-1.5.tar.gz
|-- hello-c-1.5.tar.gz
`-- vcsdir

2 directories, 7 files

 $ dpkg -c hello-c_1.5-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/hello-c/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/changelog.Debian.gz

 $ tar -tJf hello-c_1.5-1.debian.tar.xz
debian/
debian/compat
debian/changelog
debian/watch
debian/control
debian/copyright
debian/README.Debian
debian/rules
debian/source/
debian/source/format
debian/patches/
debian/patches/series
 $ tar -tzf hello-c-1.5.tar.gz
hello-c-1.5/
hello-c-1.5/install-sh
hello-c-1.5/aclocal.m4
hello-c-1.5/Makefile.am
hello-c-1.5/depcomp
hello-c-1.5/configure.ac
hello-c-1.5/config.h.in
hello-c-1.5/compile
hello-c-1.5/Makefile.in
hello-c-1.5/missing
hello-c-1.5/configure
hello-c-1.5/hello.c

Your development branch holding the real upstream source tree is the devel branch.

The following will import generated Debian packages to master, upstream, and pristine-tar branches.

 $ cd vcsdir
 $ git-import-dsc ../hello-c_1.5-1.dsc  \
                  --pristine-tar --create-missing-branches
gbp:info: Tag upstream/1.5 not found, importing Upstream tarball
gbp:info: Creating missing branch 'upstream'
pristine-tar: committed hello-c_1.5.orig.tar.gz.delta to branch pristine...
gbp:info: Version '1.5-1' imported under 'hello-c'
 $ git branch
* devel
  master
  pristine-tar
  upstream
 $ gitk --all

The gitk command shows the VCS history nicely.

Snapshot (Python)

Let’s consider another upstream source in the VCS and make a snapshot package from it. Let’s assume this is a Python3 source package in distutils.

Let’s inspect files.

 $ tree
.
`-- vcsdir
    |-- hello-py
    |   `-- __init__.py
    |-- MANIFEST
    |-- MANIFEST.in
    |-- PKG-INFO
    |-- scripts
    |   `-- hello
    `-- setup.py

3 directories, 6 files

There are minimalistic configuration files for Autotools.

setup.py:

 $ cat vcsdir/setup.py
#!/usr/bin/python3
# vi:se ts=4 sts=4 et ai:
from distutils.core import setup

setup(name='hello-py',
    version='1.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'
)

The Python program code is as follows.

scripts/hello and hello-py/init.py

 $ cat vcsdir/scripts/hello
#!/usr/bin/python3
# vim:se tw=0 sts=4 ts=4 et si:
"""
Copyright © 2014 Osamu Aoki
 ...
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"""

import hello-py

if __name__ == '__main__':
    hello.main()

 $ cat vcsdir/hello-py/__init__.py
#!/usr/bin/python3
# vim:se tw=0 sts=4 ts=4 et ai:

def main():
    print('Hello Python3!')
    return

if __name__ == '__main__':
    main()

You create a non-native Debian package source tree from the above upstream example using the debmake(1) command. Here package description is copied from the upstream setup.py content by the -s option.

 $ cd vcsdir
 $ git init
Initialized empty Git repository in /path/to/vcsdir/.git/
 $ git add .
 $ git commit -m "initial commit"
[master (root-commit) 432ec13] initial commit
 6 files changed, 93 insertions(+)
 create mode 100644 MANIFEST
 create mode 100644 MANIFEST.in
 create mode 100644 PKG-INFO
 create mode 100755 hello-py/__init__.py
 create mode 100755 scripts/hello
 create mode 100755 setup.py
 $ git branch devel
 $ git branch upstream
 $ git branch
  devel
* master
  upstream
 $ debmake -s -b':python3' -d -i debuild
 ...
I: debmake -x "1" ...
 ...
Finished running lintian.
I: upon return to the shell, current directory becomes /path/to/vcsdir
I: please execute "cd .." and inspect the build results.
 $ git clean -d -f
Removing dist/

Let’s inspect the result.

 $ cd ..
 $ tree -L 1
.
|-- hello-py-1.0
|-- hello-py_1.0-1_all.deb
|-- hello-py_1.0-1_amd64.build
|-- hello-py_1.0-1_amd64.changes
|-- hello-py_1.0-1.debian.tar.xz
|-- hello-py_1.0-1.dsc
|-- hello-py_1.0.orig.tar.gz -> hello-py-1.0.tar.gz
|-- hello-py-1.0.tar.gz
`-- vcsdir

2 directories, 7 files

 $ dpkg -c hello-py_1.0-1_all.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/lib/
drwxr-xr-x root/root ...  ./usr/lib/python3/
drwxr-xr-x root/root ...  ./usr/lib/python3/dist-packages/
-rw-r--r-- root/root ...  ./usr/lib/python3/dist-packages/hello_py-1.0.e...
drwxr-xr-x root/root ...  ./usr/lib/python3/dist-packages/hello-py/
-rw-r--r-- root/root ...  ./usr/lib/python3/dist-packages/hello-py/__ini...
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/hello-py/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-py/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-py/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/hello-py/changelog.Debian.gz

 $ tar -tJf hello-py_1.0-1.debian.tar.xz
debian/
debian/compat
debian/changelog
debian/watch
debian/control
debian/copyright
debian/README.Debian
debian/rules
debian/source/
debian/source/format
debian/patches/
debian/patches/series
 $ tar -tzf hello-py-1.0.tar.gz
hello-py-1.0/
hello-py-1.0/hello-py/
hello-py-1.0/hello-py/__init__.py
hello-py-1.0/scripts/
hello-py-1.0/scripts/hello
hello-py-1.0/MANIFEST.in
hello-py-1.0/PKG-INFO
hello-py-1.0/setup.py
hello-py-1.0/MANIFEST

Let’s check the generated control file content.

 $ dpkg -e hello-py_1.0-1_all.deb
 $ tree DEBIAN
DEBIAN
|-- control
|-- md5sums
|-- postinst
`-- prerm

0 directories, 4 files

Let’s compare how packaging deals with substvar etc.

debian/control in the source package

 $ cat hello-py-1.0/debian/control
Source: hello-py
Section: unknown
Priority: extra
Maintainer: "Firstname Lastname" <email.address@example.org>
Build-Depends: debhelper (>=9), python3-all
Standards-Version: 3.9.5
Homepage: <insert the upstream URL, if relevant>
X-Python3-Version: >= 3.2

Package: hello-py
Architecture: all
Multi-Arch: foreign
Depends: python3, ${misc:Depends}, ${python3:Depends}
Description: Hello Python
 Hello Python program.

DEBIAN/control in the binary package

 $ cat DEBIAN/control
Package: hello-py
Version: 1.0-1
Architecture: all
Maintainer: "Firstname Lastname" <email.address@example.org>
Installed-Size: 49
Depends: python3, python3:any (>= 3.3.2-2~)
Section: unknown
Priority: extra
Multi-Arch: foreign
Homepage: <insert the upstream URL, if relevant>
Description: Hello Python
 Hello Python program.

Multi binary package

Let’s consider an upstream package hello-1.1.tar.gz and untar it to inspect files.

 $ tree
.
|-- hello-1.1
|   |-- hello.c
|   |-- hello.data
|   |-- hello-sh
|   `-- Makefile
`-- hello-1.1.tar.gz

1 directory, 5 files

This is similar to the previously shown hello-c-1.0.tar.gz but with a few additional files and changes.

The C source hello.c is the same one.

Makefile is updated to support $(DESTDIR) for all files.

 $ cat hello-1.1/Makefile
all: hello

hello: hello.c
        gcc -Wall -o hello hello.c

install: hello hello.data
        install -D hello $(DESTDIR)/usr/bin/hello
        install -D hello-sh $(DESTDIR)/usr/bin/hello-sh
        install -D hello.data $(DESTDIR)/usr/share/hello/hello.data

clean:
        -rm -f hello

distclean: clean

.PHONY: all install clean distclean

There is an additional simple shell script hello-sh.

 $ cat hello-1.1/hello-sh
#!/bin/sh
echo "Hello from the shell!"

The hello.data file is a dummy data for this training.

Let’s create a set of the following non-native binary Debian packages.

hello-c : type=bin, This package contains an ELF executable hello file compiled the source file hello.c.
hello-c-dbg : type=dbg, This package contains debug symbols data of the ELF executable file hello.
hello-sh : type=script, This contains the shell script hello-sh.
hello-data : type=data, This contains the data file hello.data.

Since we are splitting the generated files into multiple packages, we package this in two steps. The first step is the "debmake -j …" command.

The debmake execution (1st stage)

 $ cd hello-1.1
 $ debmake -j -b'-c,-c-dbg,-data:data,-sh:script'
 ...
 ... (snip)
 ...
I: $ LANG=C ; sed -e "1d" < ../hello.depcheck.log | sort >../hello.build...
I: $ LANG=C; find debian/tmp -type f 2>&1 | sed -e "s/^debian\/tmp\///" ...
I: upon return to the shell, current directory becomes /path/to/hello-1....
I: please execute "cd /path/to/hello-1.1" before building the binary pac...
I: with dpkg-buildpackage (or debuild, pdebuild, sbuild, ...).

The parent directory after the "debmake -j …" execution.

 $ cd ..
 $ tree -L 1
.
|-- hello-1.1
|-- hello_1.1.orig.tar.gz -> hello-1.1.tar.gz
|-- hello-1.1.tar.gz
|-- hello.build-dep.log
|-- hello.build.log
|-- hello.depcheck.log
`-- hello.install.log

1 directory, 6 files

There are 2 log files in the parent directory.

hello.build-dep.log generated by the dpkg-depcheck command

 $ cat hello.build-dep.log
 ...
 ... (snip)
 ...

Since the build dependency to the debhelper package is always implemented by the debmake command and other packages are installed by the dependencies of the build-essential package, there is no additional package required be listed as the build dependency.

hello.install.log listing files under the debian/tmp directory

 $ cat hello.install.log
usr/bin/hello
usr/bin/hello-sh
usr/share/hello/hello.data

Now we know what files are generated in the debian/tmp directory.

Let’s start with the fresh source tree and build package from there.

The debmake execution (2nd stage)

 $ rm -rf hello-1.1
 $ debmake -b'-c,-c-dbg,-data:data,-sh:script' -a hello-1.1.tar.gz
I: set parameters
I: sanity check of parameters
I: pkg="hello", ver="1.1", rev="1"
 ...
I: parse binary package settings: -c,-c-dbg,-data:data,-sh:script
I: binary package=hello-c Type=bin / Arch=any M-A=foreign
I: binary package=hello-c-dbg Type=dbg / Arch=any M-A=same
I: binary package=hello-data Type=data / Arch=all M-A=foreign
I: binary package=hello-sh Type=script / Arch=all M-A=foreign
 ...
I: debmake -x "2" ...
 ...
I: $ wrap-and-sort
I: upon return to the shell, current directory becomes /path/to
I: please execute "cd /path/to/hello-1.1" before building the binary pac...
I: with dpkg-buildpackage (or debuild, pdebuild, sbuild, ...).

Please note that the debmake command is run with the -x2 option as the default for the new multi binary packages.

 $ cd hello-1.1
 $ tree
.
|-- debian
|   |-- changelog
|   |-- clean
|   |-- compat
|   |-- control
|   |-- copyright
|   |-- hello-c.doc-base
|   |-- hello-c.docs
|   |-- hello-c.examples
|   |-- hello-c.info
|   |-- hello-c.install
|   |-- hello-c.links
|   |-- hello-c.manpages
|   |-- hello-c.menu
|   |-- hello-c.postinst
|   |-- hello-c.postrm
|   |-- hello-c.preinst
|   |-- hello-c.prerm
|   |-- hello-data.install
|   |-- hello-sh.install
|   |-- patches
|   |   `-- series
|   |-- README.Debian
|   |-- rules
|   |-- source
|   |   |-- format
|   |   `-- local-options
|   `-- watch
|-- hello.c
|-- hello.data
|-- hello-sh
`-- Makefile

3 directories, 29 files

Let’s inspect generated template files.

debian/rules:

 $ cat debian/rules
#!/usr/bin/make -f
# See debhelper(7) (uncomment to enable)
# output every command that modifies files on the build system.
#DH_VERBOSE = 1

# In case you want to add more flags to the defaults, use
# the followings to harden via compiler options
# see FEATURE AREAS in dpkg-buildflags(1))
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
# see ENVIRONMENT in dpkg-buildflags(1))
# package maintainers to append CFLAGS
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
# package maintainers to append LDFLAGS
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed



# main packaging script based on dh7 syntax
%:
        dh $@

# debmake generated override targets
# see https://www.debian.org/doc/manuals/developers-reference/best-pkgin...
override_dh_strip:
        dh_strip --dbg-package=hello-c-dbg

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

debian/control:

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

Package: hello-c
Architecture: any
Multi-Arch: foreign
Depends: ${misc:Depends}, ${shlibs:Depends}
Description: auto-generated package by debmake: bin
 This package contains the compiled binary executable.
 ...
 ... (snip)
 ...

Package: hello-c-dbg
Section: debug
Architecture: any
Multi-Arch: same
Depends: hello-c (= ${binary:Version}), ${misc:Depends}
Description: auto-generated package by debmake: dbg
 This package contains the debugging symbols.

Package: hello-data
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}
Description: auto-generated package by debmake: data
 This package contains the architecture independent data.

Package: hello-sh
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}
Description: auto-generated package by debmake: script
 This package contains the script program.

Nice to see the templates are generated with reasonable contents.

There are several template files under the debian/ directory. Let’s customize them and erase unnecessary ones. (Here, we are skipping details required by the best practice.)

Manual adjustments of debian/*

 $ cd ./debian
 $ rm -f *.do* *.examples *.info *.links *.m*  *.p*
 $ rm hello-c-dbg.install
rm: cannot remove ‘hello-c-dbg.install’: No such file or directory
 $ echo usr/bin/hello > hello-c.install
 $ echo usr/share/hello/hello.data > hello-data.install
 $ echo usr/bin/hello-sh > hello-sh.install

You can create a non-native Debian package using the debuild command (or its equivalents) in this source tree.

 $ cd ..
 $ debuild
 dpkg-buildpackage -rfakeroot -D -us -uc -I -i
 ...
dpkg-buildpackage: host architecture amd64
 fakeroot debian/rules clean
dh clean
 ...
 debian/rules build
dh build
 ...
 fakeroot debian/rules binary
dh binary
 ...
Finished running lintian.

Let’s inspect the result.

The generated files of version 1.0 by the debuild command:

 $ cd ..
 $ tree -L 1
.
|-- hello-1.1
|-- hello_1.1-1_amd64.build
|-- hello_1.1-1_amd64.changes
|-- hello_1.1-1.debian.tar.xz
|-- hello_1.1-1.dsc
|-- hello_1.1.orig.tar.gz -> hello-1.1.tar.gz
|-- hello-1.1.tar.gz
|-- hello.build-dep.log
|-- hello.build.log
|-- hello-c_1.1-1_amd64.deb
|-- hello-c-dbg_1.1-1_amd64.deb
|-- hello-data_1.1-1_all.deb
|-- hello.depcheck.log
|-- hello.install.log
`-- hello-sh_1.1-1_all.deb

1 directory, 14 files

The source package contents of version 1.0:

 $ tar -tJf hello_1.1-1.debian.tar.xz
debian/
debian/compat
debian/clean
debian/changelog
debian/watch
debian/hello-sh.install
debian/hello-c.install
debian/control
debian/copyright
debian/README.Debian
debian/rules
debian/source/
debian/source/format
debian/patches/
debian/patches/series
debian/hello-data.install
 $ tar -tzf hello-1.1.tar.gz
hello-1.1/
hello-1.1/Makefile
hello-1.1/hello.data
hello-1.1/hello-sh
hello-1.1/hello.c

The binary package contents of version 1.0:

 $ dpkg -c hello-c_1.1-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/hello-c/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c/changelog.Debian.gz
 $ dpkg -c hello-c-dbg_1.1-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/lib/
drwxr-xr-x root/root ...  ./usr/lib/debug/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/a9/
-rw-r--r-- root/root ...  ./usr/lib/debug/.build-id/a9/023dfdad9d4c1b846...
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/hello-c-dbg/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c-dbg/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-c-dbg/changelog.Debian.g...
 $ dpkg -c hello-data_1.1-1_all.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/hello-data/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-data/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-data/changelog.Debian.gz...
drwxr-xr-x root/root ...  ./usr/share/hello/
-rwxr-xr-x root/root ...  ./usr/share/hello/hello.data
 $ dpkg -c hello-sh_1.1-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-sh
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/hello-sh/
-rw-r--r-- root/root ...  ./usr/share/doc/hello-sh/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/hello-sh/changelog.Debian.gz

Note	For the multi binary package case, you must provide binarypackage.install files for all binary packages (excluding dbg type ones). The build result needs to be moved from the debian/tmp/ directory into the directory for those binary packages.

Library package

Let’s consider an upstream package libkkc-0.3.2.tar.gz.

Step 0: Untar …

 $ tar -xzmf libkkc-0.3.2.tar.gz
 $ cd libkkc-0.3.2
 $ git init
Initialized empty Git repository in /path/to/libkkc-0.3.2/.git/
 $ git add .
 $ git commit -m 'initial import of libkkc-0.3.2.tar.gz'
[master (root-commit) 377b076] initial import of libkkc-0.3.2.tar.gz
 423 files changed, 211360 insertions(+)
 ...
 ... (snip)
 ...
 create mode 100644 tools/kkc.vala
 create mode 100644 tools/kkc_vala.stamp
 $ git branch upstream
 $ git tag upstream/0.3.2
 $ pristine-tar commit ../libkkc-0.3.2.tar.gz
pristine-tar: committed libkkc-0.3.2.tar.gz.delta to branch pristine-tar...

Let’s make a test build this with the -j option.

Step 1: debmake -j

 $ debmake -j
I: set parameters
I: sanity check of parameters
I: pkg="libkkc", ver="0.3.2", rev="1"
I: *** start packaging in "libkkc-0.3.2". ***
I: provide libkkc_0.3.2.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf libkkc-0.3.2.tar.gz libkkc_0.3.2.orig.tar.gz
 ...
 ... (snip)
 ...
I: $ wrap-and-sort
I: $ fakeroot dpkg-depcheck -m -C -o ../libkkc.depcheck.log -f -catch-al...
I: $ LANG=C ; sed -e "1d" < ../libkkc.depcheck.log | sort >../libkkc.bui...
I: $ LANG=C; find debian/libkkc -type f 2>&1 | sed -e "s/^debian\/libkkc...
I: upon return to the shell, current directory becomes /path/to/libkkc-0...
I: please execute "cd /path/to/libkkc-0.3.2" before building the binary ...
I: with dpkg-buildpackage (or debuild, pdebuild, sbuild, ...).

Let’s inspect the package dependency.

libkkc.build-dep.log

 $ cat ../libkkc.build-dep.log
  autotools-dev
  cpio
  debhelper
  gawk
  gobject-introspection
  gvfs:amd64
  intltool
  libc6-i386
  libc6-x32
  libc6:i386
  libfakechroot:amd64
  libfakeroot:amd64
  libgee-dev
  libgirepository-1.0-1
  libgirepository1.0-dev
  libglib2.0-dev
  libjson-glib-dev
  liblocale-gettext-perl
  libmarisa-dev:amd64
  libpython2.7-stdlib:amd64
  mime-support
  perl-modules
  pkg-config
  python-gobject-2
  python-imaging
  python-input-pad
  python-lazr.uri
  python-marisa
  python-repoze.lru
  python-support
  python-zope.interface
  python2.7-minimal
  valac-0.22
  valac-0.22-vapi

Let’s inspect the generated files.

libkkc.install.log

 $ cat ../libkkc.install.log
usr/bin/kkc
usr/bin/kkc-package-data
usr/include/libkkc/libkkc.h
usr/lib/x86_64-linux-gnu/girepository-1.0/Kkc-1.0.typelib
usr/lib/x86_64-linux-gnu/libkkc.la
usr/lib/x86_64-linux-gnu/libkkc.so.2.0.0
usr/lib/x86_64-linux-gnu/pkgconfig/kkc-1.0.pc
usr/share/doc/libkkc/README.Debian
 ...
 ... (snip)
 ...
usr/share/libkkc/templates/libkkc-data/tools/genfilter.py
usr/share/libkkc/templates/libkkc-data/tools/sortlm.py
usr/share/locale/ja/LC_MESSAGES/libkkc.mo
usr/share/vala/vapi/kkc-1.0.deps
usr/share/vala/vapi/kkc-1.0.vapi

Let’s clean the source tree first.

 $ git reset --hard HEAD
HEAD is now at 377b076 initial import of libkkc-0.3.2.tar.gz
 $ git clean -xfd
Removing Makefile
Removing config.guess.dh-orig
 ...
 ... (snip)
 ...
Removing tools/kkc
Removing tools/kkc-kkc.o
Removing tools/kkc-package-data

Let’s create the fresh source tree with the following package split plan.

binarypackage	type	-b option
libkkc2	lib	libkkc2
libkkc-utils	bin	-utils
libkkc2-dbg	dbg	libkkc2-dbg
libkkc-utils-dbg	dbg	-utils-dbg
libkkc-dev	dev	-dev
libkkc-common	data	-common:data

 $ debmake -b'libkkc2,-utils,libkkc2-dbg,-utils-dbg,-dev,-common:data' -...
I: set parameters
I: sanity check of parameters
I: pkg="libkkc", ver="0.3.2", rev="1"
I: *** start packaging in "libkkc-0.3.2". ***
I: provide libkkc_0.3.2.orig.tar.gz for non-native Debian package
I: pwd = "/path/to"
I: $ ln -sf libkkc-0.3.2.tar.gz libkkc_0.3.2.orig.tar.gz
I: pwd = "/path/to/libkkc-0.3.2"
I: parse binary package settings: libkkc2,-utils,libkkc2-dbg,-utils-dbg,...
 ...
 ... (snip)
 ...
I: skipping :: debian/libkkc2.install (file exists)
I: creating => debian/libkkc2.doc-base
I: creating => debian/libkkc-utils.install
I: creating => debian/libkkc-dev.install
I: creating => debian/libkkc-common.install
I: run "debmake -x3" to get more template files
I: $ wrap-and-sort

Let’s commit this result.

 $ git add -A .
 $ git commit -m debmake_template
[master e558727] debmake_template
 27 files changed, 1859 insertions(+)
 create mode 100644 debian/README.Debian
 ...
 ... (snip)
 ...

This generats the following source tree. (Too large to list here.)

 $ tree
.
|-- aclocal.m4
|-- AUTHORS
|-- autogen.sh
|-- ChangeLog
|-- compile
|-- config.guess
|-- config.h.in
|-- config.sub
|-- configure
|-- configure.ac
|-- COPYING
|-- data
|   |-- Makefile.am
 ...
 ... (snip)
 ...
|   |-- user-segment-dictionary-bad2
|   |-- user-segment-dictionary-good
|   |-- user-sentence-dictionary-bad1
|   |-- user-sentence-dictionary-bad2
|   `-- user-sentence-dictionary-good
`-- tools
    |-- kkc.c
    |-- kkc-package-data.in
    |-- kkc.vala
    |-- kkc_vala.stamp
    |-- Makefile.am
    `-- Makefile.in

95 directories, 438 files
 $ cd debian

Let’s make manual modifications to the files under the debian directory.

changelog

 $ vim changelog
 ...
 $ cat changelog
libkkc (0.3.2-1) unstable; urgency=low

  * First upload to debian archive (Closes: #715232)
  * Depends skkdic
  * Update debian/license

 -- Mitsuya Shibata <mty.shibata@gmail.com>  Wed, 26 Feb 2014 22:51:39 +...

compat

 $ cat compat
9

control

 $ vim control
 ...
 $ cat control
Source: libkkc
Priority: extra
Maintainer: IME Packaging Team <pkg-ime-devel@lists.alioth.debian.org>
Uploaders: Mitsuya Shibata <mty.shibata@gmail.com>,
           Osamu Aoki <osamu@debian.org>
Build-Depends: autotools-dev,
               debhelper (>= 9),
               gobject-introspection,
               intltool,
               libgee-dev,
               libgirepository1.0-dev,
               libglib2.0-dev,
               libjson-glib-dev,
               libmarisa-dev,
               python-marisa,
               valac
Standards-Version: 3.9.5
Section: libs
Homepage: https://bitbucket.org/libkkc/libkkc/wiki/Home
Vcs-Git: git://anonscm.debian.org/pkg-ime/libkkc.git
Vcs-Browser: http://anonscm.debian.org/gitweb/?p=pkg-ime/libkkc.git

Package: libkkc2
Architecture: any
Multi-Arch: same
Pre-Depends: ${misc:Pre-Depends}
Depends: libkkc-common, libkkc-data, skkdic, ${misc:Depends}, ${shlibs:D...
Description: Japanese Kana Kanji input library
 libkkc provides a converter from Japanese Kana-string to
 Kana-Kanji-mixed-string. It was named after kkc.el in GNU Emacs, a simp...
 Kanji converter, while libkkc tries to convert sentences in a bit more ...
 way using N-gram language models.
 .
 This package provides the shared library for libkkc.

Package: libkkc-utils
Section: utils
Architecture: any
Multi-Arch: foreign
Depends: libkkc-data,
         libkkc2 (= ${binary:Version}),
         ${misc:Depends},
         ${shlibs:Depends}
Description: Japanese Kana Kanji input library - testing utility
 libkkc provides a converter from Japanese Kana-string to
 Kana-Kanji-mixed-string. It was named after kkc.el in GNU Emacs, a simp...
 Kanji converter, while libkkc tries to convert sentences in a bit more ...
 way using N-gram language models.
 .
 This package provides the testing utility for libkkc.

Package: libkkc2-dbg
Section: debug
Architecture: any
Multi-Arch: same
Depends: libkkc2 (= ${binary:Version}), ${misc:Depends}
Description: Japanese Kana Kanji input library - library debugging symbo...
 libkkc provides a converter from Japanese Kana-string to
 Kana-Kanji-mixed-string. It was named after kkc.el in GNU Emacs, a simp...
 Kanji converter, while libkkc tries to convert sentences in a bit more ...
 way using N-gram language models.
 .
 This package contains the debugging symbols for the shared library of l...

Package: libkkc-utils-dbg
Section: debug
Architecture: any
Multi-Arch: same
Depends: libkkc-utils (= ${binary:Version}), ${misc:Depends}
Description: Japanese Kana Kanji input library - utility debugging symbo...
 libkkc provides a converter from Japanese Kana-string to
 Kana-Kanji-mixed-string. It was named after kkc.el in GNU Emacs, a simp...
 Kanji converter, while libkkc tries to convert sentences in a bit more ...
 way using N-gram language models.
 .
 This package contains the debugging symbols for the testing utility of ...

Package: libkkc-dev
Section: libdevel
Architecture: any
Multi-Arch: same
Depends: libkkc2 (= ${binary:Version}), ${misc:Depends}
Description: Japanese Kana Kanji input library - development files
 libkkc provides a converter from Japanese Kana-string to
 Kana-Kanji-mixed-string. It was named after kkc.el in GNU Emacs, a simp...
 Kanji converter, while libkkc tries to convert sentences in a bit more ...
 way using N-gram language models.
 .
 This package provides the files necessary for compiling programs that
 depend on libkkc.

Package: libkkc-common
Section: utils
Architecture: all
Multi-Arch: foreign
Depends: ${misc:Depends}
Description: Japanese Kana Kanji input library - common data
 libkkc provides a converter from Japanese Kana-string to
 Kana-Kanji-mixed-string. It was named after kkc.el in GNU Emacs, a simp...
 Kanji converter, while libkkc tries to convert sentences in a bit more ...
 way using N-gram language models.
 .
 This package provides common data such as typing rules for libkkc.

copyright

 $ vim copyright
 ...
 $ cat copyright
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0...
Upstream-Name: libkkc
Source: https://bitbucket.org/libkkc/libkkc/wiki/Home

Files: *
Copyright: 2011-2013 Daiki Ueno <ueno@gnu.org>
           2011-2013 Red Hat, Inc.
License: GPL-3.0+
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.
 .
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 .
 You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.

Files: debian/*
 ...
 ... (snip)
 ...

Files: INSTALL
Copyright: 1994-2011 Free Software Foundation, Inc.
License: PERMISSIVE
 Copying and distribution of this file, with or without modification,
 are permitted in any medium without royalty provided the copyright
 notice and this notice are preserved.  This file is offered as-is,
 without warranty of any kind.

kkc.1

 $ vim kkc.1
 ...
 $ cat kkc.1
.\"                                      Hey, EMACS: -*- nroff -*-
.\" (C) Copyright 2013 Mitsuya Shibata <mty.shibata@gmail.com>,
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH KKC 1 "DEC 2013"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
kkc \- a simple Kana Kanji converter
.SH SYNOPSIS
.B kkc
.I \fR[\fI help \fR|\fI decoder \fR|\fI context \fR]\fI
.RI [ OPTIONS ]
.SH DESCRIPTION
kkc converte from Kana-string to Kana-Kanji-mixed-string and list up
candidates.
.PP
Users can specify parameters through command line options. See
\fBkkc help\fP or \fBkkc command \-\-help\fP for the list of options.
.SH SEE ALSO
See /usr/share/doc/libkkc-utils/README for usage example.

install files

 $ echo 'usr/share/libkkc/rules/*' > libkkc-common.install
 $ echo 'usr/include/*'            > libkkc-dev.install
 $ echo 'usr/lib/*/lib*.so'        >>libkkc-dev.install
 $ echo 'usr/lib/*/pkgconfig/*'    >>libkkc-dev.install
 $ echo 'usr/share/vala/vapi/*'    >>libkkc-dev.install
 $ echo 'usr/bin/kkc'              > libkkc-utils.install
 $ echo 'usr/share/locale/'        >>libkkc-utils.install
 $ echo 'usr/lib/*/lib*.so.*'      >>libkkc2.install
 $ echo 'README'                   > libkkc-utils.docs
 $ echo 'debian/kkc.1'             > libkkc-utils.manpages

rules

 $ vim rules
 ...
 $ cat rules
#!/usr/bin/make -f
#DH_VERBOSE = 1

# In case you want to add more flags to the defaults, use
# the followings to harden via compiler options
# see FEATURE AREAS in dpkg-buildflags(1))
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
# see ENVIRONMENT in dpkg-buildflags(1))
# package maintainers to append CFLAGS
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
# package maintainers to append LDFLAGS
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

VALAFLAGS:=$(foreach w,$(CPPFLAGS) $(CFLAGS) $(LDFLAGS),-X $(w))

%:
        dh $@ --with autotools-dev,gir

override_dh_auto_configure:
        dh_auto_configure -- --disable-silent-rules

override_dh_strip:
        dh_strip -Xlibkkc-utils --dbg-package=libkkc2-dbg
        dh_strip -Xlibkkc2 --dbg-package=libkkc-utils-dbg

Remove unused template files

 $ rm -f clean
 $ rm -f libkkc2.examples
 $ rm -f libkkc2.info
 $ rm -f libkkc2.postinst
 $ rm -f libkkc2.postrm
 $ rm -f libkkc2.preinst
 $ rm -f libkkc2.prerm

Let’s record packaging result into VCS.

(Hmmmm…. importing upstream with pristine-tar first is better but let’s not worry now.)

 $ cd ../
 $ git add -A .
 $ git commit -m initial_commit
[master c97da03] initial_commit
 18 files changed, 518 insertions(+), 1763 deletions(-)
 delete mode 100644 debian/clean
 rewrite debian/control (74%)
 rewrite debian/copyright (79%)
 create mode 100644 debian/kkc.1
 create mode 100644 debian/libkkc-utils.docs
 create mode 100644 debian/libkkc-utils.manpages
 delete mode 100644 debian/libkkc2.examples
 delete mode 100644 debian/libkkc2.info
 delete mode 100644 debian/libkkc2.postinst
 delete mode 100644 debian/libkkc2.postrm
 ...
 ... (snip)
 ...
 delete mode 100644 debian/libkkc2.info
 delete mode 100644 debian/libkkc2.postinst
 delete mode 100644 debian/libkkc2.postrm
 delete mode 100644 debian/libkkc2.preinst
 delete mode 100644 debian/libkkc2.prerm

Let’s build this package under the pdebuild command.

The first pdebuild

 $ pdebuild
dpkg-buildpackage: source package libkkc
dpkg-buildpackage: source version 0.3.2-1
 ...
 dpkg-source --before-build libkkc-0.3.2
 fakeroot debian/rules clean
make[1]: Entering directory `/path/to/libkkc-0.3.2'
--
dpkg-buildpackage: host architecture amd64
 fakeroot debian/rules clean
make[1]: Entering directory `/tmp/buildd/libkkc-0.3.2'
 ...
 debian/rules build
make[1]: Entering directory `/tmp/buildd/libkkc-0.3.2'
 ...
 fakeroot debian/rules binary
make[1]: Entering directory `/tmp/buildd/libkkc-0.3.2'
 ...
dpkg-gensymbols: warning: new libraries appeared in the symbols file: li...
dpkg-gensymbols: warning: debian/libkkc2/DEBIAN/symbols doesn't match co...
--- debian/libkkc2.symbols (libkkc2_0.3.2-1_amd64)
+++ dpkg-gensymbolsw3FSQO       2014-04-02 15:43:15.582561319 +0000
@@ -0,0 +1,344 @@
+libkkc.so.2 libkkc2 #MINVER#
+ kkc_bigram_decoder_add_unknown_nodes@Base 0.3.2-1
+ kkc_bigram_decoder_backward_search@Base 0.3.2-1
+ kkc_bigram_decoder_build_trellis@Base 0.3.2-1
+ kkc_bigram_decoder_construct@Base 0.3.2-1
+ kkc_bigram_decoder_forward_search@Base 0.3.2-1
+ kkc_bigram_decoder_get_model@Base 0.3.2-1
 ...
  forking: rm -rf /var/cache/pbuilder/build//cow.10460

Restore source tree using VCS

 $ git reset --hard HEAD
HEAD is now at c97da03 initial_commit
 $ git clean -d -f -x
 ...
 ... (snip)
 ...

Using mc, copy DEBIAN/symbols from the libkkc2_0.3.2-1_amd64.deb package to debian/libkkc2.symbols. (Of course, you can manually use the dpkg-deb command.)

Update debian/libkkc2.symbols

 $ vim debian/libkkc2.symbols
 ... (:%s/-1$//)
 ... (:wq)
 $ cat debian/libkkc2.symbols
libkkc.so.2 libkkc2 #MINVER#
 kkc_bigram_decoder_add_unknown_nodes@Base 0.3.2
 kkc_bigram_decoder_backward_search@Base 0.3.2
 kkc_bigram_decoder_build_trellis@Base 0.3.2
 kkc_bigram_decoder_construct@Base 0.3.2
 kkc_bigram_decoder_forward_search@Base 0.3.2
 ...
 ... (snip)
 ...

The second pdebuild

 $ pdebuild
dpkg-buildpackage: source package libkkc
dpkg-buildpackage: source version 0.3.2-1
 ...
 dpkg-source --before-build libkkc-0.3.2
 fakeroot debian/rules clean
make[1]: Entering directory `/path/to/libkkc-0.3.2'
--
dpkg-buildpackage: host architecture amd64
 fakeroot debian/rules clean
make[1]: Entering directory `/tmp/buildd/libkkc-0.3.2'
 ...
 debian/rules build
make[1]: Entering directory `/tmp/buildd/libkkc-0.3.2'
 ...
 fakeroot debian/rules binary
make[1]: Entering directory `/tmp/buildd/libkkc-0.3.2'
 ...
  forking: rm -rf /var/cache/pbuilder/build//cow.4080

The build result

 $ cd ..
 $ tree -L 1
.
|-- libkkc-0.3.2
|-- libkkc_0.3.2-1_amd64.build
|-- libkkc_0.3.2-1_amd64.changes
|-- libkkc_0.3.2-1.debian.tar.xz
|-- libkkc_0.3.2-1.dsc
|-- libkkc_0.3.2-1_source.changes
|-- libkkc_0.3.2.orig.tar.gz -> libkkc-0.3.2.tar.gz
|-- libkkc-0.3.2.tar.gz
|-- libkkc2_0.3.2-1_amd64.deb
|-- libkkc2-dbg_0.3.2-1_amd64.deb
|-- libkkc.build-dep.log
|-- libkkc.build.log
|-- libkkc-common_0.3.2-1_all.deb
|-- libkkc.depcheck.log
|-- libkkc-dev_0.3.2-1_amd64.deb
|-- libkkc.install.log
|-- libkkc-utils_0.3.2-1_amd64.deb
`-- libkkc-utils-dbg_0.3.2-1_amd64.deb

1 directory, 17 files

Let’s inspect the result.

The generated files of version 1.0 by the debuild command:

 $ cd ..
 $ tree -L 1
.
|-- libkkc-0.3.2
|-- libkkc_0.3.2-1_amd64.build
|-- libkkc_0.3.2-1_amd64.changes
|-- libkkc_0.3.2-1.debian.tar.xz
|-- libkkc_0.3.2-1.dsc
|-- libkkc_0.3.2-1_source.changes
|-- libkkc_0.3.2.orig.tar.gz -> libkkc-0.3.2.tar.gz
|-- libkkc-0.3.2.tar.gz
|-- libkkc2_0.3.2-1_amd64.deb
|-- libkkc2-dbg_0.3.2-1_amd64.deb
|-- libkkc.build-dep.log
|-- libkkc.build.log
|-- libkkc-common_0.3.2-1_all.deb
|-- libkkc.depcheck.log
|-- libkkc-dev_0.3.2-1_amd64.deb
|-- libkkc.install.log
|-- libkkc-utils_0.3.2-1_amd64.deb
`-- libkkc-utils-dbg_0.3.2-1_amd64.deb

1 directory, 17 files

The source package contents:

 $ tar -tJf libkkc_0.3.2-1.debian.tar.xz
debian/
debian/libkkc-utils.docs
debian/libkkc2.menu
debian/libkkc2.manpages
debian/compat
debian/libkkc2.links
debian/changelog
debian/watch
debian/libkkc2.install
debian/kkc.1
 ...
 $ tar -tzf libkkc-0.3.2.tar.gz
libkkc-0.3.2/
libkkc-0.3.2/missing
libkkc-0.3.2/tools/
libkkc-0.3.2/tools/kkc_vala.stamp
libkkc-0.3.2/tools/kkc.vala
libkkc-0.3.2/tools/Makefile.in
libkkc-0.3.2/tools/kkc-package-data.in
libkkc-0.3.2/tools/Makefile.am
libkkc-0.3.2/tools/kkc.c
libkkc-0.3.2/NEWS
 ...

The binary package contents:

 $ dpkg -c libkkc2_0.3.2-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/lib/
drwxr-xr-x root/root ...  ./usr/lib/x86_64-linux-gnu/
-rw-r--r-- root/root ...  ./usr/lib/x86_64-linux-gnu/libkkc.so.2.0.0
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/libkkc2/
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc2/changelog.gz
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc2/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc2/README.Debian
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc2/changelog.Debian.gz
drwxr-xr-x root/root ...  ./usr/share/menu/
-rw-r--r-- root/root ...  ./usr/share/menu/libkkc2
lrwxrwxrwx root/root ...  ./usr/lib/x86_64-linux-gnu/libkkc.so.2 -> libk...
 $ dpkg -c libkkc2-dbg_0.3.2-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/lib/
drwxr-xr-x root/root ...  ./usr/lib/debug/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/6a/
-rw-r--r-- root/root ...  ./usr/lib/debug/.build-id/6a/87fbe93c7f4705859...
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/libkkc2-dbg/
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc2-dbg/changelog.gz
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc2-dbg/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc2-dbg/changelog.Debian.g...
 $ dpkg -c libkkc-common_0.3.2-1_all.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/libkkc-common/
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-common/changelog.gz
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-common/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-common/changelog.Debian...
drwxr-xr-x root/root ...  ./usr/share/libkkc/
 ...
 ... (snip)
 ...
-rw-r--r-- root/root ...  ./usr/share/libkkc/rules/default/keymap/hankak...
-rw-r--r-- root/root ...  ./usr/share/libkkc/rules/default/keymap/wide-l...
-rw-r--r-- root/root ...  ./usr/share/libkkc/rules/default/keymap/direct...
-rw-r--r-- root/root ...  ./usr/share/libkkc/rules/default/metadata.json...
drwxr-xr-x root/root ...  ./usr/share/libkkc/rules/default/rom-kana/
-rw-r--r-- root/root ...  ./usr/share/libkkc/rules/default/rom-kana/defa...
 $ dpkg -c libkkc-dev_0.3.2-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/include/
drwxr-xr-x root/root ...  ./usr/include/libkkc/
-rw-r--r-- root/root ...  ./usr/include/libkkc/libkkc.h
drwxr-xr-x root/root ...  ./usr/lib/
drwxr-xr-x root/root ...  ./usr/lib/x86_64-linux-gnu/
drwxr-xr-x root/root ...  ./usr/lib/x86_64-linux-gnu/pkgconfig/
-rw-r--r-- root/root ...  ./usr/lib/x86_64-linux-gnu/pkgconfig/kkc-1.0.p...
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/libkkc-dev/
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-dev/changelog.gz
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-dev/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-dev/changelog.Debian.gz...
drwxr-xr-x root/root ...  ./usr/share/vala/
drwxr-xr-x root/root ...  ./usr/share/vala/vapi/
-rw-r--r-- root/root ...  ./usr/share/vala/vapi/kkc-1.0.vapi
-rw-r--r-- root/root ...  ./usr/share/vala/vapi/kkc-1.0.deps
lrwxrwxrwx root/root ...  ./usr/lib/x86_64-linux-gnu/libkkc.so -> libkkc...
 $ dpkg -c libkkc-utils_0.3.2-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/kkc
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/locale/
drwxr-xr-x root/root ...  ./usr/share/locale/ja/
drwxr-xr-x root/root ...  ./usr/share/locale/ja/LC_MESSAGES/
-rw-r--r-- root/root ...  ./usr/share/locale/ja/LC_MESSAGES/libkkc.mo
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/libkkc-utils/
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-utils/changelog.gz
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-utils/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-utils/changelog.Debian....
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-utils/README
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/kkc.1.gz
 $ dpkg -c libkkc-utils-dbg_0.3.2-1_amd64.deb
drwxr-xr-x root/root ...  ./
drwxr-xr-x root/root ...  ./usr/
drwxr-xr-x root/root ...  ./usr/lib/
drwxr-xr-x root/root ...  ./usr/lib/debug/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/
drwxr-xr-x root/root ...  ./usr/lib/debug/.build-id/20/
-rw-r--r-- root/root ...  ./usr/lib/debug/.build-id/20/afe1a56a5caa24363...
drwxr-xr-x root/root ...  ./usr/share/
drwxr-xr-x root/root ...  ./usr/share/doc/
drwxr-xr-x root/root ...  ./usr/share/doc/libkkc-utils-dbg/
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-utils-dbg/changelog.gz
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-utils-dbg/copyright
-rw-r--r-- root/root ...  ./usr/share/doc/libkkc-utils-dbg/changelog.Deb...

Appendix

debmake(1)

NAME

debmake - program to make the Debian source package

SYNOPSIS

debmake [-h] [-c] [-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]

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

-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],…"

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.

If the source tree contents does 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 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")

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

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 “Debian Policy Manual”.

DEBUG

The character set in the environ variable $DEBUG determines the logging output level.

p: list all parameters
d: list all binary package parameters
f: copyright scanner input filename
i: copyright scanner input line
o: line outside of the copyright and license sections
c: line inside of the copyright section
l: line inside of the license section

AUTHOR

LICENSE

MIT License