A short TUTORIAL for debmake
----------------------------

This is the new debmake program written in Python.  This provides convenient
command to make a Debian package from the upstream VCS/archive/source.

Reminder
--------

Please do not forget that making of the package for the Debain distribution
takes much more efforts than just compiling the source code into working
set of installable binary files.  There are much more to it.

Please read the basic Debian documentations and "Debian New Maintainers' Guide"
as a starter and other important documents.

 * http://www.debian.org/doc/devel-manuals#policy
 * http://www.debian.org/doc/devel-manuals#devref
 * http://www.debian.org/doc/devel-manuals#maint-guide

Typical use cases
-----------------

1. execute in the untared source tree

 $ mkdir -p /path/to; cd /path/to
 $ tar -xvzf upstreampackage-1.0.tar.gz
 $ cd upstreampackage-1.0
 $ debmake
 $ debuild

2. execute with the upstream tar-ball

 $ mkdir -p /path/to; cd /path/to
 $ debmake -a upstreampackage-1.0.tar.gz
 $ cd upstreampackage-1.0
 $ debuild

3. execute in the upstream isource tree (usually in VCS)

* upstream source tree supporting "make dist"
 
 $ cd /path/to/upstream-vcs
 $ debmake -d
 $ cd ../upstreampackage-1.0
 $ debuild

* upstream source tree supporting quasi-native Debain package.
  (This is in the same format as native package except for the version number
   in the changelog which always ends with the Debian revision -1.)

 $ cd /path/to/upstream-vcs
 $ debmake -t
 $ cd ../upstreampackage-1.0
 $ debuild

4. make a arch=all package only
 $ cd /path/to/upstreampackage-1.0
 $ debmake -b"-:all"
 $ debuild
 (Please note the binary package "-" means that it is the same as upstream source name.)

5. make arch=any(foo) and all(foo-doc) packages
 $ debmake -b"foo:any,foo-doc:all"
 $ debuild

6. make arch=any(foo) and all(foo-doc) packages (Autotool based, python code)
 $ debmake -w python2 -b"foo:any,foo-doc:all"
 $ debuild

 (Please note binary package name such as lib* will make them arch=same.)

The debuild command used to make Debian binary packages from the source package
in the above examples may be substituted by the equivalent commands such as
pdebuild run with the cowbuilder backend.

7. scan source to check copyright+license text

 $ cd /path/to/upstream
 $ debmake -c |less

8. Get more template files

 * use "-x0" option to add only minimal templates to the source package.

 * use "-x1" option to add all typical templates to the source package
   with existing debian/* for a single binary package.

 * use "-x2" option to add all typical templates to the source package
   with existing debian/* for multi binary packages.

 * use "-x3" option to add specialized templates (dh_make compatibility)
   - prerm
   - preinst
   - postinst
   - postrm
   - init script and default
   - manpages

 * use "-x4" option to add specialized templates for the typical 
   copyright file examples.

 -- Osamu Aoki <osamu@debian.org>  Sun, 12 Jan 2014 07:21:13 +0000
