I have actually found really useful documentation in the Internet (see references section below) that explains the package creation process in great detail. Nevertheless I thought it could make sense for me to put together a simplified tutorial, using a simple "hello world" program as an example.
As well, as a continuation of this post, I will write another article explaining how to use Pbuilder to compile the binary package for the different Debian distributions, currently wheezy, jessie and sid, using chroot environments.
For this purpose I've used a 64 bits server with Debian wheezy, current stable, version 7.4 (you can check yours at /etc/debian_version). This way I've been able to create packages for both i386 and amd64 architectures.
1.- The package creation process
There are several tools involved in this process, used to build, check and sign the package. Debuild is a wrapper that will call them appropriately, so we don't need to do it manually. Here is a brief description of the tools it invokes:
- dpkg-buildpackage: It creates a temporary directory with the package files, building later the .deb package with its content. To work properly, it heavily relies on the files in the special debian subdirectory: control, rules, changelog, etc.
- lintian: Dissects Debian packages trying to find bugs or policy violations.
- debsign: Signs packages (.dsc and .changes files) using GPG or PGP.
2.- Installing necessary software to build our packages
apt-get install dh-make build-essential
apt-get install devscripts fakeroot debootstrap pbuilder
3.- Setting up environment variables
DEBEMAIL="your_email_address@domain.com"
DEBFULLNAME="Your Name"
export DEBEMAIL DEBFULLNAME
4.- Uncompressing our source code (format of the tar.gz file is software-version.tar.gz)
In my case, for the purpose of this little how-to, I will build the Debian package for a simple "hello world" program written in C.
root@debian-package:/opt# tar -xvzf hello-0.1.tar.gz
hello-0.1/
hello-0.1/Makefile
hello-0.1/hello_world.c
hello_world.c:
#include <stdio.h>
main ()
{
printf("Hello World");
}
Makefile:
DESTDIR=/
INSTALL_LOCATION=$(DESTDIR)/usr/
CFLAGS:=$(shell dpkg-buildflags --get CFLAGS)
LDFLAGS:=$(shell dpkg-buildflags --get LDFLAGS)
all: hello_world
hello_world: hello_world.o
cc $(CFLAGS) $(LDFLAGS) -o $@ hello_world.o
install: hello_world_install
hello_world_install:
mkdir -p $(INSTALL_LOCATION)/bin
cp hello_world $(INSTALL_LOCATION)/bin
chmod 755 $(INSTALL_LOCATION)/bin/hello_world
clean:
rm -f *.o hello_world
There are a two interesting things that we can see in our Makefile:
- It uses DESTDIR variable to support the DESTDIR convention.
- Dpkg-buildflags is used to get C compiler options (CFLAGS) as well as linker options (LDFLAGS). This complies with the hardening requirements described in Debian documentation.
On the other hand, if your software has any external dependencies, you would need to install those, so you can compile it successfully. Typically you would be able to install them using apt-get.
5.- Building the Debian files skeleton
root@debian-package:/opt# cd hello-0.1
root@debian-package:/opt/hello-0.1# dh_make -f ../hello-0.1.tar.gz
Type of package: single binary, indep binary, multiple binary, library, kernel module, kernel patch?
[s/i/m/l/k/n] s
Maintainer name : Your name
Email-Address : your_email_address@domain.com
Date : Tue, 24 Jun 2014 21:50:02 +0000
Package Name : hello
Version : 0.1
License : blank
Type of Package : Single
Hit <enter> to confirm:
Done. Please edit the files in the debian/ subdirectory now. You should also
check that the hello Makefiles install into $DESTDIR and not in / .
As we only want to build a single binary package, I chose that option. Multiple binary package option would in fact, build multiple .deb packages.
Now we have a new directory, called "debian", with all the necessary Debian files that we need to build our package, including examples. This includes important files like:
- control: includes meta data about the package
- rules: specifies how the package is going to be built
- changelog: history of the debian package
- copyright: copyright information
As well, some other example files are created by dh_make, that we won't use at this point and can be deleted safely.
root@debian-package:/opt/hello-0.1/debian# rm -f *.ex *.EX README.*
root@debian-package:/opt/hello-0.1/debian# ls
changelog compat control copyright docs rules source
6.- Control file
The control file has two sections, the first part refers to the source package and the second to the binary one. More information about the different fields can be found in deb-control manual page.
Source: hello
Maintainer: Your Name <your_email_address@domain.com>
Build-Depends: debhelper (>= 8.0.0)
Standards-Version: 3.9.3
Section: utils
Package: hello
Priority: extra
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: Test package for hello world
This software literally prints "hello world".
The variable ${shlibs:Depends} will be substituted by the shared library dependencies needed to build our binary package. Those are calculated automatically by dh_shlibdeps, one of the tools of the debhelper suite.
7.- Changelog file
root@debian-package:/opt/hello-0.1# cat debian/changelog
hello (0.1-1) unstable; urgency=low
* Initial release (Closes: #100) # there was no previous ITP
-- Your Name <your_email_address@domain.com> Wed, 25 Jun 2014 19:50:08 +0000
ITP stands for Intend to Package and, for our package to be included in a Debian distribution, the changelog file should close an existing bug. For our example we closed bug #100, this way we won't see lintian warnings requiring for this number later.
Note: We can use "dch -i" command to edit our changelog file.
8.- Copyright file
root@debian-package:/opt/hello-0.1# cat debian/copyright
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: hello
Files: *
Copyright: 2014 Your Name <your_email_address@domain.com>
License: GPL-2
This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.
This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>
.
On Debian systems, the complete text of the GNU General
Public License version 2 can be found in "/usr/share/common-licenses/GPL-2".
9.- Rules file
The rules file invokes the original software Makefile script, as well as the debhelper suite of tools (with the prefix "dh_). These tools handle different tasks, including the creation of the .deb file (dh_builddeb).
#!/usr/bin/make -f
# -*- makefile -*-
# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1
%:
dh $@
The rules file can be run with different targets: clean (invokes make clean), build (invokes make) and binary (invokes make install). Usage of fakeroot command is recommended so you don't need to build your packages as root.
root@debian-package:/opt/hello-0.1# fakeroot debian/rules clean
dh clean
dh_testdir
dh_auto_clean
make[1]: Entering directory `/opt/hello-0.1'
rm -f *.o hello_world
make[1]: Leaving directory `/opt/hello-0.1'
dh_clean
root@debian-package:/opt/hello-0.1# fakeroot debian/rules build
dh build
dh_testdir
dh_auto_configure
dh_auto_build
make[1]: Entering directory `/opt/hello-0.1'
cc -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -c -o hello_world.o hello_world.c
cc -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -Wl,-z,relro -o hello_world hello_world.o
make[1]: Leaving directory `/opt/hello-0.1'
dh_auto_test
root@debian-package:/opt/hello-0.1# fakeroot debian/rules binary
dh binary
dh_testroot
dh_prep
dh_installdirs
dh_auto_install
make[1]: Entering directory `/opt/hello-0.1'
mkdir -p /opt/hello-0.1/debian/hello/usr//bin
cp hello_world /opt/hello-0.1/debian/hello/usr//bin
chmod 755 /opt/hello-0.1/debian/hello/usr//bin/hello_world
make[1]: Leaving directory `/opt/hello-0.1'
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_pysupport: This program is deprecated, you should use dh_python2 instead. Migration guide: http://deb.li/dhs2p
dh_installinit
dh_installmenu
dh_installmime
dh_installmodules
dh_installlogcheck
dh_installlogrotate
dh_installpam
dh_installppp
dh_installudev
dh_installwm
dh_installxfonts
dh_installgsettings
dh_bugfiles
dh_ucf
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
dpkg-gencontrol: warning: File::FcntlLock not available; using flock which is not NFS-safe
dh_md5sums
dh_builddeb
dpkg-deb: building package `hello' in `../hello_0.1-1_amd64.deb'.
At this point we have already our .deb file created!. We can see the shared libraries needed to build our program (in this case libc6, because of the stdio.h include) listed in our debian/hello.substvars file:
root@debian-package:/opt/hello-1.0# cat debian/hello.substvars
shlibs:Depends=libc6 (>= 2.2.5)
misc:Depends=
10.- Inspecting package contents
root@debian-package:/opt/hello-0.1# find debian/hello
debian/hello
debian/hello/DEBIAN
debian/hello/DEBIAN/control
debian/hello/DEBIAN/md5sums
debian/hello/usr
debian/hello/usr/bin
debian/hello/usr/bin/hello_world
debian/hello/usr/share
debian/hello/usr/share/doc
debian/hello/usr/share/doc/hello
debian/hello/usr/share/doc/hello/copyright
debian/hello/usr/share/doc/hello/changelog.Debian.gz
root@debian-package:/opt/hello-0.1# dpkg --contents ../hello_0.1-1_amd64.deb
drwxr-xr-x root/root 0 2014-07-02 02:07 ./
drwxr-xr-x root/root 0 2014-07-02 02:07 ./usr/
drwxr-xr-x root/root 0 2014-07-02 02:07 ./usr/bin/
-rwxr-xr-x root/root 6160 2014-07-02 02:07 ./usr/bin/hello_world
drwxr-xr-x root/root 0 2014-07-02 02:07 ./usr/share/
drwxr-xr-x root/root 0 2014-07-02 02:07 ./usr/share/doc/
drwxr-xr-x root/root 0 2014-07-02 02:07 ./usr/share/doc/hello/
-rw-r--r-- root/root 940 2014-07-02 01:12 ./usr/share/doc/hello/copyright
-rw-r--r-- root/root 174 2014-06-30 23:51 ./usr/share/doc/hello/changelog.Debian.gz
11.- Package maintenance scripts
It is possible to supply scripts that will run when the package is installed, upgraded or removed. These scripts are the control information files: preinst, postinst, prerm, postrm. And in some cases, may prompt the user if necessary, typically through a program such as debconf. More information on how to create this scripts can be found at the
Debian Policy Manual.
12.- Debuild
As mentioned before, we can use debuild to build the Debian binary and source packages, check it with lintian, and sign it with debsign. We can use "debuild -us -uc" to build the packages without signing the .changes file. More information can be found with "man debuild".
root@debian-package:/opt/hello-0.1# debuild -us -uc
dpkg-buildpackage -rfakeroot -D -us -uc
dpkg-buildpackage: warning: using a gain-root-command while being root
dpkg-buildpackage: source package hello
dpkg-buildpackage: source version 0.1-1
dpkg-buildpackage: source changed by Your Name <your_email_address@domain.com>
dpkg-source --before-build hello-0.1
dpkg-buildpackage: host architecture amd64
fakeroot debian/rules clean
dh clean
dh_testdir
dh_auto_clean
make[1]: Entering directory `/opt/hello-0.1'
rm -f *.o hello_world
make[1]: Leaving directory `/opt/hello-0.1'
dh_clean
dpkg-source -b hello-0.1
dpkg-source: info: using source format `3.0 (quilt)'
dpkg-source: info: building hello using existing ./hello_0.1.orig.tar.gz
dpkg-source: info: building hello in hello_0.1-1.debian.tar.gz
dpkg-source: info: building hello in hello_0.1-1.dsc
debian/rules build
dh build
dh_testdir
dh_auto_configure
dh_auto_build
make[1]: Entering directory `/opt/hello-0.1'
cc -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -c -o hello_world.o hello_world.c
cc -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -Wl,-z,relro -o hello_world hello_world.o
make[1]: Leaving directory `/opt/hello-0.1'
dh_auto_test
fakeroot debian/rules binary
dh binary
dh_testroot
dh_prep
dh_installdirs
dh_auto_install
make[1]: Entering directory `/opt/hello-0.1'
mkdir -p /opt/hello-0.1/debian/hello/usr//bin
cp hello_world /opt/hello-0.1/debian/hello/usr//bin
chmod 755 /opt/hello-0.1/debian/hello/usr//bin/hello_world
make[1]: Leaving directory `/opt/hello-0.1'
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_pysupport: This program is deprecated, you should use dh_python2 instead. Migration guide: http://deb.li/dhs2p
dh_installinit
dh_installmenu
dh_installmime
dh_installmodules
dh_installlogcheck
dh_installlogrotate
dh_installpam
dh_installppp
dh_installudev
dh_installwm
dh_installxfonts
dh_installgsettings
dh_bugfiles
dh_ucf
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
dpkg-gencontrol: warning: File::FcntlLock not available; using flock which is not NFS-safe
dh_md5sums
dh_builddeb
dpkg-deb: building package `hello' in `../hello_0.1-1_amd64.deb'.
dpkg-genchanges >../hello_0.1-1_amd64.changes
dpkg-genchanges: warning: missing Priority for source files
dpkg-genchanges: including full source code in upload
dpkg-source --after-build hello-0.1
dpkg-buildpackage: full upload (original source is included)
Now running lintian...
warning: the authors of lintian do not recommend running it with root privileges!
W: hello: binary-without-manpage usr/bin/hello_world
Finished running lintian.
Both source and binary packages have been built now. One of Lintian checks warned us about our package not including a manual page for hello_world binary. Although it is just a reminder, more information about this warning can be displayed using "lintian-info -t
lintian_tag" command. In our case
lintian_tag is "binary-without-manpage".
root@debian-package:/opt/hello-0.1# ls -l ../
total 32
drwxr-xr-x 3 root root 4096 Jul 2 03:07 hello-0.1
-rw-r--r-- 1 root root 3020 Jul 2 03:09 hello_0.1-1_amd64.build
-rw-r--r-- 1 root root 1407 Jul 2 03:08 hello_0.1-1_amd64.changes
-rw-r--r-- 1 root root 3338 Jul 2 03:08 hello_0.1-1_amd64.deb
-rw-r--r-- 1 root root 1378 Jul 2 03:07 hello_0.1-1.debian.tar.gz
-rw-r--r-- 1 root root 735 Jul 2 03:07 hello_0.1-1.dsc
-rw-r--r-- 1 root root 441 Jun 30 23:43 hello_0.1.orig.tar.gz
-rw-r--r-- 1 root root 441 Jun 30 23:43 hello-0.1.tar.gz
13.- Extracting sources
Finally we can use dpkg-source command to extract the sources from our package:
root@debian-package:/opt# dpkg-source -x hello_0.1-1.dsc
dpkg-source: warning: extracting unsigned source package (hello_0.1-1.dsc)
dpkg-source: info: extracting hello in hello-0.1
dpkg-source: info: unpacking hello_0.1.orig.tar.gz
dpkg-source: info: unpacking hello_0.1-1.debian.tar.gz
References
https://www.debian.org/doc/debian-policy/
http://www.debian-administration.org/articles/336
https://www.debian.org/doc/manuals/packaging-tutorial/packaging-tutorial.en.pdf
