// vim:set filetype=asciidoc:
[[simple]]
== Simple packaging

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:

.Basics for the install from the upstream tarball
----
 $ 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?

NOTE: Actual packaging activities are often performed manually without using *debmake* while referencing only existing similar packages and "`https://www.debian.org/doc/debian-policy/[Debian Policy Manual]`".

The *debmake* command is the helper script for the Debian packaging. ("`<<manpage>>`")

* It creates good template files for the Debian packages.
* 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 provides short extracted license texts as *debian/copyright* in decent accuracy to help license review.

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.

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

* Debian wiki: "`https://wiki.debian.org/AutomaticPackagingTools[AutomaticPackagingTools]`" -- Extensive comparison of packaging helper scripts
* Debian wiki: "`https://wiki.debian.org/CopyrightReviewTools[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*

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

.The output from the *debmake* command
----
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* (without maintainer script supports for simplicity)

NOTE: Here, the *debmake* command is invoked with the *-x1* option to keep this tutorial simple.  Use of default *-x3* option is highly recommended.

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[]
----

Let's remove unused template files and edit remaining template files:

* *debian/README.source*
* *debian/source/local-option.ex*
* *debian/source/local-patch-header.ex*
* *debian/patches/series*  (No upstream patch)
* *clean*
* *dirs*
* *install*
* *links*

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

.Building package with *debuild*
----
include::../examples/debhello-0.0_build-1/step500.slog[lines=1..13]
 ...
include::../examples/debhello-0.0_build-1/step500.slog-binary[]
 ...
include::../examples/debhello-0.0_build-1/step500.slog-tail[]
----

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 (alternatives): 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 modify files in the upstream source.  For example, *Makefile* may be modified to set the *$(prefix)* value to */usr*.

NOTE: The above "`<<step-maintainer>>`" using the *debian/rules* file is the better approach for packaging for this example.  But let's continue on with this alternative approaches as a leaning experience.

In the following, let's consider 3 simple variants of this alternative approach to generate **debian/patches/*** files representing modifications to the upstream source in the Debian source format "`**3.0 (quilt)**`". These substitute "`<<step-maintainer>>`" in the above step-by-step example:

* "`<<diff-u-ap>>`"
* "`<<dquilt-ap>>`"
* "`<<auto-commit-ap>>`"

Please note the *debian/rules* file used for these examples 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[]
----

[[diff-u-ap]]
=== Patch by "`*diff -u*`" approach

Here, the patch file *000-prefix-usr.patch* is created using the *diff* command.

.Patch by "`*diff -u*`"
----
include::../examples/debhello-0.0_build-2/step120.slog[]
----

Please note that the upstream source tree is restored to the original state after generating a patch file *000-prefix-usr.patch*.

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

.*000-prefix-usr.patch* (DEP-3):
----
include::../examples/debhello-0.0_build-2/step304.slog[]
----

NOTE: When generating the Debian source package by *dpkg-source* via
*dpkg-buildpackage* in the following step of "`<<step-debuild>>`", the
*dpkg-source* command assumes that no patch was applied to the upstream source,
since the *.pc/applied-patches* is missing.

[[dquilt-ap]]
=== Patch by *dquilt* approach

Here, the patch file *000-prefix-usr.patch* is created using the *dquilt* command.

*dquilt* 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 generated patch is stored in the *debian/patches/* directory.

.Patch by *dquilt*
----
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 for the packaging.

NOTE: When generating the Debian source package by *dpkg-source* via
*dpkg-buildpackage* in the following step of "`<<step-debuild>>`", the
*dpkg-source* command assumes that patches were applied to the upstream source,
since the *.pc/applied-patches* exists.

The upstream source tree can be restored to the original state for the packaging.

.The upstream source tree (restored):
----
include::../examples/debhello-0.0_build-3/step410.slog[]
----

Here, *Makefile* is restored and the *.pc/applied-patches* is missing.

[[auto-commit-ap]]
=== Patch by "`*dpkg-source --auto-commit*`" approach

Here, the patch file isn't created in this step but the source files are setup to create **debian/patches/*** files in the following step of "`<<step-debuild>>`".

Let's edit the upstream source.

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

Let's edit *debian/source/local-options*:

.*debian/source/local-options* for *auto-commit*
----
include::../examples/debhello-0.0_build-4/step311.slog[]
----

Let's edit *debian/source/local-patch-header*:

.*debian/source/local-patch-header* for *auto-commit*
----
include::../examples/debhello-0.0_build-4/step312.slog[]
----

Let's remove **debian/patches/*** files and other unused template files.

.Remove unused template files
----
include::../examples/debhello-0.0_build-4/step340.slog[]
----

There are no **debian/patches/*** files at the end of this step.

NOTE: When generating the Debian source package by *dpkg-source* via
*dpkg-buildpackage* in the following step of "`<<step-debuild>>`", the
*dpkg-source* command uses options specified in *debian/source/local-options*
to auto-commit modification applied to the upstream source as
*patches/debian-changes*.

Let's inspect the Debian source package generated after the following "`<<step-debuild>>`" step and extracting files from *debhello-0.0.debian.tar.xz*.

.Inspect *debhello-0.0.debian.tar.xz* after *debuild*
----
include::../examples/debhello-0.0_build-4/step703.slog[]
----

Let's check generated **debian/patches/*** files.

.Inspect **debian/patches/*** after *debuild*
----
include::../examples/debhello-0.0_build-4/step705.slog[]
----

The Debian source package *debhello-0.0.debian.tar.xz* is confirmed to be
generated properly with **debian/patches/*** files for the Debian modification.