dbs
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
R dpkg --compare-versions !
Here I use 0.1dbs.
$ mkdir tenmado-0.1dbs $ cp tenmado-0.1.tar.gz tenmado-0.1dbsMake 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.1dbsThen 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.mkdbs comes with one more makefile, that is, R /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 endifThe 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 R 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
R /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_readmeMove 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 R 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%
the behavior is the same as debhelper). Typically, package.in files are
generated from other files, for example, package.in.in .
FILES AND DIRECTORIES
R 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),
R /usr/share/doc/dbs/ , the
R 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.
ČLÁNKY DO MAILU