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 the creation of the real Debian package much more
efforts than just compiling the source code into working set of installable
binary files.  There are much more details to be addressed before uploading it
to the Debian archive.

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

   Use of quasi-native Debain package helps easy communication with 
   the downstream distros such as Ubuntu for bug fixes etc.

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/*.  Usable without customization.

 * use "-x2" option to add all typical templates to the source package
   with existing debian/*.  Customization desirable.

 * use "-x3" option to add specialized templates (dh_make compatibility)

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

9. run dpkg-depcheck from debmake with -j

 $ cd upstreampackage-1.0
 $ debmake -b'binpackage1,binpackage2' -j

This is handy when used with -d, -t, or -a options.

10. run debuild from debmake with -i

 $ cd upstreampackage-1.0
 $ debmake -i debuild

This is handy when used with -d, -t, or -a options.

See contents of /usr/share/doc/debmake/examples.tar.gz.

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