= Debmake tutorial
:Author:    Osamu Aoki
:Email:     osamu@debian.org
:Date:      {date}
:Revision:  {revision}

This tutorial may be used under the terms the GNU General Public License version 2 or higher.

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

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.

This simple tutorial should be enough for you to get started with the *debmake* command, if you already know the Debian packaging.

There is also the *debmake* manpage which explains all the command options.  It is included here in the appendix.

If you are new to the Debian packaging, do not worry about the details and just get the big picture instead.  Please read the more detailed guide such as link:maint-guide.html[Debian Maintainers' Guide with debmake].

[[feature-overview]]
== Feature overview

The *debmake* command is intended to replace functions offered historically by *deb-make* footnote:[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:

* use of *dh* syntax under the new *debhelper (> 9.0)* package
** extensive check of copyright for *DEP-5* (*debian/copyright*)
** substvar supports for binary packages (*debian/control*)
** support of compiler hardening options (*debian/rules*)
* keep pre-existing Debian package configuration files untouched
** automatic generation of the missing template packaging files
** easy verification of the *debian/copyright* file against the current source. (*-k* option)
* 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
** direct generation of the binary package from the python module
** the multiarch Debian package
** the multi binary Debian package
** the non-native Debian packages from the VCS snapshot
** seamless work with *debuild*, *pdebuild*, etc.

These are realized with the following approaches:

* It doesn't overwrite existing configuration files in the *debian/* directory.
* 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 has the *-s* option to copy the package description from the upstream meta data.
* It supports the *multiarch* package.
** 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 creates good template files such as the *debian/copyright* file complient to *DEP-5*.
** 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 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 outputs from the *-c* and *-k* options involve heuristic operations on the copyright and license information.  They may produce some erroneous results.

[[simple]]
== Binary package

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
   ... Make manual adjustments of generated configuration files
 $ debuild
----

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

TIP: The *debuild* command in these examples may be substituted by the equivalent commands such as the *pdebuild* command.

include::44-boption.txt[]

== Useful options

include::66-aioption.txt[]

include::67-dtoption.txt[]

include::68-pymod.txt[]

include::69-coption.txt[]

include::70-koption.txt[]

include::71-joption.txt[]

include::72-xoption.txt[]

[[manpage]]
include::99-manpage.txt[]

