Deb Package
From MapbenderWiki
Programs you need for development
Before you start anything, you should make sure that you have properly installed additional packages needed for development. None of the packages are marked as essential but you should install all of them.
1. build-essential :The most important package to install on your development system. Once you try to install it, it will pull in other packages required to have a basic build environment.
2. file - this handy program can determine what type a file is.(see file(1))
3. patch - this very useful utility will take a file containing a difference listing (produced by the diff program) and apply it to the original file, producing a patched version. (see patch(1))
4. perl - Perl is one of the most used interpreted scripting languages on today's Unix-like systems, often referred to as "Unix's Swiss Army Chainsaw". (see perl(1))
5. autoconf, automake, autotools-dev - many newer programs use configure scripts and Makefile files preprocessed with help of programs like these. (see "info autoconf", "info automake"). The autotools-dev keeps up-to-date versions of certain auto files and has documentation about the best way to use those files.
6. dh-make, debhelper - dh-make is necessary to create the skeleton of our mapbender package, and it will use some of the debhelper tools for creating packages. It makes the whole process very much easier to start, and control afterwards. (see dh_make(1), debhelper(1), /usr/share/doc/debhelper/README)
7. devscripts - (see /usr/share/doc/devscripts/README.gz)
8. fakeroot - this utility lets you emulate being root which is necessary for some parts of the build process. (see fakeroot(1))
9. gnupg - a tool that enables you to digitally sign packages. This is especially important if you want to distribute it to other people, and you will certainly be doing that when your work gets included in the Debian distribution. (see gpg(1))
10. xutils-dev - some programs, usually those made for X11, also use these programs to generate Makefile files from sets of macro functions. (see imake(1), xmkmf(1))
11. lintian - this is the Debian package checker that can let you know of any common mistakes after you build the package, and explains the errors found. (see lintian(1), /usr/share/doc/lintian/lintian.html/index.html)
12. pbuilder - this package contains programs which are used for creating and maintaining chroot environment. Building Debian package in this chroot environment verifies the proper build dependency and avoid FTBFS (Fails To Build From Source) bugs. (see pbuilder(8) and pdebuild(1))
13. patchutils - this package contains some utilities to work with patches such as the lsdiff , interdiff and filterdiff commands.
14. quilt - this package helps you to manage a series of patches by keeping track of the changes each of them makes. They are logically organized as a stack, and you can apply (=push), un-apply (=pop), refresh them easily by traveling into the stack. (see quilt(1), /usr/share/doc/quilt/README.Debian)
15. python - Python is another of the most used interpreted scripting languages on the Debian system that combines remarkable power with very clear syntax. (see python(1))
Programs to create Makefile
A lot of Free programs are written in the C and C++ lunguages. Many of these use Autotools or CMake to make them portable across different platforms. These tools are used to generate Makefile and other required source files. Then, such programs are built with usual "make; make install".
Autotools are the GNU build system comprising Autoconf, Automake, Libtool, and Gettext. You can notice such sources by the configure.ac, Makefile.am, and Makefile.in files.
The first step of Autotools work flow is usually that the upstream runs autoreconf -i -f in the source and distributes this source with generated files.
configure.ac-----+-> autoreconf -+-> configure
Makefile.am -----+ | +-> Makefile.in
src/Makefile.am -+ | +-> src/Makefile.in
| +-> config.h.in
automake
aclocal
aclocal.m4
autoheader
See info autoconf and info automake before editing configure.ac and Makefile.am.
The second step of Autotools work flow is usually that the user obtains this distributed source and runs "./configure && make" in the source to compile program into a binary.
Makefile.in -----+ +-> Makefile -----+-> make -> binary
src/Makefile.in -+-> ./configure -+-> src/Makefile -+
config.h.in -----+ +-> config.h -----+
|
config.status -+
config.guess --+
You can change many things in the Makefile file such as the default file install location using the command option, e.g. ./configure --prefix=/usr. Although it is not required, updating the configure and other files with autoreconf -i -f as the user may improve the compatibility of the source.
Package name and version
You should start packaging with a completely clean (pristine) source directory, or simply with freshly unpacked sources.
For the package to be built correctly, you must make the program's original name lowercase, and you should move the source directory to packagename-version.
Initial debianization
Let's set up the Bash shell environment variable $DEBEMAIL and $DEBFULLNAME so many Debian maintenance tools recognize your name and email address to use for packages as follows.
$ cat >>~/.bashrc <<EOF DEBEMAIL=your.email.address@example.org DEBFULLNAME="Firstname Lastname" export DEBEMAIL DEBFULLNAME EOF
Let's make initial debianization by issuing the dh_make command as follows.
$ . ~/.bashrc $ cd ~/mapbender/mapbender-2.6 $ dh_make -f ../mapbender.2.6.tar.gz
See dh_make(1) for details.
Some information will come up. It will ask you what sort of package you want to create. Mapbender is a single binary package - it creates only one binary, and thus one .deb file - so we will select the first option, with the "s" key, check the information on the screen and confirm by pressing "ENTER".
After this execution of dh_make, a copy of the upstream tarball is created as mapbender_2.6.orig.tar.gz in the parent directory to accommodate the creation of the non-native Debian source package with the debian.tar.gz later.
$ cd ~/debian ; ls -F mapbender-2.6/ mapbender-2.6.tar.gz mapbender_2.6.orig.tar.gz
Please note 2 key features in this mapbender_2.6.orig.tar.gz file name:
Package name and version are separated by the "_" (underscore).
There is the .orig before the .tar.gz.
If you accidentally erased some template files while working on them, you can recover them by running dh_make with the --addmissing option again in an already debianized directory.
Set up quilt
The quilt program offers the basic method to record modification to the source for the Debian packaging. Since slightly different default is desirable for Debian packaging, let's set up ~/.quiltrc as follows.
d=. ; while [ ! -d "$d/debian" -a `readlink -e $d` != / ]; do d="$d/.."; done
if [ -d "$d/debian" ] && [ -z "$QUILT_PATCHES" ]; then
# Debian packaging case and unset $QUILT_PATCHES
QUILT_PATCHES=debian/patches
QUILT_PATCH_OPTS="--unified-reject-files"
QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"
if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
fi
See quilt(1) and /usr/share/doc/quilt/quilt.html for how to use quilt.
Installation of files to the destination
Normally, programs install themselves in the /usr/local subdirectory. Since it is reserved for system administrator's (or user's) private use, Debian packages must not use that directory but should use system directories such as the /usr/bin subdirectory following the Filesystem Hierarchy Standard (FHS, /usr/share/doc/debian-policy/fhs/fhs-2.3.html).
Normally, make(1) is used to automate building the program and the execution of "make install" installs programs directly to the desired destination by the install target of the Makefile file. In order for Debian to provide binary packages, the build system installs programs to the file tree image created under a temporary directory instead to the actual destination.
The Makefile file follows the GNU conventions to support $(DESTDIR) variable (/usr/share/doc/gnu-standards/standards.html#Makefile-Conventions).
If you need to make changes in the Makefile file, you should make sure to support these $(DESTDIR) variable. The $(DESTDIR) variable is unset in it and is prepended to each file path used for the program installation. The packaging script will set $(DESTDIR) to the temporary directory.
The temporary directory used by the dh_auto_install command is chosen as debian/mapbender-2.6 for single binary packages. Everything that is contained in the temporary directory will be installed on a user's system when they install your package, the only difference is that dpkg will be installing the files in the root directory.
Bear in mind that even though your program installs in debian/mapbender-2.6, it still needs to behave correctly when placed in the root directory, i.e. when installed from the .deb package. So you must not allow the build system to hardcode strings like /home/<username>/debian/mapbender-2.6/usr/share/package into the package file.
Here's the relevant part of Mapbender's Makefile file:
# Where to put binary on 'make install'?
BIN = /usr/local/bin
# Where to put icons on 'make install'?
ICONS = /usr/local/share/mapbender
We see that the files are set to install under /usr/local. Change those paths to:
# Where to put binary on 'make install'?
BIN = $(DESTDIR)/usr/bin
# Where to put icons on 'make install'?
ICONS = $(DESTDIR)/usr/share/mapbender
This is because Debian packages never install files beneath /usr/local -- that tree is reserved for the system administrator's use. Such files on Debian systems go under /usr instead.
The more exact locations for binaries, icons, documentation etc. are specified in the Filesystem Hierarchy Standard (see /usr/share/doc/debian-policy/fhs/).
So, we should install the binary in /usr/bin instead of /usr/local/bin, the manual page in /usr/share/man/man1 instead of /usr/local/man/man1 etc. Notice how there's no manual page mentioned in mapender's Makefile, but since the Debian Policy requires that every program has one, we'll make one later and install it in /usr/share/man/man1.
Some programs don't use Makefile variables to define paths such as these. This means you might have to edit some real C sources in order to fix them to use the right locations. But where to search, and exactly what for? You can find this out by issuing:
$ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
grep will run recursively through the source tree and tell you the filename and the line number for all matches.
Edit those files and in those lines replace /usr/local/lib with usr/lib.
$ vim '+argdo %s/usr\/local\/lib\//usr\/lib\//gce|update' +q \
$(find . -type f -name '*.[c|h]')
Be careful that you don't mess up the rest of the code! :-)
After that you should find the install target (search for line that starts with install:, that will usually work) and rename all references to directories other than ones defined at the top of the Makefile.
After your upstream bug fix, mapbender's install target said:
install: mapbender-target
install ./mapbender $(BIN)
install icons/* $(ICONS)
install mapbenderrc-example $(HOME)/.mapbenderrc
Let's fix this and record this with the quilt command as debian/patches/install.patch.
$ quilt new install.patch
$ quilt add Makefile
Let's change this for Debian package as following using the editor:
install: mapbender-target
install -d $(BIN) $(ICONS) $(DESTDIR)/etc
install ./mapbender $(BIN)
install -m644 icons/* $(ICONS)
install -m644 mapbenderrc-example $(DESTDIR)/etc/mapbenderrc
You've surely noticed that there's now a "install -d" command before the other commands in the rule. The original Makefile didn't have it because usually the /usr/local/bin and other directories already exist on the system where one runs "make install". However, since we will install into our own empty (or even nonexistent) directory, we will have to create each and every one of those directories.
We can also add in other things at the end of the rule, like the installation of additional documentation that the upstream authors sometimes omit:
install -d $(DESTDIR)/usr/share/doc/mapbender/html
cp -a docs/* $(DESTDIR)/usr/share/doc/mapbender/html
After careful check, if everything is fine, ask quilt to refresh the patch to create debian/patches/install.patch and add its description.
$ quilt refresh
$ quilt header -e
... describe patch
Now you have a series of patches.
Required files under the debian directory
There is a new subdirectory under the program's source directory, it's called debian. There are a number of files in this directory that we should edit in order to customize the behavior of the package. The most important of them are control, changelog, copyright and rules, which are required for all packages.
control file
This file contains various values which dpkg, dselect, apt-get, apt-cache, aptitude, and other package management tools will use to manage the package.
Here is a sample control file dh_make can create for us:
1 Source: mapbender
2 Section: unknown
3 Priority: extra
4 Maintainer: Abhishek Singh <singhabhishek.bit@gmail.com>
5 Build-Depends: debhelper (>= 7.0.50~)
6 Standards-Version: 3.0.0
7 Package: mapbender
8 Architecture: any
9 Depends: ${shlibs:Depends}, ${misc:Depends}
10 Description: <insert up to 60 chars description>
11 <insert long description, indented with spaces>
The fields may restrict their applicability to particular versions of each named package. These versions are listed in parentheses after each individual package name, and they should contain a relation from the list below followed by the version number. The relations allowed are: <<, <=, =, >= and >> for strictly lower, lower or equal, exactly equal, greater or equal and strictly greater, respectively. For example,
Depends: foo (>= 1.2), libbar1 (= 1.3.4)
Conflicts: baz
Recommends: libbaz4 (>> 4.0.7)
Suggests: quux
Replaces: quux (<< 5), quux-foo (<= 7.6)
The last feature you need to know about is ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc. These entries are substituted by the list generated by other debhelper components when the dh_gencontrol(1) command is executed.
dh_shlibdeps(1) will scan it for binaries and libraries determine their shared library dependencies and detect which packages they are in, such as libc6 or xlib6g, after your package has been built and installed into the temporary directory. This list of shared library dependencies is used for ${shlibs:Depends}.
The package list generated by the dh_perl(1) is used for ${perl:Depends}.
Some debhelper commands may make the generated package need to depend on some other packages. This list of required packages is used for ${misc:Depends}.
Having said all that, we can leave the "Depends:" field exactly as it is now, and insert another line after it saying "Suggests: file", because mapbender can use some features provided by that file package.
Line 10 is the short description. In this case I am changing that to "back office software and client framework for spatial data infrastructures".
Line 11 is where the long description goes. This should be a paragraph which gives more details about the package.
Finally, here is the updated control file:
1 Source: mapbender
2 Section: x11
3 Priority: optional
4 Maintainer: Abhishek Singh<singhabhishek.bit@gmail.com>
5 Build-Depends: debhelper (>= 7.0.5), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
6 Standards-Version: 3.0.0
7 Homepage: http://www.mapbender.org/
8 Package: mapbender
9 Architecture: any
10 Depends: ${shlibs:Depends}, ${misc:Depends}
11 Suggests: file
12 Description: back office software and client framework for spatial data infrastructures
13 The software is implemented in PHP, JavaScript and XML and
14 dual licensed under GNU GPL and Simplified BSD license. It
15 provides a data model and web based interfaces for displaying,
16 navigating and querying OGC compliant map services.
17 Mapbender is an official Open Source Geospatial Foundation
18 project and all about managing maps! Mapbender helps to manage,
19 organize, protect and monitor map services, users and applications.
20 The maps themselves come from many different Map Services and
21 can be located anywhere in the world.
copyright file
This file contains the information about package upstream resources, copyright and license information.
dh_make can give you a template copyright file. Let's use the "--copyright gpl2" option here to get a template file for the mapbender package released under GPL-2.
Also have a look at GNU GPL and Simplified_BSD_license before modifying the template copyright file generated by dh_make.
You must fill in missing information such as the place you got the package from, the actual copyright notice and their license to complete this file. For the common free software licenses such as GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-3, BSD, Apache or the Artistic license, you can just refer to the appropriate file in /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license.
changelog file
This is a required file, which has a special format described in the Debian Policy Manual, 4.4 'debian/changelog'. This format is used by dpkg and other programs to obtain the version number, revision, distribution and urgency of your package.
For you, it is also important, since it is good to have documented all changes you have done. It will help people downloading your package to see whether there are issues with the package that they should know about. It will be saved as /usr/share/doc/mapbender/changelog.Debian.gz in the binary package.
dh_make create a default one for this package.
rules file
Now we need to take a look at the exact rules which dpkg-buildpackage(1) will use to actually create the package. This file is actually another Makefile, but different from the one(s) in the upstream source. Unlike other files in debian, this one is marked as executable.
Targets of rules file :
Every rules file, as any other Makefile, consists of several targets and their rules specifying how to handle the source. The simplified explanation of targets are the following.
1.clean target: to clean all compiled, generated, and useless files in the build-tree. (required)
2.build target: to build the source into compiled programs and formatted documents in the build-tree. (required)
3.install target: to install files into a file tree for each binary package under the debian directory. If defined, binary* targets effectively depend on this target. (optional)
4.binary target: to create all binary packages (effectively combination of binary-arch and binary-indep targets). (required
5.binary-arch target: to create arch-dependent (Architecture: any) binary packages in the parent directory. (required)
6.binary-indep target: to create arch-independent (Architecture: all) binary packages in the parent directory. (required)
7.get-orig-source target: to obtain the most recent version of the original source package from upstream archive site. (optional)
dh_make gives us a default rules file. You should also read "info make" for more information.
Default rules file
Newer dh_make generates a very simple but powerful default rules file using the dh command:
1 #!/usr/bin/make -f
2 # -*- makefile -*-
3 # Sample debian/rules that uses debhelper.
4 # This file was originally written by Joey Hess and Craig Small.
5 # As a special exception, when this file is copied by dh-make into a
6 # dh-make output file, you may use that output file without restriction.
7 # This special exception was added by Craig Small in version 0.37 of dh-make.
8
9 # Uncomment this to turn on verbose mode.
10 #export DH_VERBOSE=1
11
12 %:
13 dh $@
(I've added the line numbers. In the actual rules file, the leading white spaces are TAB codes.)
You are probably familiar with lines like line 1 from shell and Perl scripts. It tells the operating system that this file is to be processed with /usr/bin/make.
Line 10 can be uncommented to set DH_VERBOSE variable to 1. Then, the dh command will output which dh_* commands are executed by the dh command. You can also add "export DH_OPTIONS=-v" line here. Then each dh_* command will output which commands are executed by each dh_* command. This helps you to understand what exactly is going on behind this simple rules file and to debug its problems. This new dh is a core part of the debhelper tools and does not hide anything from you.
Lines 12 and 13 are where all the work is done. The % sign means any targets which then call a single program, dh with the target name. The dh command is a wrapper script which runs appropriate sequences of dh_* programs depending on its argument.
"debian/rules clean" runs "dh clean"; which in turn runs the following:
dh_testdir
dh_auto_clean
dh_clean
"debian/rules build" runs "dh build"; which in turn runs the following:
dh_testdir
dh_auto_configure
dh_auto_build
dh_auto_test
"fakeroot debian/rules binary" runs "fakeroot dh binary"; which in turn runs the following:
dh_testroot
dh_prep
dh_installdirs
dh_auto_install
dh_install
dh_installdocs
dh_installchangelogs
dh_installexamples
dh_installman
dh_installcatalogs
dh_installcron
dh_installdebconf
dh_installemacsen
dh_installifupdown
dh_installinfo
dh_pysupport
dh_installinit
dh_installmenu
dh_installmime
dh_installmodules
dh_installlogcheck
dh_installlogrotate
dh_installpam
dh_installppp
dh_installudev
dh_installwm
dh_installxfonts
dh_bugfiles
dh_lintian
dh_gconf
dh_icons
dh_perl
dh_usrlocal
dh_link
dh_compress
dh_fixperms
dh_strip
dh_makeshlibs
dh_shlibdeps
dh_installdeb
dh_gencontrol
dh_md5sums
dh_builddeb
"fakeroot debian/rules binary-arch" runs "fakeroot dh binary-arch"; which in turn runs the same sequence as "fakeroot dh binary" but with the "-a" option appended for each command.
"fakeroot debian/rules binary-indep" runs "fakeroot dh binary-indep"; which in turn runs almost the same sequence as "fakeroot dh binary" but excluding dh_strip, dh_makeshlibs, and dh_shlibdeps with the "-i" option appended for each remaining command.
The function of dh_* commands are almost self-evident from their names. There are few notable ones worth making (over)simplified explanation here assuming typical build environment based on Makefile.
dh_auto_clean usually executes the following if Makefile exists with the distclean target.
make distclean
dh_auto_configure usually executes the following if ./configure exists (arguments abbreviated for readability).
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...
dh_auto_build usually executes the following to execute the first target of Makefile if it exists.
make
dh_auto_test usually executes the following if Makefile exists with the test target.
make test
dh_auto_install usually executes the following if Makefile exists with the install target (line folded for readability).
make install \
DESTDIR=/path/to/package_version-revision/debian/package
Targets which require the fakeroot command contain dh_testroot. If you are not pretending to be root using this command, it exits with an error.
The important part to know about the rules file created by dh_make, is that it is just a suggestion. So now you have to customize it to fit your needs. Only things that you must not change are the names of the rules, because all the tools use these names, as mandated by the Debian Policy.
Although "install" is not required target, it is supported. "fakeroot dh install" behaves like "fakeroot dh binary" but stops after dh_fixperms.
Customization of rules file
There are many ways to customize the rules file created with the new dh command.
Customizing the "dh $@" command :
1.Add support of the dh_pysupport command. (The best choice for Python.)
Install the python-support package in "Build-Depends:".
2.Use "dh $@" as usual. (This is enabled by default)
This handles Python modules using the python-support framework.
3.Add support of the dh_pycentral command.
Install the python-central package in "Build-Depends:".
Use "dh --with python-central $@" instead.
This also deactivates the dh_pysupport command.
This handles Python modules using the python-central framework.
4.Add support of the dh_installtex command.
Install the tex-common package in "Build-Depends:".
Use "dh --with tex $@" instead.
This registers Type 1 fonts, hyphenation patterns, or formats with TeX.
5.Add support of the dh_quilt_patch and dh_quilt_unpatch commands.
Install the quilt package in "Build-Depends:".
Use "dh --with quilt $@" instead.
This applies and un-applies patches to the upstream source from files in the debian/patches directory for the 1.0 source package.
This is not needed if you use the new 3.0 (quilt) source package.
6.Add support of the dh_dkms command.
Install the dkms package in "Build-Depends:".
Use "dh --with dkms $@" instead.
This correctly handles DKMS usage by the kernel module package.
7.Add support of the dh_autotools-dev_updateconfig and dh_autotools-dev_restoreconfig commands.
Install the autotools-dev package in "Build-Depends:".
Use "dh --with autotools-dev $@" instead.
This updates and restores config.sub and config.guess.
8.Add support of the dh_autoreconf and dh_autoreconf_clean commands.
Install the dh-autoreconf package in "Build-Depends:".
Use "dh --with autoreconf $@" instead.
This updates the GNU Build System files and restores them after the build.
9.Add support to the bash completion feature.
Install the bash-completion package in "Build-Depends:".
Use "dh --with bash-completion $@" instead.
This installs bash completions using configuration file at debian/package.bash-completion.
For sources using Autotools, use combination of above as "dh --with autotools-dev --with autoreconf $@" to be most current with the GNU Build System.
Many dh_* commands invoked by the new dh command can be customized by the corresponding configuration files in the debian directory.
Some dh_* commands invoked by the new dh command may require you to run it with some arguments or to run additional commands with them or to skip them. For such cases, you create an override_dh_foo target with its rule in the rules file only for the dh_foo command you want to change.
Please note that the dh_auto_* commands tend to do more than what has been discussed as (over)simplified explanation to take care all the corner cases. Use of simplified equivalent command instead of these in override_dh_* targets except the override_dh_auto_clean target is a bad idea since it may kill such debhelper's smart features.
If you want to store the system configuration data for the mapbender package in the /etc/mapbender directory instead of the usual /etc directory, you can override the default --sysconfig=/etc argument given by the dh_auto_configure command to the ./configure command by the following.
override_dh_auto_configure:
dh_auto_configure -- --sysconfig=/etc/mapbender
The arguments given after -- are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than the ./configure command here since it will only override the --sysconfig argument and keeps well intended other arguments to the ./configure command.
If Makefile of a source for mapbender requires you to specify build as its target to build it , you create an override_dh_auto_build target to enable it.
override_dh_auto_build:
dh_auto_build -- build
This ensures to run $(MAKE) with all the default arguments given by the dh_auto_build command and build argument.
If Makefile of a source for mapbender requires you to specify the packageclean target to clean it for Debian package instead of the distclean or clean targets in the Makefile file, you create an override_dh_auto_clean target to enable it.
override_dh_auto_clean:
$(MAKE) packageclean
If Makefile of a source for mapbender contains test target which you do not want to run for the Debian package building process, you can use empty override_dh_auto_test target to skip it.
override_dh_auto_test:
If mapbender has an unusual upstream changelog file called FIXES, dh_installchangelogs will not install that file by default. The dh_installchangelogs command requires FIXES as its argument to install it.
override_dh_installchangelogs:
dh_installchangelogs FIXES
