This online tutorial gives a short overview about the development of Symbian applications in C++. This tutorial uses the Symbian development environment that is shipped by most of the mobile phone vendors like Nokia or Sony Ericsson. Mobile phone vendors offer specific configurations of this basic Symbian development environment for their own products. Nokia offers a specific configuration for Nokia phones and Sony Ericsson also offers a Sony Ericsson version of the Symbian development environment. Often the vendors apply themes for the Symbian emulator epoc32 to display their phones instead of the standard epoc theme. The basic functionality of this different development environment configurations remains the same.
Additionally, there mostly exist three different versions of the environment for integrating Symbian development functionality into Metroworks Codewarrior,  Borland's C++ BuilderX Mobile Edition or Microsoft Visual Studio.
This tutorial covers only the basic functionality, which is provided originally by Symbian, and does not use a costly visual development environment.

The build process (on the command line)

This tutorial assumes that any Symbian SDK (and Perl) is installed on the machine. The tutorial refers to the install path through the variable '?ipath?'. So if you installed the Sony Ericsson Symbian SDK on your harddisk under 'c:\Symbian', replace the variable '?ipath?' with your install path. 

1. set a default device

   The first step, before you can start to develop with the Symbian kit, is to specify a default device for which the build tools should generate build scripts.
   Open a windows command prompt and type devices to see a list of possible target devices. On the console following example output appears:

   UIQ_70:com.symbian.UIQ
   UIQ_70:com.symbian.UIQ-runtime

   Now type devices -setdefault @UIQ_70:com.symbian.UIQ to set the default to our UIQ device. If you type devices again, now following output should appear:

   UIQ_70:com.symbian.UIQ - default
   UIQ_70:com.symbian.UIQ-runtime

2. create build scripts (bldmake) 

   A generic project specification file (.mmp = makmake project) is used to, automatically, generate specific build files for the specific build environments. This generic project specification file contains information that are necessary to build the project for different platforms and environments.

   An example for such a generic project specification file is shown here. The HelloWorld.mmp specification file is taken from the HelloWorld UIQ example application, which comes with the Symbian SDK (you can find it in '?ipath?\Symbian\UIQ_70\examples\HelloWorld\' ):

   // HelloWorld.mmp
   // using relative paths for sourcepath and user includes
   // second UID for testing purposes between 0x01000000 and 0x0ffffff TARGET        HelloWorld.app
   TARGETTYPE    app
   UID           0x100039CE 0X01000001
   TARGETPATH    \system\apps\HelloWorld
   SOURCEPATH    .
   SOURCE        HelloWorld_Main.cpp
   SOURCE        HelloWorld_Application.cpp
   SOURCE        HelloWorld_Document.cpp
   SOURCE        HelloWorld_AppUi.cpp
   SOURCE        HelloWorld_AppView.cpp
   USERINCLUDE   .
   SYSTEMINCLUDE \epoc32\include
   SYSTEMINCLUDE \epoc32\include\techview RESOURCE      HelloWorld.rss
   LIBRARY       euser.lib apparc.lib cone.lib eikcore.lib

   • The TARGET specifies the build result
   • The TARGETTYPE defines of which kind the build result is (exe for executables or app for UIQ applications) 
   • The UID is important to UIQ GUI applications, where every application has to provide a unique id. For exe targets this information is not relevant
   • The TARGETPATH specifies the path on the target system, where the result should be stored (i think so, but i am not shure if this information is used and where...)
   • SOURCEPATH specifies the path where the source files of the project reside
   • SOURCE specifies one or more single sourcefiles
   • USERINCLUDE and SYSTEMINCLUDE specify folders in which it is searched for include files. Symbian projects specify the \epoc32\include as a default system include path
   • RESOURCE specifies the resource file of the project
   • LIBRARY specifies one or more libraries (.lib files) to which the project has to link to

   To generate the build scripts it is necessary to create another information file: the  bldmake component description file. The projects component description file (bld.inf) contains a reference to the project specification file: 

   PRJ_MMPFILES
   HelloWorld.mmp

   Now type bldmake bldfiles and the bldmake tool automatically generates the build scipts for you. The default is to generate the build scripts for all platforms that are supported.

   After the bldmake tool returns (normally without any message response), the build scripts have been generated and are ready to use. The make (which abld.bat uses) files for the different platforms can be found in : '?ipath?\Symbian\UIQ_70\epoc32\BUILD\?ipath?\SYMBIAN\UIQ_70\EXAMPLES\HELLOWORLD\' 

3. Running the build script (abld.bat)

   After bldmake returns, a new script file appears in the project directory: abld.bat. The abld.bat script calls a Perl script that runs the rest of the build process. The command 'abld.bat help commands' prints all available abld command options on the console:

   Commands (case-insensitive):
     BUILD        Combines commands EXPORT,MAKEFILE,LIBRARY,RESOURCE,TARGET,FINAL
     CLEAN        Removes everything built with ABLD TARGET
     CLEANEXPORT  Removes files created by ABLD EXPORT
     EXPORT       Copies the exported files to their destinations
     FINAL        Allows extension makefiles to execute final commands
     FREEZE       Freezes exported functions in a .DEF file
     HELP         Displays commands, options or help about a particular command
     LIBRARY      Creates import libraries from the frozen .DEF files
     LISTING      Creates assembler listing file for corresponding source file
     MAKEFILE     Creates makefiles or IDE workspaces
     REALLYCLEAN  As CLEAN, but also removes exported files and makefiles
     RESOURCE     Creates resource files, bitmaps and AIFs
     TARGET       Creates the main executable and also the resources
     TIDY         Removes executables which need not be released

   The syntax of the abld.bat script is: abld [test] command [options] [platform] [build] [program]

   To build the HelloWorld example for the epoc32 emulator platform type: 'abld build winscw udeb'
   In order to build it for a real armi device (e.g. for the Sony P800) type: 'abld build armi urel'
   

   The result of the build process can then be found in: '?ipath?\Symbian\UIQ_70\epoc32\release\'

4. Running the application

   After a successful build process the Symbian application can run on a target platform. On the one hand it is possible to test the application within the epoc emulator and on the other hand it is possible to run it on the target device. There are two possibilities to deploy a Symbian application on a device. The simple one is to copy the application file (HelloWorld.app) to the '\system\Programs\' folder on the Symbian target device. The second possibility is to create a Symbian application install package (called SIS file) which contains all the necessary resources and libraries. Most of the mobile phone vendors provide an application manager or application installer within their sync software suite, which is able to take a SIS file and to install it on the target device.

   Creating a SIS installation file

   To create a simple installation file (.SIS) it is necessary to provide a package file (.PKG) that contains information about the installation process. A simple PKG file contains a header (specifiing the appname, the UID, major, minor and build number) and the target and source paths. The Symbian documentation offers following minimal package file for the HelloWorld application:

    #{"Minimal application"},(0X01000001),1,0,0
; Only two files to install for the minimal application
"HelloWorld.app"-"!:\system\apps\HelloWorld\HelloWorld.app"
"HelloWorld.rsc"-"!:\system\apps\HelloWorld\HelloWorld.rsc"

   
   The makesis tool uses the package file and packs all the required resources together into a SIS installation file. The SIS file format was published by Symbian and the sourcecode of the makesis tool is also available on the Symbian tools page. Following image shows the makesis process.

   

   The syntax of the makesis command line tool is shown here:

   MakeSIS [-h] [-v] [-s] [-d directory] [-p password] pkgfile [sisfile]

   Obtain an unique UID number from Symbian

   The UID numbers of your UIQ applications should be unique and are therefore registed at a global database at Symbian.com. For testing purposes it is not necessary to get a specific UID from Symbian, you have to manage your UIDs so that two applications do not use the same on one device. If you ship your product it is absolutely necessary to get a unique UID from Symbian. Just write an email with the subject 'UID Request' to: uid@symbiandevnet.com and specify your name or your products name, an email address and how many UIDs you need (up to 10 without reason, more than 10 you have to explain why you need so many...).

Symbian C++ project content and style

Exception handling

According to performance and memory issues the exception mechanism has been changed a little bit under the Symbian C++ dialect. The Symbian C++ dialect does not use a try-catch statement for exception handling, which is used e.g. in C++ and Java.

In Symbian the macros LEAVE and TRAP act like the well known throw and catch statements. A function call that could raise an exception can be put into a TRAP statement, in which the developer is able to catch the type of exception and to handle it.

TInt leaveValue;
TRAP(leaveValue, anyFunctionL());
if (leaveValue!=KErrNone)
{
// the developer is able to handle exceptions that accured within function "anyFunctionL()"
}

By convention, all functions that can leave — directly or indirectly — have an L appended onto their name (and can therefore be referred to as L functions). The function invoked by a trap harness will always be an L function.