View source for 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, for example Windows and Mac.

== Is there a simple(r) way ? ==

Note that the instructions on this page apply to QtSDK 1.0.x and QtCreator 2.0.x. The use of the [http://labs.qt.nokia.com/2011/03/01/qt-sdk-1-1-beta-released/ QtSDK 1.1] is strongly encouraged, as it has incorporated/automated most of the steps outlined below. 

===Using the Wizard===
With QtSDK 1.1, all you need to do is go to Build-> Publish Project... --> Start Wizard. As shown [http://doc.qt.nokia.com/qtcreator-2.2/creator-publishing-to-maemo-extras.html here].

You can then choose to upload your app directly to the repository using your [https://garage.maemo.org/ maemo garage] account, or you can do the more straightforward approach of choosing not to upload through QtSDK (make sure that the "do not upload" box is ticked) and instead uploading the generated files using [https://garage.maemo.org/extras-assistant/index.php Maemo Extras Assistant] (check your /tmp/qtc_packing_appname/ folder for the .changes, .tar.gz and .dsc files).

====Issues====
Some developers have encountered problems with the debian/rules file using this method, in which case it should be noted that one working solution is to uncomment the "qmake PREFIX=/usr" and "dh_shlibdeps" lines in the rules file (as suggested by notation in the actual file itself). Another common solution is to check that each line of the rules file is indented with TABS and not spaces.

===Using Custom Build Steps===
Another way to generate the .changes, .tar.gz and .dsc files is to add a custom step to the build configuration . This is also a fairly straightforward process and is outlined [http://qt-funk.blogspot.com/2011/02/generating-maemoorg-compatible-source.html here] and [http://raeda.blog.com/2011/02/19/upload-qt-apps-to-extras-devel-from-windows/ here]

== 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 <code>QSettings</code> class works as expected on Maemo 5, so make use of it for configuration files and storing system information.
* 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.

<ol>
<li>
Add a directory for the maemo-specific files in the source directory. Call it "<code>maemofiles</code>". It will contain the following two files:
<ul>
<li>
an icon file — make it a 48×48 PNG, which you can build in GIMP, or whatever else you use to make images. <code>appname_icon.png</code> is probably a good name, but use whatever you like. In the final package this file will end up in <code>/usr/share/icons/hicolor/48x48/apps</code>
</li>
<li>
the <code>appname.desktop</code> file. This tells the system how to present the app in the menus and where to find the executable. It will end up in <code>/usr/share/applications/hildon</code> in the final package. For more information on what goes in this file, see the article on the [[desktop file format]].  Also, note that the .pro changes below will write the app into /usr/bin/appname/appname, so make sure you have the desktop file match this.
</li>
</ul>
</li>
<li>
Next we need to tell the project how to find those files and where to put them. Edit the <code>.pro</code> file for your app and add a <code>unix{}</code> section as follows (make sure the directories and filenames match the ones you just created above):
<pre>
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
}
</pre>
</li>
<li>
Add a folder to the source directory named "<code>debian</code>" folder and copy the Debian files needed from <code>appname-build-maemo</code> directory that was created when you did a Maemo target build in Qt Creator. The files you need for a basic app are: <code>changelog</code>, <code>compat</code>, <code>control</code>, <code>copyright</code>, <code>rules</code>
</li>
<li>
The Debian files need to be updated for your application as follows:
<ul>
<li>
add a file called "<code>optify</code>" and put the word "<code>auto</code>" in the file as the only contents. This will cause the application to be automatically "optified" for install on an [[Nokia N900|N900]].
</li>
<li>
make sure the "<code>changelog</code>" 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 application is built later on, so make sure this file is correct. The "<code>dch</code>" 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 "<code>dch -v 1.0.1</code>" (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 <code>git</code> tools which automatically update this file, if you care to figure those out.
</li>
<li>
change the contents of the "<code>compat</code>" 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.
</li>
<li>
update the "<code>control</code>" file with the proper information:
<ul>
<li>
Make sure it has these on the "<code>Build-Depends</code>" line: <code>debhelper (>= 5), libqt4-dev</code>
</li>
<li>
The "<code>section</code>" entry on the "<code>control</code>" file can have values as found on the [[Packaging/Guidelines#Sections|packaging guidelines]] article
</li>
<li>
add the icon to the <code>control</code> file. See the [[Packaging#Displaying an icon in the Application Manager next to your package|package icon section]] in the [[packaging]] article for more information
</li>
</ul>
</li>
<li>
set the <code>copyright</code> file as needed, including any copyright info on external items you use such as images or libraries.
</li>
<li>
set the <code>rules</code> file to be slightly different than the one found in the article on [[packaging a Qt application]], so that it is as follows:
<source lang="make">
#!/usr/bin/make -f
APPNAME := appname
builddir:
	mkdir -p builddir

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
# Build architecture-independent files here.
binary-indep: build install
# We have nothing to do by default.

# Build architecture-dependent files here.
binary-arch: build install
	dh_testdir
	dh_testroot
	dh_installdocs
	dh_installexamples
	dh_installman
	dh_link
#	dh_strip --dbg-package=appname-dbg
	dh_compress
	dh_fixperms
	dh_installdeb
	dh_shlibdeps
	dh_gencontrol
	dh_md5sums
	dh_builddeb

binary: binary-indep binary-arch
.PHONY: build clean binary-indep binary-arch binary install configure
</source>
""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.
</li>
</ul>
</li>
<li>
Copy the source directory (including the <code>debian</code> and <code>maemofiles</code> directories, but not the <code>appname.pro.user</code> file) into another directory (outside the source directory) called <code>app-version</code>, for example <code>appname-1.0.0</code>, in your work directory. We'll call this the <code>app-version</code> directory. The version number should match the one in the <code>changelog</code>.
<li>
In the <code>app-version</code> directory, issue the following commands: <pre>dpkg-buildpackage</pre>This should build a binary Debian package. This isn't really required to create the files we need, but is a good check that all is in working order.
<pre>dpkg-buildpackage -sa -S</pre>
This will build the source package files we need for submission. They wil be found in the work directory (the parent of the <code>app-version</code> directory)
Note: You can also issue the <code>dpkg-buildpackage</code> commands with <code>~/NokiaQtSDK/Maemo/4.6.2/bin/mad</code> in front of them (or wherever you find the mad binary files), for example:
<pre>~/NokiaQtSDK/Maemo/4.6.2/bin/mad dpkg-buildpackage -sa -S</pre>
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.
</li>
</ol>

== Submitting ==

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

[[Category:Packaging]]
[[Category:Qt]]