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.