Single Instance Harmattan Applications

[toc align_right="yes" depth="3"]

How to create single-instance applications for N9 Harmattan Meego 1.2

Important note, read before [[Image:|Image:]]!

This workaround will apply to the Qt 4.7.3 first release supporting Harmattan Meego 1.2 devices. The problem is superseeded buy the new Qt 4.7.4 update including the Qt Creator 2.3.0 release. (added Sept, 14, 2011)

This How-to aims to reduce to other developers the amount of time that me and other contributors have already spent to find a workaround to build single-instance applications for the N950 / N9 platforms. At the actual date the problem refers to a bug in the SDK package 4.7.3 so it is possible - hopefully - that this page become unuseful in few time. To solve this problem I have found a lot of help but what I am trying here is to give too the reason that need this solution.

Note: The behavior of the packages created with the Qt SDK 4.7.3 evidentiates only working on the physical device. Using the QEMU Harmattan emulator in Qt-Creator it is not clear it this issue can be seen. Thus all those developers that are developing/porting their applications on the Harmattan platform without the possibility to test them on a physical device (formerly the N950) probably ignore this problem at all.

Starting point

• The compiled/packaged applications for Qt-Meego are not single-instance
• Multi-instance is prohibitied
• This is a bug of Qt-Creator (or the SDK or both, not sure of the origin)

Workaround

Modify the rules file

Open with a external editor the rules file in the qtc_packaging/debian_harmattan folder changing the following line

[TAB]$(MAKE)*[SPACE]*INSTALL_ROOT="$(CURDIR)"/debian/<application_name> install

to

[TAB]$(MAKE)[SPACE][SPACE]INSTALL_ROOT="$(CURDIR)"/debian/<application_name> install

as is add a second SPACE character after $(MAKE) leaving the initial TAB character This solve the problem of the multi-instance but at this point the.desktop_ file don'work correctly

Please note: Do not open the rules file with Qt Creator but with emacs/vim/your editor. Qt Creator will substitute spaces for the tab and then your app will not install.

Modify the .desktop file

Edit in Qt-Creator the .desktop file setting the correct Icon pointer that should be

Icon=/usr/share/icons/hicolor/64x64/apps/<application_name>.png

At this point it is probable that the icon is now shown in the program. As a matter of fact the application icon (those shown on the device main page) depends from the encoded icon in the control file. To avoid this problem it is necessary to open the project section in Qt-Creator, open the run tab in the Harmattan target expanding the Create Package group. Select the icon again and confirm.

The .desktop file at this point works correctly trying to launch the application using the invoker command in a line like the following:

Exec=invoker —single-instance —type=d /opt/<application_name>/bin/<application_name>

Tapping on the application icon the program don't start. Launching the invoker with the same command line from the device terminal this is the received error:

invoker: Invoking execution: '/opt/<application_name>/bin/<application_name>'
Booster: Loading symbol 'main'
failed: '/opt/<application_name>/bin/<application_name>:
undefined symbol: main'

Modify the main.cpp source

The QtDeclarative main() is not exported by default so - as explained by matrixx - it is necessary to change the main() function declaration in the main.cpp source as follows:

Q_DECL_EXPORT int main(int argc, char *argv[])
{
…
}