Provided by: dbs_0.45_all bug

NAME

       dbs - Debian Build System

DESCRIPTION

       dbs  is a collection of makefiles and shell scripts for easier handling
       of upstream sources and patches. Basically it adds  to  debian/rules  a
       special  target  which extracts upstream sources and applies patches to
       them in the correct order before the build target is called.

WHY DBS

       Suppose that you have just debianized a  package  with  dh_make(8)  and
       debhelper(7).   It may work for a simple package, but problems arise if
       the situation becomes really complicated:

       ·   If you modified the upstream source a lot, it  is  difficult  which
           part  of  .diff.gz is Debian-specific.  This means the upstream has
           to have a hard time if he/she wants  to  integrate  improvement  in
           .diff.gz to the next release.

       ·   If the format of the upstream source is not .tar.gz or if there are
           2 or more upstream tarballs, without dbs you  have  to  repack  the
           upstream  source.  This makes verification (such as a md5sum check)
           impossible.

       dbs solves these problems by putting  unchanged  upstream  tarballs  in
       .orig.tar.gz and patch files in .diff.gz.

       The  backdraft  of dbs is that it is more complicated and non-standard.
       Because it was not packaged for Debian for a long time there  are  many
       slightly  differing  flavours  around.  Dbs  should only be used if its
       special benefits are required. If you use dbs, include  a  README.build
       in  the  debian  directory  which lists the basic commands required for
       unpacking and adding a patch.  You could simply copy the one  from  the
       dbs examples directory.

THE FIRST STEP

       For  example, I have a package tenmado (0.1-1). It was packaged without
       dbs. Now I want to repackage it with dbs.

       The first thing to do is to create  a  empty  directory  and  copy  the
       upstream  tarballs  into  it,  the  name of the directory should be the
       standard package-upstream.version format.

       If the package is already in the Debian archive, you have to play  some
       dirty  trick on the upstream version number to overwrite .orig.tar.gz .
       You may want to contact the upstream in advance. Note that  you  should
       not  use  an epoch in this case. Choose a version-number that is higher
       than the current one and lower than the next  upstream  version.  Check
       with dpkg --compare-versions!  Here I use 0.1dbs.

           $ mkdir tenmado-0.1dbs
           $ cp tenmado-0.1.tar.gz tenmado-0.1dbs

       Make sure that the name of the upstream tarballs has a standard suffix.
       dbs tries to auto-detect which file is the upstream tarball by checking
       its  name. Currently .tgz, .tar.gz, .tar.bz and .tar.bz2 are supported.

       The upstream of tenmado distributes a PGP signature of the source code.
       It  is  a good idea to include it and the public key of the upstream in
       this directory too so that the upstream tarball can be verified  later.

           $ cp tenmado-0.1.tar.gz.asc tenmado-0.1dbs
           $ cp pub-key.txt tenmado-0.1dbs

       Then create the .orig.tar.gz that contains this directory.

           $ tar zcf tenmado_0.1dbs.orig.tar.gz tenmado-0.1dbs/

ADDING THE DEBIAN DIRECTORY

       The  next  step is to add the debian directory to the top of the source
       tree. If you have already debianized the package, copying the  previous
       debian directory is a good start.

           $ cp -R tenmado-0.1/debian/ tenmado-0.1dbs/

       Of course this debian directory needs modification. First, this package
       must build-depend on dbs, but this is trivial. The main  change  is  in
       debian/rules.

       The file /usr/share/dbs/dbs-build.mk provides makefile targets that are
       necessary to use dbs. Import this file in debian/rules  after  you  set
       DH_COMPAT (and, if necessary, TAR_DIR, which is described below).

           export DH_COMPAT=3
           TAR_DIR = tenmado-0.1
           # the dbs rules
           include /usr/share/dbs/dbs-build.mk

       dbs comes with one more makefile, that is, /usr/share/dbs/dpkg-arch.mk.
       It sets architecture specification strings. It is not dbs-specific, but
       including it too is a good thing.

           # convenient way to set architecture specification strings
           # the ifeq condition is here to allow them to be overridden
           # from the command line
           ifeq (,$(DEB_BUILD_GNU_TYPE))
             include /usr/share/dbs/dpkg-arch.mk
           endif

       The  build  target  must  be  called  after  the source is unpacked and
       patched.   The  right  way  to  do  this  is  to  have  the  build  (or
       build-stamp)  target  depend on the $(patched) target, which is defined
       in dbs-build.mk.

       Usually you need to move to the top of the source  tree  to  configure,
       build  or  install  it.  dbs  defines  BUILD_TREE  for this purpose. By
       default, it is $(SOURCE_DIR)/$(TAR_DIR) if TAR_DIR is  defined  (useful
       if  there  is  only one upstream tarball), $(SOURCE_DIR) otherwise. The
       default of SOURCE_DIR in dbs-build.mk is build-tree.

           configure: configure-stamp
           configure-stamp: $(patched)
                   dh_testdir
           # Add here commands to configure the package.
                   cd $(BUILD_TREE) && ./configure --prefix=/usr \
                                                   --bindir=/usr/games \
                                                   --mandir=/usr/share/man
                   touch configure-stamp

           build: configure-stamp build-stamp
           build-stamp: $(patched)
                   dh_testdir
           # Add here commands to compile the package.
                   cd $(BUILD_TREE) && $(MAKE)
                   touch build-stamp

           install: build
                   dh_testdir
                   dh_testroot
                   dh_clean -k
                   dh_installdirs
           # Add here commands to install the package into debian/tenmado.
                   cd $(BUILD_TREE) && $(MAKE) install  \
                                          DESTDIR=$(CURDIR)/debian/tenmado/

       The  clean  target  must  remove  the  directories   $(STAMP_DIR)   and
       $(SOURCE_DIR).  There  is no need to call $(MAKE) distclean because the
       entire build tree is removed anyway.

           clean:
                   dh_testdir
                   dh_testroot
                   rm -f build-stamp configure-stamp
           # Add here commands to clean up after the build process.
                   rm -rf $(STAMP_DIR) $(SOURCE_DIR)
                   dh_clean

       If you are using debhelper(7), you may need to modify  file  lists  for
       debhelper   (such   as   debian/package.docs)   and   the  argument  of
       dh_installchangelogs(1) (the upstream changelog).

MODIFYING THE UPSTREAM SOURCE

       To modify the upstream source appropriately, you  have  to  unpack  the
       upstream  source and apply some of the patches (it depends on what kind
       of modification you want to make). Doing this every time you modify the
       source  is  painful,  so  dbs  includes  a  dedicated command, that is,
       dbs-edit-patch(1).

       dbs-edit-patch requires the name of a patch file as  an  argument.   By
       convention,  the name of a patch file is two digits followed by a short
       description of what the patch does. In this way you can specify in what
       order the patch is applied.

       dbs-edit-patch  must be called in the top directory of the source tree.
       It unpacks the upstream tarballs in a subdirectory of $TMP_DIR (default
       /tmp)  and  applies  all  patches "before" (in the sense of the default
       order of sort(1))  the  patch  file  being  edited  (the  command  line
       argument).  I  recommend  overriding  $TMP_DIR  with  the -t (--tmpdir)
       option or the $TMP  environment  variable.  Building  a  package  in  a
       world-writable directory and distribute it is not a good practice.

       All  patch  files  are  saved  in  the  directory  $PATCH_DIR  (default
       $SOURCE_DIR/debian/patches). The default of SOURCE_DIR in  dbs-build.mk
       is the current directory (compare this with dbs-build.mk). All files in
       $PATCH_DIR are considered as patch files unless their name begins  with
       chk-.

       dbs-edit-patch  does  not  create  $TMP_DIR  or $PATCH_DIR. You have to
       create them if necessary before you call dbs-edit-patch.

           $ dbs-edit-patch -t ~/dbs-tmp/ 10pointer_to_readme
           Extracting source tenmado-0.1.tar.gz ... successful.
           Copying tenmado-0.1 to tenmado-0.1-old ... successful.
           Patch does not yet exist; will create a new patch 10pointer_to_readme

       Move to $TMP_DIR and you will find a directory which has the same  name
       as  the  patch  file  being  edited. This contains two directories (the
       source tree and its copy)  and  one  script  (named  dbs-update-patch).
       Edit  the  source  tree (that is, the directory whose name does not end
       with  -old)  and  run   ./dbs-update-patch   when   done.   Note   that
       ./dbs-update-patch  removes  all  files  whose name ends with .bak or ~
       before generating a patch.

MISC STUFF

       The setup target in dbs-build.mk is almost equal  to  $(patched),  with
       one  exception  - the setup target calls the command up-scripts (no, it
       is not ./up-scripts, it is something on your $PATH) before unpacking.

       The  script  /usr/share/dbs/dbs_split  reads  debian/package.in  (where
       package   is   a  package  name)  or  debian/packages.d/package.in  (if
       debian/packages.d exists)  and  split  it  at  the  line  which  begins
       %filename%, where filename can be any file name. If the package.in file
       contains a line that begins with %filename%, the text between that line
       and the next %filename% are written to the file debian/package.filename
       (or  debian/filename  -  the  behavior  is  the  same  as   debhelper).
       Typically,  package.in  files  are  generated  from  other  files,  for
       example, package.in.in .

FILES AND DIRECTORIES

       blah-version/foo.tar.gz, blah-version/bar.tar.bz2
              original vanilla upstream sources of the package  blah,  shipped
              in  the tar file blah_version.orig.tar.gz. dbs supports upstream
              sources in tar.gz, tgz, tar.bz and tar.bz2-format.

       debian/patches/
              dbs will apply all these patches using patch -p0 in alphanumeric
              order.   You  might  want  to  name  them e.g. 00_first.patch to
              99_last.patch.

       stampdir/
              Status- and log-files.

       buildtree/
              Actual build-directory.

BASIC INTERACTION WITH debian/rules

       See above for details.

       unpacked
              Unpacks the source(s) in build-tree/

       setup  Unpacks  the  source(s),  applies  patches,  calls  the  command
              up-scripts.

       make_patch
              Generates  a  diff between the (modified) tree in build-tree and
              the result of the setup-target in the file new.diff.

SEE ALSO

       dbs-edit-patch(1), /usr/share/doc/dbs/, the hello-dbs  source  package,
       http://snoopy.apana.org.au/~bam/debian/faq/#dbs

AUTHOR

       The  original  version  of  dbs  was  written by Adam Heath. Some other
       maintainers also used dbs by including their own copy of dbs  in  their
       packages.  Later  dbs  was  packaged  by  Brian  May. It was based on a
       modified version of dbs by Ben Collins.

       This man page was generated by Andreas Metzler, mostly by  reformatting
       the mini-HOWTO by Oohara Yuuma.