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]]
=== *debmake*

The *debmake* command is the helper script footnote:[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*, *pbuilder*, 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.
** 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.

TIP: The non-native Debian package is the normal Debian package.

NOTE: The generation of the *debian/copyright* file, and the output from the *-c* and *-k* option involve hulistic operations on the copyright and license information.  They may produce some errouneous results.

[[basics]]
=== Basics

Let's consider a simple C source following the http://www.gnu.org/prep/standards/[GNU Coding Standards] and http://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard[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 lacking meaningful contents, etc.  But this generates a functioning binary package which can be managed by the *dpkg* command and is good enough for your local deployment.

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 the *pdebuild* command.

[[xoption]]
=== 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: The *debuild* command may be substituted by the equivalent commands such as *pdebuild* etc.

TIP: URL such as "'http://www.example.org/DL/package-1.0.tar.gz'" may be used for the *-a* option.

TIP: URL such as "http://arm.koji.fedoraproject.org//packages/ibus/1.5.7/3.fc21/src/ibus-1.5.7-3.fc21.src.rpm" may be used for the *-a* option, too.

[[boption]]
=== 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.

*****
include::binary.txt[]
*****

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

[options="header", cols="3,2,3,2,8"]
|====
|'binarypackage'   |'type'   |*Architecture:*|*Multi-Arch:*	|Package content
|*lib*'foo1'	   |*lib*^*^ |any |same    |the shared library, co-installable
|*lib*'foo1'*-dbg* |*dbg*^*^ |any |same    |the shared library debug symbols, co-installable
|*lib*'foo'*-dev*  |*dev*^*^ |any |same    |the shared library header files etc., co-installable
|*lib*'foo'*-tools*|*bin*^*^ |any |foreign |the run-time support programs, not co-installable
|*lib*'foo'*-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.

[[pythonmod]]
=== Python module

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

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

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

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

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

[[dt-option]]
=== 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 automates making of the non-native Debian packages from the VCS snapshot while using these **debian/*** files.

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

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 the packaging situation resembles the Debian *native* binary package building case using the *debuild* command without the upstream tarball.

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

[[testbuild]]
=== Test build

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

For example, let's package the same 'package-1.0'*.tar.gz* (see <<basics>>) into a multi binary package by test building it with the *-j* option.

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

NOTE: The *-j* option for *debmake* invokes *dpkg-depcheck*(1) to run *debian/rules* under *strace*(1) to obtain library dependencies and is very slow.  If you know the library package dependencies from other sources such as the SPEC file in the source, you may just run "*debmake* ..." without *-j* and "*debian/rules install*" to check the install paths of the generated files.

* Check the last lines of 'package'**.build-dep.log** to judge build dependencies for *Build-Depends*. (You do not need to list packages used by *debhelper*, *perl*, or *fakeroot* explicitly in *Build-Depends*.  This technique is useful for the generation of the single binary package, too.)

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

----
 $ rm -rf package-1.0
 $ 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.

[[c-option]]
=== Check copyright

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

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

With *-c*, this provides shorter report.

[[k-option]]
=== Check debian/copyright

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

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

