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:

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