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

[[packaging-tarball]]
=== Packaging tarball

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

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

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

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

Debian packaging requires changing this ``*make install*'' process to install files to the target system image location instead of the normal location under */usr/local*.

NOTE: Examples of creating a Debian package from other complicated build systems are described in <<more>>.

[[big-picture]]
=== Big picture

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

* The maintainer obtains the upstream tarball *debhello-0.0.tar.gz* and untars its contents to the *debhello-0.0* directory.
* The *debmake* command debianizes the upstream source tree by adding template files only in the *debian* directory.
** The *debhello_0.0.orig.tar.gz* symlink is created pointing to the *debhello-0.0.tar.gz* file.
** The maintainer customizes template files.
* The *debuild* command builds the binary package from the debianized source tree.
** *debhello-0.0-1.debian.tar.xz* is created containing the *debian* directory.

.Big picture of package building
----
 $ tar -xzmf debhello-0.0.tar.gz
 $ cd debhello-0.0
 $ debmake
   ... manual customization
 $ debuild
   ...
----

TIP: The *debuild* command in this and following examples may be substituted by equivalent commands such as the *sbuild* command.

TIP: If the upstream tarball in the *.tar.xz* format is available, use it instead of the one in the *.tar.gz* and *.tar.bz2* formats. The *xz* compression format offers the better compression than the *gzip* and *bzip2* compressions.

[[what-debmake]]
=== What is debmake?

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

* It always sets most of the obvious option states and values to reasonable defaults.
* It generates the upstream tarball and its required symlink if they are missing.
* It doesn't overwrite the existing configuration files in the *debian/* directory.
* It supports the *multiarch* package.
* It creates good template files such as the *debian/copyright* file compliant with *DEP-5*.

These features make Debian packaging with *debmake* simple and modern.

In retrospective, I created *debmake* to simplify this documentation.  I consider *debmake* to be more-or-less a demonstration session generator for tutorial purpose.

NOTE: Many packages are packaged using only a text editor while imitating how other similar packages are packaged and consulting how the Debian policy requires us to do.  This seems to me the most popular method for the real-life packaging activity.

The *debmake* command isn't the only helper script to make a Debian package.  If you are interested alternative packaging helper tools, please see:

* https://wiki.debian.org/AutomaticPackagingTools[Debian wiki: AutomaticPackagingTools] -- Extensive comparison of packaging helper scripts
* https://wiki.debian.org/CopyrightReviewTools[Debian wiki: CopyrightReviewTools] -- Extensive comparison of copyright review helper scripts

[[what-debuild]]
=== What is debuild?

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

* The *debian/rules* file defines how the Debian binary package is built.
* The *dpkg-buildpackage* command is the official command to build the Debian binary package.  For normal binary build, it executes roughly:
** ``*dpkg-source --before-build*'' (apply Debian patches, unless they are already applied)
** ``*fakeroot debian/rules clean*''
** ``*dpkg-source --build*'' (build the Debian source package)
** ``*fakeroot debian/rules build*''
** ``*fakeroot debian/rules binary*''
** ``*dpkg-genbuildinfo*'' (generate a ***.buildinfo** file)
** ``*dpkg-genchanges*'' (generate a ***.changes** file)
** ``*fakeroot debian/rules clean*''
** ``*dpkg-source --after-build*'' (unapply Debian patches, if they are applied during *--before-build*)
** ``*debsign*'' (sign the **\*.dsc** and ***.changes** files)
*** If you followed <<devscripts-setup>> to set the *-us* and *-uc* options, this step is skipped and you must run the *debsign* command manually.
* The *debuild* command is a wrapper script of the *dpkg-buildpackage* command to build the Debian binary package under the proper environment variables.
* The *sbuild* command is a wrapper script to build the Debian binary package under the proper chroot environment with the proper environment variables.

NOTE: See *dpkg-buildpackage*(1) for exact details.

[[step-upstream]]
=== Step 1: Get the upstream source

Let's get the upstream source.

.Download *debhello-0.0.tar.gz*
----
include::../examples/debhello-0.0_build-1/step000.slog[]
----

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

.*hello.c*
----
include::../examples/debhello-0.0_build-1/step101.slog[]
----

Here, the *Makefile* supports https://www.gnu.org/prep/standards/[GNU Coding Standards] and https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard[FHS]. Notably:

* build binaries honoring *$(CPPFLAGS)*, *$(CFLAGS)*, *$(LDFLAGS)*, etc.
* install files with *$(DESTDIR)* defined to the target system image
* install files with *$(prefix)* defined, which can be overridden to be */usr*

.*Makefile*
----
include::../examples/debhello-0.0_build-1/step102.slog[]
----

NOTE: The *echo* of the *$(CFLAGS)* variable is used to verify the proper setting of the build flag in the following example.

[[step-debmake]]
=== Step 2: Generate template files with debmake

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

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

----
include::../examples/debhello-0.0_build-1/step200.slog[]
----

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

* The source package name: *debhello*
* The upstream version: *0.0*
* The binary package name: *debhello*
* The Debian revision: *1*
* The package type: *bin* (the ELF binary executable package)
* The *-x* option: *-x1* (default for the single binary package)

Let's inspect generated template files.

.The source tree after the basic *debmake* execution.
----
include::../examples/debhello-0.0_build-1/step201.slog[]
----

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

.*debian/rules* (template file):
----
include::../examples/debhello-0.0_build-1/step202.slog[]
----

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

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

.*debian/control* (template file):
----
include::../examples/debhello-0.0_build-1/step203.slog[]
----

WARNING: If you leave ``*Section: unknown*'' in the template *debian/control* file unchanged, the *lintian* error may cause the build to fail.

Since this is the ELF binary executable package, the *debmake* command sets ``*Architecture: any*'' and ``*Multi-Arch: foreign*''.  Also, it sets required *substvar* parameters as ``*Depends: $\{shlibs:Depends}, $\{misc:Depends}*''.  These are explained in <<basics>>.

NOTE: Please note this *debian/control* file uses the RFC-822 style as documented in https://www.debian.org/doc/debian-policy/ch-controlfields.html#source-package-control-files-debian-control[5.2 Source package control files -- debian/control] of the ``Debian Policy Manual''. The use of the empty line and the leading space are significant.

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

.*debian/copyright* (template file):
----
include::../examples/debhello-0.0_build-1/step204.slog[]
----

[[step-maintainer]]
=== Step 3: Modification to the template files

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

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

.*debian/rules* (maintainer version):
----
include::../examples/debhello-0.0_build-1/step301.slog[]
----

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

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

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

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

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

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

.*debian/control* (maintainer version):
----
include::../examples/debhello-0.0_build-1/step302.slog[]
----

.*debian/copyright* (maintainer version):
----
include::../examples/debhello-0.0_build-1/step303.slog[]
----

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

.Template files under *debian/*. (v=0.0):
----
include::../examples/debhello-0.0_build-1/step400.slog[]
----

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

[[step-debuild]]
=== Step 4: Building package with debuild

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

----
sys::[head -n3  ../examples/debhello-0.0_build-1/step500.slog]
 ...
sys::[grep -A 1 -e '^ debian/rules clean' ../examples/debhello-0.0_build-1/step500.slog]
 ...
sys::[grep -A 10 -e '^ debian/rules binary' ../examples/debhello-0.0_build-1/step500.slog]
 ...
sys::[grep -e '^Now running lintian' ../examples/debhello-0.0_build-1/step500.slog]
 ...
sys::[grep -A 3 -e 'binary-without-manpage' ../examples/debhello-0.0_build-1/step500.slog]
 ...
sys::[tail -n1  ../examples/debhello-0.0_build-1/step500.slog]
----

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

The manpage should be added to the package as reported by the *lintian* package, as shown in later examples (see <<more>>).  Let's move on for now.

Let's inspect the result.

.The generated files of *debhello* version *0.0* by the *debuild* command:
----
include::../examples/debhello-0.0_build-1/step600.slog[]
----

You see all the generated files.

* The *debhello_0.0.orig.tar.gz* is a symlink to the upstream tarball.
* The *debhello_0.0-1.debian.tar.xz* contains the maintainer generated contents.
* The *debhello_0.0-1.dsc* is the meta data file for the Debian source package.
* The *debhello_0.0-1_amd64.deb* is the Debian binary package.
* The *debhello-dbgsym_0.0-1_amd64.deb* is the Debian debug symbol binary package. See <<dbgsym>>.
* The *debhello_0.0-1_amd64.build* file is the build log file.
* The *debhello_0.0-1_amd64.buildinfo* file is the meta data file generated by *dpkg-genbuildinfo*(1).
* The *debhello_0.0-1_amd64.changes* is the meta data file for the Debian binary package.

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

.The compressed archive contents of *debhello_0.0-1.debian.tar.xz*:
----
include::../examples/debhello-0.0_build-1/step701.slog[]
----

The *debhello_0.0-1_amd64.deb* contains the binary files to be installed to the target system.

The *debhello-debsym_0.0-1_amd64.deb* contains the debug symbol files to be installed to the target system..

.The binary package contents of all binary packages:
----
include::../examples/debhello-0.0_build-1/step700.slog[]
----

The generated dependency list of all binary packages.

.The generated dependency list of all binary packages (v=0.0):
----
include::../examples/debhello-0.0_build-1/step702.slog[]
----

CAUTION: Many more details need to be addressed before uploading the package to the Debian archive.

NOTE: If manual adjustments of auto-generated configuration files by the *debmake* command are skipped, the generated binary package may lack meaningful package description and some of the policy requirements may be missed.  This sloppy package functions well under the *dpkg* command, and may be good enough for your local deployment.

[[alt-patch]]
=== Step 3 (alternative): Modification to the upstream source

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

An alternative approach as the maintainer is to change the upstream source by modifying the upstream *Makefile* to set the $(prefix) value to */usr*.

The packaging is practically the same as the above step-by-step example except for two points in <<step-maintainer>>:

* Store the maintainer modifications to the upstream source as the corresponding patch files in the *debian/patches/* directory and list their filenames in the *debian/patches/series* file as indicated in <<patches>>.
There are several ways to generate patch files.  A few examples are given in these sections:
** <<diff-u>>
** <<dquilt>>
** <<dpkg-source-commit>>
* The maintainer modification to the *debian/rules* file doesn't have the *override_dh_auto_install* target as follows:
+
.*debian/rules* (alternative maintainer version):
----
include::../examples/debhello-0.0_build-2/step301.slog[]
----

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

NOTE: For this particular packaging case, the above <<step-maintainer>> using the *debian/rules* file is the better approach.  But let's keep on with this approach as a leaning process.

TIP: For more complicated packaging cases, both <<step-maintainer>> and <<alt-patch>> approaches need to be deployed.

[[diff-u]]
==== Patch by diff -u

Here is an example to create *000-prefix-usr.patch* by the *diff* command.

----
include::../examples/debhello-0.0_build-2/step120.slog[]
----

Please note that the upstream source tree is restored to the original state and the patch file is available as *000-prefix-usr.patch*.

This *000-prefix-usr.patch* is edited to be https://dep-team.pages.debian.net/deps/dep3/[DEP-3] conformant and moved to the right location as below.

----
include::../examples/debhello-0.0_build-2/step304.slog[]
----

[[dquilt]]
==== Patch by dquilt

Here is an example to create *000-prefix-usr.patch* by the *dquilt* command which is a simple wrapper of the *quilt* program.  The syntax and function of the *dquilt* command  is the same as the *quilt*(1) command, except for the fact that the patch is stored in the *debian/patches/* directory.

----
include::../examples/debhello-0.0_build-3/step304.slog[]
----

Here, *Makefile* in the upstream source tree doesn't need to be restored to the original state. The *dpkg-source* command invoked by the Debian packaging procedure in <<step-debuild>>, understands the patch application state recorded by the *dquilt* program in the *.pc/* directory.  As long as all the changes are committed by the *dquilt* command, the Debian source package can be built from the modified source tree.

NOTE: If the *.pc/* directory is missing, the *dpkg-source* command assumes that no patch was applied.  That's why the more primitive patch generation methods like in <<diff-u>> without generating the *.pc/* directory require the upstream source tree to be restored.

[[dpkg-source-commit]]
==== Patch by dpkg-source --commit

Here is an example to create *000-prefix-usr.patch* by the ``*dpkg-source --commit*'' command.

Let's edit the upstream source.

----
include::../examples/debhello-0.0_build-4/step310.slog[]
----

Let's commit it.

----
sys::[head -n1  ../examples/debhello-0.0_build-4/step340.slog]
... editor to edit the DEP-3 patch header
...
----

Let's see the result.

----
include::../examples/debhello-0.0_build-4/step350.slog[]
----

Here, the *dpkg-source* command performs exactly the same as what the sequences of the *dquilt* command did in <<dquilt>>.