DBS(7)								Debian Build System							    DBS(7)

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/Deb-
       Src3.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 stan-
       dard 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  previ-
       ous 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-spe-
       cific, 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 gen-
       erating 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/pack-
       age.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.

Debian								February 15th, 2011							    DBS(7)