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.