Hands On

Developing for any Symbian OS phone follows a standard pattern.

Development is PC hosted, based on an emulator which provides a Microsoft Windows-based implementation of the actual phone. At versions 6.0 and 6.1, for C++ development, the edit/compile/build cycle is based on Microsoft's Visual C++ 6.0 Windows development toolset. However, instead of linking and building against Win32 or MFC, developers link and build against the Symbian headers and libraries installed by the SDK. The resulting binary is then run against the emulator implementation of the appropriate version of the OS.

The tools supplied with the SDK make this a simple process. Symbian's environment neutral mmp project file can be used to generate toolchain specific project files for the VC++ IDE and the GCC toolchain. During development, the VC++ project file manages all linking and building details. It also ensures that all outputs from the build, and any required resources including application resource files, icons, bitmaps, sound files, etc., are built into the appropriate location for debugging on the emulator.

There is little difference for developers who prefer the command line. An essentially identical process is used to specify project information from which a makefile is created, which in turn manages the compile and linking steps.

For most developers the appropriate reference hardware will be a real phone from a Symbian licensee, bought over the counter. However, the substantial part of the development cycle is independent of real hardware being available. Real hardware is essentially a test and verification requirement, and at most levels of development, for most of the time, it is not a necessity.

Substantially, the emulator based process accurately mimics the operation of a final application on a real phone.

Builds can be specified to turn debugging information on or off. Specifying debug or non-debug builds is an option when the build toolchain is invoked.

If debugging is required, then for Versions 6.0 and 6.1 the MS VC++ IDE debugger is recommended. System level header files are supplied to make debugging and tracing easier, allowing the thread of execution to be followed down into system level.

Emulation necessarily differs in some respects from true phone targeted implementations. For example the Windows processes and threads model is not the same as the Symbian model. This shows up in differences between app and exe type projects targeting the emulator which don't arise on real hardware. Also, different underlying CPUs mean that there are potentially subtle differences between emulator and non-emulator targeted builds, for example, related to word size and endianess.

In most cases and for most developers, such differences remain largely invisible.

HelloWorld is a very simple UI application. It displays a simple message in the centre of the screen, and carries a menu bar. It consists of a single view which displays the "Hello World" text, drawn using the default title font supplied by the UI. The example project can be found in <path>\epoc32ex\HelloWorld, where <path> is the location in which the SDK was installed.

Key ideas this project shows off include:

• application resources, which define all text shown by applications, as well as all menus, dialogs, and other customisable "screen furniture", are managed outside the application source code in separate resource files which can be independently compiled, in this case in HelloWorld.rss

• commands to be interpreted by an application are likewise defined outside the main source but are #included into both it and its resource files

• applications can be divided naturally into engine, UI, and view components, which are dependent but logically separate from each other

• all applications have a three value UID which uniquely identifies it to the system

As importantly, the project demonstrates basic build requirements — what files the system needs to build an application successfully — and the basic build process — what commands are needed to invoke what tools, to perform what functions.

The Hello World project supplies both a Symbian .mmp project file and a bldmake component description file bld.inf.

The bld.inf file simply specifies the name of the .mmp project file to be built, as shown below:

PRJ_MMPFILES
HelloWorld.mmp

The HelloWorld.mmp file is as follows:

TARGET HelloWorld.app
TARGETTYPE app
UID 0x100039CE 0x10004299
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
RESOURCE HelloWorld.rss
LIBRARY euser.lib apparc.lib cone.lib eikcore.lib

Note that the target type is app, meaning a GUI application, and that the LIBRARY statement lists the application framework and graphics libraries required for a GUI application. The UID line specifies the unique system identifier for a GUI application (0x100039CE) and the unique identifier for this application (0x10004299).

All classes are defined in a single header file. Each class implementation is contained in its own .cpp file.

From a command prompt, do the following:

• Change to the SDK directory <path>\epoc32ex\HelloWorld.

• Type bldmake bldfiles.

• Type abld makefile vc6.

This creates the VC++ workspace HelloWorld.dsw in the directory: <path>\epoc32\build\<path>\epoc32ex\HelloWorld\HelloWorld\wins. This file can then be opened in VC++ and built by pressing F7, or by selecting the Build | Build HELLOWORLD.APP from the IDE menu.

For a command line debug emulator build, change the abld command to:

• Type abld build wins udeb

The application is now built into the emulator's z:\system\apps\HelloWorld directory, and can be run from the emulator's UI.

For a command line release build to a real phone, change the abld command to:

• Type abld build armi urel

The application's files are now built into the <path>\epoc32\release\armi\urel directory, and can be downloaded to a real phone.

To run the Hello World application from the IDE, first press Ctrl F5, or select the Build | Execute menu option. The first time you do this the IDE prompts for the location of the executable to be run (the emulator) — you'll need to supply the complete path for the debug emulator <path>\epoc32\release\wins\udeb\epoc.exe. Note that you only have to do this once — next time the emulator location will be saved in the workspace.

After loading the emulator, which may take some time, the Hello World application can be launched.

Debugging a Symbian application is the same as debugging a Windows application. First load the VC++ project file and then press the F7 key to build the application. Any build errors will appear in the "Build" tab. You can use the F4 key to scroll each error in the tab and display the location of the error in source code. You can also add breakpoints and step through code as normal.

Note that the Hello World application should build without errors, and hence will probably not require debugging.

The final stage in the development process is to upload the application to a real phone. The binary format of a real phone is different from the emulator so you will first have to recompile the application for ARMI, using abld build armi urel on the command line. You may then use Symbian Connect to copy the application and resource files from <path>\epoc32\release\armi\urel on the PC to the \System\Apps\HelloWorld folder on the real phone.

Symbian provides a tool for packaging applications for delivery to users — makesis. If you intend to do a lot of re-building and testing on a real phone it may be more practical to upload using this mechanism, rather than copying the files directly.

See also:

Application installation guide

Other topics in this guide describe the major subsystem building blocks which make up the OS, and the programming idioms which are specific to it and which are designed to ensure software robustness and reliability.

Other specialist topics and areas of special interest are covered in the techical papers available to registered developers at the DevNet site. In addition, a number of programming books are now available for Symbian OS aimed at both C++ and Java developers. For details visit Symbian DevNet.