Packaging Qt Creator Apps for Maemo Extras

While there are a few pages relating to packaging Maemo and Qt apps, this document is designed to provide step-by-step instructions for taking a working app in Qt Creator and publishing it to the Maemo extras development repository for all to enjoy. The methods here have been tested with basic Qt apps in an Ubuntu Linux environment. Hopefully additional feedback and edits will provide information about working on the lesser platforms available (e.g. Windows and Mac).

Qt Creator Notes
A few notes on Qt Creator, especially if you haven't started yet:
 * create a work directory and create the Qt Creator project directory within that. For example, if your app is called supercalc, create a directory called supercalc-work (or whatever you want to call it) and create the supercalc project directory within that.  When you do all of the building and testing within Qt Creator, it creates lots of directories.  You can control where they are created, but this lets you use the default locations.
 * If you create a Desktop target, you can run your app outside the simulator and test the functionality directly in a native app. Sometimes this is easier than working within the simulator.
 * The QSettings class works as expected on Maemo 5, so make use of it for configuration files and storing system info.
 * Before attempting the packaging, you should make sure that a build with the Maemo target is successful.

Packaging
Now that you have a working application, you can package it as follows. For the purposes of this discussion, we will refer to the work directory and the source directory. The source directory is the directory created for the Qt project--the one with the .pro file in it. The work directory is probably the parent directory of the source directory, but it can easily be somewhere else. unix { INSTALLS += target desktop icon48 target.path = /usr/bin/appname desktop.path = /usr/share/applications/hildon desktop.files += maemofiles/appname.desktop icon48.path = /usr/share/icons/hicolor/48x48/apps icon48.files += maemofiles/appname_icon.png }
 * Add a directory for the maemo-specific files in the source directory. Call it "maemofiles".  It will contain the following two files:
 * an icon file - make it a 48x48 png, which you can build in Gimp, or whatever else you use to make images. appname_icon.png is probably a good name, but use whatever you like. In the final package this file will end up in /usr/share/icons/hicolor/48x48/apps
 * the appname.desktop file. This tells the system how to present the app in the menus and where to find the executable.  It will end up in /usr/share/applications/hildon/ in the final package.  For more info on what goes in this file, see the Desktop_file_format page.
 * Next we need to tell the project how to find those files and where to put them. Edit the .pro file for your app and add a unix{} section  as follows (make sure the directories and filenames match the ones you just created above):

APPNAME := appname builddir: mkdir -p builddir
 * Add a folder to the source directory named "debian" folder and copy the debian files needed from appname-build-maemo directory that was created when you did a maemo target build in Qt Creator. The files you need for a basic app are: changelog, compat, control, copyright, rules
 * The debian files need to be updated for your app as follows:
 * add a file called "optify" and put the word "auto" in the file as the only contents. This will cause the app to be automatically "optified" for install on an N900.
 * make sure the "changelog" file is up to date and in the proper format. There should be an entry for the current release version.  The version number here is the one used to determine the version number when the app is built later on, so make sure this file is correct.  The "dch" command in linux will add an entry in the proper format and open an editor for you to do changes on it.  From the source directory, type "dch -v 1.0.1" (substitute your version number for 1.0.1, of course), and an editor will open with a new entry for you to use.  There are also some git tools which automatically update this file, if you care to figure those out.
 * change the contents of the "compat" file to be just a single digit: the number 5. (It is probably 7 now, which is not compatible with the autobuilder.)  Numbers higher than 5 will cause mysterious errors in the autobuilder.
 * update the "control" file with the proper info:
 * Make sure it has these on the "Build-Depends" line: debhelper (>= 5), libqt4-dev
 * The "section" entry on the "control" file can have values as found on the Packaging page or on http://hildon-app-mgr.garage.maemo.org/packaging-stable.html
 * add the icon to the control file. Details on this are also on http://wiki.maemo.org/Packaging
 * set the copyright file as needed, including any copyright info on external items you use such as images or libraries.
 * set the rules file to be slightly different than the one found at Packaging_a_Qt_application, so that it is as follows:
 * 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_compress dh_fixperms dh_installdeb dh_shlibdeps dh_gencontrol dh_md5sums dh_builddeb
 * 1) Build architecture-dependent files here.
 * 1) 	dh_strip --dbg-package=appname-dbg

binary: binary-indep binary-arch .PHONY: build clean binary-indep binary-arch binary install configure ""IMPORTANT: These are tabs and not spaces!"" Change the application name in the beginning of the file to your app name. Also note that the debug line is commented out. This change appears to be necessary in order to work properly. dpkg-buildpackage This should build a deb package. This isn't really required to create the files we need, but is a good check that all is in working order. dpkg-buildpackage -sa -S This wil build the source package files we need for submittal. They wil be found in the work directory (the parent of the app-version directory) Note: You can also issue the dpkg-buildpackage commands with ~/NokiaQtSDK/Maemo/4.6.2/bin/mad in front of them (or wherever you find the mad binary files), for example: ~/NokiaQtSDK/Maemo/4.6.2/bin/mad dpkg-buildpackage -sa -S This will use Madde to generate the files instead of doing it directly in the OS. This may be preferable, but I have seen it work fine either way for creating the source. The native buildpackage command will build an x86 or x86_64 package, and the Madde buildpackage will build an armel package.
 * Copy the source directory (including the debian and maemofiles directories, but not the appname.pro.user file) into another directory (outside the source directory) called app-version (e.g. appname-1.0.0) in your work directory. We'll call this the app-version directory.  The version number should match the one in the changelog.
 * In the app-version directory, issue the following commands:

Submitting
At this point you should have all the files needed to upload to the Maemo extras assistant at https://garage.maemo.org/extras-assistant/index.php. The files you need should be located in your work directory.