Packaging a Qt application

= Packaging a Qt application for Maemo=

Finding your package in debian
If you want to port a Qt package to Maemo, you should check and see if it is already packaged for debian and use that package if you can - this will save you time and effort. You can search in debian's Package Tracking System (PTS) to see if it is there. There is a search system on the PTS page, under the "distribution" drop-down, select 'any', this will search throughout debian's repositories to find the package. Debian has more than 20,000 packages just in its stable distribution so your application is likely already packaged.

If you find the package already exists in debian, you can get the source, including the packaging source, with apt-get. To do this, you'll have to edit your /etc/apt/sources.list, you can follow this recipe;

$ echo “deb http://ftp.it.debian.org/debian/ unstable main contrib non-free” >> /etc/apt/source.list $ apt-get update $ apt-cache search "application name" $ apt-get source "application name"

To learn more about the /etc/apt/sources.list you can do a 'man sources.list' if you are running debian or a debian based GNU/Linux distro.

Porting the debian package to a Maemo package
If your application has been already packaged for debian, you can begin your maemo packaging with this section. Once you have the source of the debian package, you will need to make some modifications to that package for it to build under Maemo. For the complete Maemo Package Policy, use this link to a pdf.

In order to create a new package for maemo, you'll need to: $mv myapp myapp-0.1 $cd myapp-0.1 $mkdir src $cp * src $mv src/appname.pro src/src.pro
 * Rename the upstream source directory in Package-Version (eg: myapp-0.1)
 * Create “src” directory in Package-Version/
 * Copy all the files in the src/
 * Rename src/appname.pro in src/src.pro

Append the following chunk to end of your src/src.pro. The chunk adds install section to your qmakefile

unix { #VARIABLES isEmpty(PREFIX) { PREFIX = /usr/local } BINDIR = $$PREFIX/bin DATADIR =$$PREFIX/share

DEFINES += DATADIR=\"$$DATADIR\" PKGDATADIR=\"$$PKGDATADIR\"


 * 1) MAKE INSTALL

INSTALLS += target desktop iconxpm icon26 icon40 icon64

target.path =$$BINDIR

desktop.path = $$DATADIR/applications/hildon desktop.files += $${TARGET}.desktop

iconxpm.path = $$DATADIR/pixmap iconxpm.files += ../data/maemo/$${TARGET}.xpm

icon26.path = $$DATADIR/icons/hicolor/26x26/apps icon26.files += ../data/26x26/$${TARGET}.png

icon40.path = $$DATADIR/icons/hicolor/40x40/apps icon40.files += ../data/40x40/$${TARGET}.png

icon64.path = $$DATADIR/icons/hicolor/64x64/apps icon64.files += ../data/64x64/$${TARGET}.png }

QMAKEVERSION = $$[QMAKE_VERSION] ISQT4 = $$find(QMAKEVERSION, ^[2-9]) isEmpty( ISQT4 ) { error("Use the qmake include with Qt4.4 or greater, on Debian that is qmake-qt4"); }
 * Create a myapp-0.1/myapp.pro file like this:

TEMPLATE = subdirs SUBDIRS = src dh_make --createorig --single -e maintainer@email.org -c gpl
 * Run dh_make to debianize the source archive, it creates:
 * An archive with the unchanged upstream source (orig.tar.gz)
 * Some basic files in the debian directory
 * Some example files (*.EX *.ex)

Having a look inside the debian/ dir
At this point the directory my-app contains
 * the source directory ( src/ )
 * the debian directory (debian/)

Inside the debian dir we have the files needed for the creation of the debian package
 * Changelog - Application's change log
 * Compat - Debian helper compatibly version
 * Control - Describes the packages to be made
 * Copyright - Copyright text
 * Rules - A binary makefile containing the rules to build the package

Maemo Packaging Policy
Maemo packages follow the Debian Policy, but there are some items where Maemo:
 * Is more strict (it is an embedded distribution)
 * Is more relaxed
 * Only a target device (Nokia Internet Tablet)
 * Only a specified UI (Hildon)
 * Only one user.
 * Differs from Debian because Maemo has different:
 * Objectives
 * Maintainers
 * Infrastructure

Editing the rules file
The rules file generated by dh_make will be modified in order to look like this one. We are using qmake, so we haven't a configure file to run. If you cut-and-paste following file, notify that empty space beginning of lines it TAB characters, it is not multiple space characters. If you cut-and-paste the following chunk, you most propably get spaces instead tabs and the file does not wok

APPNAME := my_app_name builddir: mkdir -p builddir
 * 1) !/usr/bin/make -f

builddir/Makefile: builddir cd builddir && qmake-qt4 PREFIX=/usr ../$(APPNAME).pro

build: build-stamp

build-stamp: builddir/Makefile dh_testdir # Add here commands to compile the package. cd builddir && $(MAKE) touch $@

clean: dh_testdir dh_testroot rm -f build-stamp # Add here commands to clean up after the build process. rm -rf builddir dh_clean install: build dh_testdir dh_testroot dh_clean -k dh_installdirs

# Add here commands to install the package into debian/your_appname cd builddir && $(MAKE) INSTALL_ROOT=$(CURDIR)/debian/$(APPNAME) install binary-indep: build install
 * 1) Build architecture-independent files here.
 * 1) We have nothing to do by default.

binary-arch: build install dh_testdir dh_testroot dh_installdocs dh_installexamples dh_installman dh_link dh_strip dh_compress dh_fixperms dh_installdeb dh_shlibdeps dh_gencontrol dh_md5sums dh_builddeb
 * 1) Build architecture-dependent files here.

binary: binary-indep binary-arch .PHONY: build clean binary-indep binary-arch binary install configure

Editing the Control file
Basically it specifies for each package (source or binary) a name, some dependencies, a description etc... For a Maemo package these fields are very important:
 * Section: Only the packages in the user segment are showed by App Installer.
 * Maintainer: This field MUST be changed if the upstream package is modified
 * XB-Maemo-Icon26: It contains the PNG icon encoded in base64 visible in the Application Installer

Source: my-application Section: user/valid_subsection Priority: optional Maintainer: name surname  XSBC-Original-Maintainer: name surname  Build-Depends: debhelper (>= 5), libqt4-dev, OTHERS_BUILD DEPENDECIES Standards-Version: 3.7.3

Package: my-application Architecture: any Depends: ${shlibs:Depends}, ${misc:Depends} Description: A simple test application A very simple application with a short description. Which spans multiple lines actually. XB-Maemo-Icon-26: iVBORw0KGgoAAAANSUhEUgAAABoAAAAaCAYAAACpSkzOAAAABmJLR0QA/wD/AP+g vaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH1gURDQoYya0JlwAAAU9J REFUSMftlL1KA0EUhb/NZl/ggnHQxsJUxt5CUucVJCCkDfgyKdIGG5/A0s5HEBtJ EdDAQGBgmw0YJmMzgXXYza5CtNkDW9zZw5z7c+ZCgwb/Ai3i9sVl/Bq8RIs4LRK1 gJDsKvJyNXmJMuYTsMoY1zpgozaABdYArQNPZQ1kfyGU7SpqVwxzAMwABWhgpIwp 4vWBB+AUWAI3ypjnfEXtPU4bLKx9vErTeCeiRSYF+fTn1j5dp2myE9EiU+DSi3wX ymeqRQAmZ3EcA5E/fgO6BULT8zhOcrwXoJdrXRa2Lgps2y2odAUcBUIXQdz78YyC SldAp8b7+bXrIv91qjZBietqCc2DjbAt4b2WxJkyZljVujlwp0U0cPxuLcAIuC+4 dKxFlsDJarvdAGP/b6hFnDImYs+uG3hbO2AB3Jbsur63tQM+fFx3bzZocEB8AdV2 gJBZgKTwAAAAAElFTkSuQmCC

Valid subsections are:
 * accessories
 * communication
 * games
 * multimedia
 * office
 * other
 * programming
 * support
 * themes
 * tools

Editing the Changelog file
It is the log of the changes for a specified application version. It's important file because it sets the binary/binaries and the source packages version and revision. If an upstream package is re-packaged or modified for maemo, the Maemo revision string should be appended to the upstream revision. So if in Debian the package name was something like "Myapp-0.4-2" in maemo this package will be called "Myapp-0.4-2maemo0". The number after the "maemo" string is a progressive number.

Application menu icon & position
The Maemo application menu detects automatically an app that provides a .desktop file in /usr/share/application/hildon. If you don't have desktop file, create one to src directory.

[Desktop Entry] Encoding=UTF-8 Version=0.1 Type=Application Name=myapp Exec=/usr/bin/myapp Icon=myapp X-HildonDesk-ShowInToolbar=true X-Osso-Type=application/x-executable

Maemo menu structure is completely different from Debian:
 * An unmodified Debian package installs the proper .desktop in /usr/share/applications
 * Applications that use the debian menu are displayed in the extra menu

In order to show our application in the correct Maemo menu: src/*.desktop usr/share/applications/hildon src/*.png usr/share/icons/hicolor/26x26/apps
 * debian/myapp.install moves the .desktop file and icons in the right directory

maemo-select-menu-location myapp.desktop
 * debian/postinst should call maemo-select-menu-location utility to permit the user to choose the menu location.  This works only in Diablo, it don't work in Fremantle.
 * 1) !/bin/sh

Checking Maemo Packages
Lintian dissects Debian packages and reports bugs and policy violations. It contains automated checks for many aspects of Debian policy as well as some checks for common errors. Unfortunately it doesn't check conformance to the additional Maemo policy.

Currently Maemo doesn't provide any tools to check its policy.

Building the binary and the source package
To build only binary package/s $dpkg-buildpackage -rfakeroot -b we can install these binary package with dpkg: $dpkg -i myapp.deb

To build the source package and to sign it with your gpg key (ABCDEF12) dpkg-buildpackage -rfakeroot -sa -S -kABCDEF12 At this point, if you have tested your package and it works fine you can upload it in extras/extras-devel.

= Example = You can download the source package of qt-maemo-example from the extra-devel repository just running

apt-get source qt-maemo-example

This command will download the:

- unmodified source (.orig.tar.gz)

- debian dsc file (.dsc)

- diff file (.diff)

and after it will launch automatically dpkg -x file.dsc in order to uncompress the orig.tar.gz and apply the changes.

= Useful Links = Qt4Maemo at garage

Desktop entry spec 0.9.4