Tuesday, 28 April 2009

Deploying S60 Qt application to single SIS file

Aim of today's experiment:
  • To create one S60 installation file (SIS file) containing an arbitrary Qt application and all binaries necessary to run it on the phone (Qt binaries among other things).

Benefits of doing so:
  • The user of Qt application doesn't have to download and install Qt libraries separately, before installing the application.
  • While uninstalling the application, Qt libraries will be uninstalled automatically - the user doesn't have to remember to uninstall them separately,
Preparing single SIS file with libraries embedded inside of it is not a difficult task, however I thought that many people, especially Qt developers with no prior Symbian experience, are not aware of such possibility.

In order to make things easier, I will go step by step through the whole process, from installing SDK to running Qt application on Nokia E71 phone. As always in mobile world, things are not as easy as writing several lines of code and pressing 'Run' button in the IDE, so some people may find this guide helpful. Of course, I'm not able to describe here all the trouble you may run into, however if you find a problem please email me, and if I know the answer I will add a note to this post.

First... some basic backgroud:
  • Qt is not pre-installed on any mobile phone because it is very fresh technology in hands of mobile phone vendors.
  • So you need to install Qt on the phone first before installing your Qt application.
  • The latest Qt for S60 release is called Garden. You can find more information and download it here.
  • While installing the Garden release, you will build it for your S60 emulator, as descibed on the web page mentioned in the previous point.
  • After building Qt libraries for emulator you can create your Qt application using Qt APIs and build and run it on the S60 emulator too.
  • In order to install your app or the real phone, you neeed to build it for hardware and create an installation package (SIS file).
I will go step by step through creating the application and building for hardware until I have single SIS package that can be installed on Nokia E71 phone. However first there is some...

Legal stuff worth considering before you proceed
Qt Garden release is distributed by Nokia under Technology Preview Licensee Agreement. This means that you can use it for evaluation, but you are not allowed to distribute it to other parties, so please be careful! Hopefully properly licensed Qt for S60 will be released soon.

Step 1 - Prepare the environment
You have to download and install:Step 2 - Create the application
For the purpose of this blog post I have used very simple Qt application. You can do the same by creating hello_world directory for the application and then put the following content into main.cpp inside this directory:
#include <qapplication>
#include <qpushbutton>

int main(int argc, char *argv[])
{
QApplication app(argc, argv);

QPushButton hello("Hello Anand!");
hello.resize(100, 30);

hello.show();
return app.exec();
}
[Anand is the guy who has lent me his Nokia E71 for a while so I could perform this experiment]

In addition to main.cpp I used simple Qt project file hello_world.pro:
TEMPLATE = app
TARGET =
DEPENDPATH += .
INCLUDEPATH += .
Input
SOURCES += main.cpp

Step 3 - Preparing build files
First we need to generate Symbian build and configuration files out of Qt .pro file. In order to do so:
  • Start command line and change directory to hello_world
  • Invoke the command:
    qmake
Lots of files will be generated by qmake, saving us a lot of trouble - normally Symbian developer would have to create these files manually, and their syntax is not too obvious. Among the files we have:
  • Symbian build files: bld.inf and .mmp file.
  • pkg files that will let us create SIS files for the hardware.
    • pkg file describes the contents of SIS file and acts as input for SIS-creation tools.
    • one of them will be hello_world_armv5_udeb.pkg which will describe package with debug version of hello_world targeted for the hardware. Please remember that as SIS files contain binaries, you need separate SIS file for each platform (ARM hardware or emulator).

Step 4 - Building for emulator
Now you can build the application for the emulator by invoking the following Symbian build commands from the command line:
bldmake bldfiles
abld build winscw udeb
As result the exe file with your application should be built in your SDK directory under epoc32\release\winscw\udeb. You can enter that directory and execute the exe to see how it works in the emulator.

Step 5 - Building for hardware
Invoke the following command from the command line (you don't need to invoke bldmake bldfiles now as this has already been done in Step 4):
abld build armv5
If everything goes right, executable files for the mobile phone should be created under epoc32\release\armv5.

Step 6 - ESSENTIAL IN THIS GUIDE - Modifying pkg file
Now we can think about creating the installation file (SIS file) for the Nokia E71 phone. We already have the specification of the SIS file hello_world_armv5_udeb.pkg generated by qmake. We could use it straight away, however first we would like to change the pkg file so that Qt binaries are be embedded into resulting SIS file together with our application.

Let's first copy the required binaries into our application's hello_world directory so that we can easily point to them from the pkg file:
  • Qt binaries
    • They are located in qts60binaries subdirectory of Qt installation directory.
    • There are two versions of binaries located in separate subdirectories: 3.x and 5.0. We will use the version from subdirectory 3.x as Nokia E71 works under 3rd edition of S60.
    • The file to copy is: qt_libs_armv5_udeb.sisx
  • PIPS binaries
    • This is Nokia Open C/C++ library. It is necessary to include this library for Nokia E71 as Qt depends on it. Newer Nokia phones with latest versions of S60 will have this library pre-installed, so there will be no need to include it in the SIS file.
    • Please download the library here: http://www.forum.nokia.com/Resources_and_Information/Explore/Runtime_Platforms/Open_C_and_C++/
    • Name of the downloaded archive: Plugin_For_S60_3rd_Ed.zip
    • And this is the file we are interested in that should be decompressed from the archive to hello_world directory: pips_nokia_1_3_SS.sis .
Now as we have the libraries locally accessible, we can modify the pkg file in order to include them. The following lines need to be inserted in hello_world_armv5_udeb.pkg, just after 'Unique Vendor name' section:
IF NOT package(0x20009a80)
@"pips_nokia_1_3_SS.sis", (0x20013851)
endif

IF NOT package(0x2001e61c)
@"qt_libs_armv5_udeb.sisx", (0x2001e61c)
endif
Of course, if your phone already has PIPS built in, you should skip the first IF statement.

Now the pkg file is ready to use.

Step 7 - Create the SIS file
After pkg file is updated, we can run the command that will create unsigned sis file:
makesis hello_world_armv5_udeb.pkg
The resulting file should be hello_world_armv5_udeb.SIS.

Step 8 - Sign the SIS file
You will probably not be able to install unsigned sis file on your Nokia phone. I will not describe here the various signing methods, however I will help you to run the application on your phone. In order to do so, you can use Symbian Open Signed Online service. It will sign the sis file for development purposes and to be used only on your phone. Application signed in this way will display ''Application is for development use only. Continuing installation may cause serious problems to your device. Continue?'' during the installation.
After submitting the form you should confirm your email by following a link in email message you receive after a while. Then another email will be sent to you with a link to the signed application.

Download the signed application - hello_world_armv5_udeb.SIS.

The Result.
Now you can upload the application to the phone. It should install and work on your phone properly. There will be many annoying messages displayed during the installation, you should accept everything and continue installation regardless of the warnings. One example of such message: 'Component 'Symbian OS PIPS' missing. Continue anyway?' - this may be displayed even several times. Unfortunately I don't know how to get rid of them - any ideas?

And this is all. I hope this guide was helpful. Please let me know if you had any problems not mentioned here. I would be very happy being able to help and fill the gaps in the guide.

Sunday, 5 April 2009

Introduction

I'm a software engineer with 10 years of commercial experience in various industries: internet marketing (Adv.pl), digital tv (Osmosys), mobile applications (Midlet.pl), mobile phone development (Symbian and Nokia). For years I've been a happy employee of corporations - I've been often given exciting tasks such as creating new UI framework that happened to change industry's expectations for good UI (see Osmosys EGG) or optimising graphics performance of newest Nokia platforms. However it was always my dream to become independent technology expert, and as I have been given a chance with Nokia VRP, I'm planning to pursue this dream now.

This blog will be part of the dream. For the beginning, while I'm still on the notice period, I'm planning to publish here some results of my weekend bedroom development experiments. The blog should get up to speed in about three month's time.

I can't forecast what ideas the future will bring to me, however I'd like to focus especially on technologies which I'm using in Nokia now - Symbian S60 platform and Qt framework. As you may already know, Qt is a new asset in Nokia's hands. Given that Nokia is the leading phone manufacturer in the world and Symbian Foundation is going to publish Symbian S60 open source code pretty soon, I believe that very interesting times are coming.