=== Debian packaging workflow

The Debian packaging workflow to create the Debian binary package involves generating several specifically named files as defined in the ``Debian Policy Manual''. 

It can be summarized in 5 steps as follows.

1. The upstream tarball is downloaded as the 'package-version'**.tar.gz** file.
2. The upstream tarball is untared to create many files under the 'package-version'**/** directory.
3. 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.
4. The Debian package specification files are added to the upstream source under the 'package-version'**/debian/** directory.
* The *debmake* command invoked in the 'package-version/' directory helps this by providing template files.
* *debian/rules* (This is *makefile*.  Use of *dh* and *debhelper*(8) is the current best practice.)
* *debian/control* (This defines the binary package names and package dependency.)
* *debian/changelog* (This is required.)
* *debian/copyright* (This is required.)
* ... (edit these files manually to their perfection according toy the ``Debian Policy Manual'')
5. 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.
* 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

=== The *debmake* command

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

* It makes template files for the step 4 just as *dh_make* does.
* It always sets most of the obvious option states and values to reasonable defaults.
* It deligates most of the heavy lifting to its backend packages: *debhelper*, *dpkg-dev*, *devscripts*, etc.
* 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 can function as a wrapper script integrating all the steps 1-5.
* 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 source files 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.

A functional single binary package can be generated automatically without touching files in the 'package-version'**/debian/** directory generated by the *debmake* command.  Such a package can be used locally.

* To comply with the strict quality requirements of the Debian archive, these template files must be manually adjusted to their perfection before the upload.

* For  example, you can get a Python module packaged by the Python distutils and make its Debian binary package by simply running "*debmake -d -i debuild*" in its
  untared source tree.

The functional multi binary package always requires some extra manual works. These works are done as follows:

* Invoke *debmake* with the *-b"*'package1:type1, ...'" and *-j* options in the 'package-version/' directory.

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

* Check the contents of 'package'**.install.log** to identify file paths in *debian/tmp*.

* Update *debian/control* and *debian/*'binarypackage'**.install** files using the above information.

* Update other *debian/** files as needed.

* Build binary packages with *debuild*, *pdebuild*, etc.

* Files installed into *debian/tmp* are split by **debian/**'binarypackage'**.install** into each 'binarypackage_version-revision_arch'**.deb**.

TIP: Make sure to protect the arguments of the *-b*, *-f*, *-n*, and *-w* options from the shell interference by quoting them properly.


