Provided by: dbs_0.47_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.

WARNING

       dbs is deprecated, please switch to the  `3.0  (quilt)'  Debian  source
       package                format                instead.               See
       http://wiki.debian.org/Projects/DebSrc3.0#FAQ for a short guide how  to
       do it.

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:

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

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