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.

8 comments:

  1. You can do first package with pips_nokia_1_3_SS.sis and qt_libs_armv5_udeb.sisx callaed libs.sisx
    Follow you do second package with libs.sisx and hello_world_armv5_udeb.SIS together.

    I don't understand between compilation from armv5 and gcce. Does Qt for S60 has important which commpiler I choose?

    ReplyDelete
  2. Thanks for the suggestion :)

    In terms of compilers - both of them generate code for ARM processors, but here are the main differences:

    ARMV5 target - RVCT compiler
    * it is not free
    * optimised and used for OS builds internally in Symbian and Nokia, in particular does the linking of C++ components very well
    * more information: http://www.arm.com/products/DevTools/RVCT.html

    GCCE compiler
    * is free
    * thus it is more appealing for 3rd party app development
    * but generates less optimized code (size&performance) and the toolchain is less stable

    Qt should work with both compilers. In order to compile under gcce just use the following command line when building for hardware:
    abld build gcce

    ReplyDelete
  3. Hi!
    Is it necessary to package the whole qt library with the
    application?
    It would be a very large package, even if the app
    is very simple, using only a few parts of the qt
    elements.

    ReplyDelete
  4. Isn't it possible to compile qt for s60 static?
    I used the -static option with configure, but it makes
    no difference. I have build it on linux with this howto:
    http://lizardo.wordpress.com/2009/07/29/running-qt-for-s60-sdk-on-linux

    Then I tried to copy QtCore.dll and QtGui.dll into the
    same Folder than the Executable. But the app does
    not run on the phone without the installed QT.
    Shipping these 2 dlls with the application would be
    acceptable for me. It would take about 3MB. But how
    to link against it?

    ReplyDelete
  5. I tried to use qmake. My prompt said: "qmake is not recognized internal or external command,operable program or batch file."

    I was in Helloworld dictionary where I tried to qmake.

    ReplyDelete
  6. Is it possible create all in carbide v2.0 what need in sis file. I mean that build all configurations in carbide and then sign a application ?

    Have to add .dll to .pkg file by .pro file if you have Qt application and s60 application the same file system. I mean that use s60 properties in Qt by wrapper class. how I create package file?

    ReplyDelete