Bug#153581: dbs: documentation: how to use dbs
Package: dbs
Version: 0.11
Severity: wishlist
[Cc:ing to debian-devel because I want comments]
how to use dbs
by Oohara Yuuma <oohara@libra.interq.or.jp>
$Id: dbs.txt,v 1.19 2002/07/19 15:18:51 oohara Exp $
This document describes how to use the dbs (Debian Build System) package.
* what is dbs
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.
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.
* why dbs
Suppose that you have just debianized a package with dh_make(1) and
debhelper(1). 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 have 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 re-pack the
upstream source. This makes verification (such as a md5sum check)
impossible.
dbs solves these problems by putting unpacked upstream tarballs
in .orig.tar.gz and patch files in .diff.gz .
* 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 unpacked
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. 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 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, you may need to modify file lists for debhelper
(such as debian/package.docs) and the argument of dh_installchangelogs
(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 the directory $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 .
The script /usr/share/dbs/file2cat auto-detects compressed files by checking
their names, reads them and prints them to stdout. It is used internally
by dbs.
-- System Information
Debian Release: 2.2
Kernel Version: Linux grain 2.4.18 #1 Fri Jul 19 13:47:12 JST 2002 i686 unknown
Versions of the packages dbs depends on:
hi make 3.79.1-10 The GNU version of the "make" utility.
--
To UNSUBSCRIBE, email to debian-devel-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: