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.

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.