C++ development processes

Development for a Symbian OS phone is PC-hosted, based on an emulator which provides a Microsoft Windows-based implementation of Symbian OS. For C++ development, the edit/compile/build cycle can be based on an IDE, for instance Metrowerks CodeWarrior Development Studio for Symbian OS, or Borland C++BuilderX Mobile Edition. However, instead of linking and building against Windows libraries, developers link and build against the Symbian OS headers and libraries. The resulting binary is then run on the emulator.

You can create debug or release builds: your IDE's usual debug facilities can be used on debug builds. The tools supplied with the Development Kit make this a simple process. Symbian OS's environment-neutral mmp project file can be used to generate projects for specific IDEs and compilers. During development, the 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 and sound files are built into the correct location for debugging on the emulator.

Running an application is then simply a matter of starting the emulator, and selecting the application from the emulator's shell program.

There is little difference for developers who prefer the command line. The Symbian OS build tools bldmake and abld convert the mmp file into an appropriate makefile, which in turn manages the compile and linking steps.

Once an application has been developed on the emulator, it is rebuilt for the relevant phone hardware, and installed and tested on the hardware.

This page provides a summary of these steps, and provides pointers to where further information is available. A HelloWorld example is used to illustrate these steps. This is a very simple UI application. It displays a simple message in the centre of the screen, Hello World, drawn using the default title font supplied by the UI, and carries a menu bar.

Note that the example application referred to in this section uses the TechView test UI and is supplied by Symbian on Development Kits for Symbian licensees and their development partners. It is not present on application SDKs, although a modified version may be supplied. However, the information in this section should still be useful and relevant to developers targetting any UI.

A full description of the build tools is available from Build tools guide and Build tools reference.

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

A bld.inf file's main role is to specify the projects to be built. In this case, there is just one project, as shown below:

PRJ_MMPFILES
HelloWorld.mmp

The HelloWorld.mmp file is as follows:

TARGET        HelloWorld.exe
TARGETTYPE    exe
UID           0x100039CE 0x10004299
VENDORID      0x70000001
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

START RESOURCE HelloWorld.rss
HEADER
TARGETPATH      \resource\apps
end

START RESOURCE HelloWorld_reg.rss
TARGETPATH      \private\10003a3f\apps
END

LIBRARY       euser.lib apparc.lib cone.lib eikcore.lib

Note that:

• TARGET specifies the file name of the built program.

  You don't need to specify a directory: the build tools will work out the correct directory.

• TARGETTYPE is specified as exe, meaning that Symbian OS will be able to load and run the program in its own process. The other common target type is DLL, which means that the program provides shared functionality to be loaded and used by other programs.

• The UID line specifies identifier numbers, which allow the OS to identify the type of the program, and to distinguish it from other programs.

  In this case, the first UID number identifies that the program is a GUI application (0x100039CE), while the second number is the unique identifier for this application (0x10004299).

  For more information, see UIDs.

• The SOURCE statements list the project's five .cpp source files.

  In this case, we've chosen to put a single class in each .cpp file. The source files are in the same directory as the project file, so we can specify the SOURCEPATH as . (in other words, the current directory).

• The build tools need to know in which directories are any header files referenced by the source code.

  The USERINCLUDE statement specifies the directory of the project's own header files, while SYSTEMINCLUDE does the same for the OS headers files.

  All projects will use headers from the main OS headers' directory, \epoc32\include. Some headers are also in sub-directories of this directory.

  The API reference page for an item shows what header file an API item is declared in.

• Application resources, which define the text used in applications, as well as the menus, dialogs, and other customisable screen furniture, are defined in resource source files (.rss files). They are compiled by a Symbian OS resource compiler, which is called as part of the build process.

  The START RESOURCE...END blocks specify the resource source file (e.g. HelloWorld.rss), and options for building it, such as the output directory (TARGETPATH).

  A GUI application minimally requires a couple of built resource files. One, which must be built to the \resource\apps directory, defines the application's screen furntiture. The other, which must be built to \private\10003a3f\apps, gives application registration information. This defines properties of the application, such as its icon, which allow the phone's shell application (or equivalent) to correctly show and handle the application.

  For details of resource files, see Application resource tools reference.

  For details of registration files, see Application registration information.

• The LIBRARY statement lists the libraries which the project uses. The build tools link the project's own code against these libraries to produce the final executable.

  All projects link against the kernel user library (euser.lib), which contains the OS's fundamental classes and types. The other libraries in this example, apparc.lib, cone.lib, and eikcore.lib, provide support for GUI applications.

  The API reference page for an item shows what library needs to be linked against to use that item.

For more information on the project file formats, see bld.inf file syntax and mmp file syntax.

This section summarises the main tools used in working with a project on the emulator.

For details of emulator usage and configuration, see Emulator.

For more details of build issues, see The emulator build targets.

CodeWarrior can import an .mmp file and create from it a CodeWarrior project. To do this, start CodeWarrior and choose the File | Import project from .mmp file command. Select the Symbian OS kit that you want to use, and then the project file, HelloWorld.mmp file.

CodeWarrior then reads the .mmp file, and generates and opens a CodeWarrior project.

You can then use the normal CodeWarrior commands to build, debug and run the project. For example, build the project with the Project | Make command, and then run it with Project | Run. This will start the emulator and the application.

Note that any resource files listed in the .mmp file are automatically compiled by CodeWarrior as part of the build process.

The main help for using CodeWarrior is available from the IDE's Help menu.

Important!: if you have not yet set a default development kit, do so now. You can do this using the devices command from the command line.

From a command prompt, do the following:

• Change to the location of the application's bld.inf file, <path>\examples\HelloWorld

• Type bldmake bldfiles

• For a command line debug emulator build, enter the command abld build winscw udeb (if you're using CodeWarrior).

  The application's executable is built into the kit directory epoc32\RELEASE\WINSCW\UDEB\. This is the emulator's mapping of the directory z:\sys\bin\, which on a real phone contains all ROM-based executables.

  The resource files are built to the target directories specified in the project file, \resource\apps, and \private\10003a3f\apps\. These directories are located under the epoc32\RELEASE\WINSCW\UDEB\z\ directory, the emulator's mapping of the z: (ROM) drive on a real phone.

• The emulator can then be started with the command:

  > epoc

  and the application started from the emulator, using the shell application.

The primary method of debugging on the emulator is through an IDE. For details for CodeWarrior, see "Emulation Debugging" in the CodeWarrior Help.

Also useful is the trace log, EPOCWIND.OUT in the Windows temp directory, which is produced when the emulator is run. This logs thread start-up information, panics, and platform security warnings. For details, see Debug output (system message log) from the emulator.

Programs can write to this log using the RDebug::Printf API. Note on hardware, the trace log is sent to the serial port, from where it can be viewed using a terminal emulator on a connected PC.

In debug builds, the GUI provides special key combinations for resource checking, to trap memory leaks early in the development cycle, and for redraw testing, to check drawing code functions correctly. See Debug facilities for details.

Engine (non-GUI) code is usually tested through automated test programs.

Basic test code can execute in a command line type environment, using the RTest class.

For serious testing, automated, scriptable test code enables the definition of different test sets, from a quick system test to a full exhaustive system test that runs automatically over night. Symbian uses a framework called Test Driver, available on DevKits, to do this. This framework can also be used for automated testing on devices.

The emulator and reference Symbian OS builds include a text shell (eshell) application. This supports simple batch files, which can be useful for scripting test commands.

Localisation allows a program to be targetted at a specific language/culture.

Translation of the text displayed by an application should not require any changes to C++ code, as such text should be held in resource files. For more details, see How to localise resources.

A resource file may be created for each language supported, and each file included in the installation file. The actual resource used is determined by the end-user at installation time. See How to create an installation file for a multilingual application.

Conventions used for representing locale sensitive information, for example date and time formatting, the currency symbol and units of measurement are encapsulated by the TLocale class. For more information, see Locale Settings.

The build process automatically copies localisable project files, such as resources and bitmaps, to under the epoc32\localisation\ directory. For details, see Localisation support for Symbian OS.

The final stage in the development process is to upload the application to the target phone. The binary format of a phone is different from the emulator, so you will first have to recompile the application for the ARM processor used on phones.

The emulator provides a largely faithful emulation of Symbian OS running on a real phone (however, see Emulator/native platform differences for a list of the differences). This allows the major part of the development cycle to be 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.

When hardware is required, you can either use the actual target phone itself, if it is available, or, if you are developing before the target phone is available, you can use a hardware reference board, which chip manufacturers and designers produce to enable early development and prototyping.

The hardware reference boards supported depend on the Symbian OS version. At v9.1, supported boards include the Intel Lubbock DBPXA255 Development Platform, and Texas Instruments H2 Hardware Reference Platform. See the Board guides for more information.

Programs for native targets are built from the command line using bldmake and abld. They can also be built from the CodeWarrior IDE.

In either case, you need to select the right target to build to. This will depend on the phone that you wish to deploy to and the native compiler that is available. Possible targets include ARMV5 and ARMV6, which use the ARM RVCT compiler, and GCCE, which uses a version of the GNU GCC compiler. For example, the following builds for the ARMV5 target from the command line:

> bldmake bldfiles

> abld build armv5 urel

This builds the binary files into the epoc32\release\armv5\urel directory. Resource files are built under the epoc32\data\z\ directory.

For more information on building for hardware, see the The native build targets.

To be run or debug, the program must next be built into a test ROM, or packaged into a file that can be installed on a phone.

Where reference hardware is available, rather than production phones, ROMs can be rebuilt (from DevKits/CustKits) to contain the program.

For details, see Tools: ROM building and Reference: ROM building tools.

To install a program on a phone, it must be packaged into the Symbian OS installation (.sis) file format.

Developers write package control (.pkg) files that define the files to be put in the SIS installation file. Symbian OS tools, such as createsis, are used to insert the program files into a SIS installation file according to the instructions in the package file.

From v9.1, platform security requires that SIS files are authenticated when they are installed, so that malicious code cannot be installed to the phone. This means that the SIS file must be digitally signed.

SIS files for such programs can be signed by the developer themselves. These include programs that:

• do not use any APIs that are protected by capability checks, so do not need any platform security capabilities.

• only require platform security capabilities that belong to the group known as "user" or "basic" capabilities. If the software installer is asked to install a program with these capabilities, it can tell the user this, and query whether the installation should continue.

Some programs however require platform security capabilities that cannot be granted by the user. These programs must be tested externally, and signed with a certificate that the software installer recognises as coming from a trusted identity. This process is done through the Symbian Signed programme. Full details are at http://www.symbiansigned.com/; there is also a presentation on the Symbian developers’ web site: http://www.symbian.com/symbiansigned/. More detailed discussion of when you may or may not require a program to be Symbian Signed is available at the Implementing Platform Security for ISVs whitepaper on DevNet.

In order to test such applications on production phones, prior to the application being submitted to Symbian Signed, the SIS file must be signed with a special “development” certificate, which allows the application to be installed without having been through the external testing and signing process. These certificates are locked to the specific individual phones on which testing will take place (through the IMEI/ESN number). Development certificates are obtained through http://www.symbiansigned.com/.

The diagram below shows the key files and tools used in the process of creating a SIS file. The makesis tool uses the package file to create an unsigned SIS file. The signsis tool can then be used to sign the SIS file with a certificate to create a signed SIS file that can be installed.

The createsis tool is a wrapper around these two tools, which allows the whole process to be done in one step. If the program is being signed by the developer, rather than being signed through Symbian Signed, then createsis can also create the certificate to use.

For more details of these tools and the package file format, see Installation guide and Installation reference.

The typical means of distributing add-on programs commerically is to make the installation file available on disk or for download to a PC. From there, the user installs the installation file to the phone using PC connectivity software. Some phones may also allow direct download of installation files to the phone, for example through a web browser.

As with the emulator, the preferred way to debug programs built into ROM or installed on phones is through a debugger IDE connected to the phone. See the CodeWarrior product information for the versions of the OS and phones supported by versions of that IDE.

As noted previously, programs can also write debug log messages using the RDebug::Printf API. Messages are sent to the serial port, from where it can be viewed using a terminal emulator on a connected PC.

Reference ROMs also include the tool D_EXC, which traps panics and exceptions occurring in user-side programs, and logs the information for later analysis. This tool and others are discussed in more detail in the white paper "Hardware Debugging using Symbian OS" on the Symbian partner extranet.

For device driver and kernel-side developers, when a kernel crash, system process panic, or unhandled processor exception occurs, a debug monitor program is started. This allows a developer to get information about the state of the device, through a terminal emulator on a PC connected through a serial port. For more information, see Debugging information in the Device Driver Guide.

Unsatisfactory performance can be an issue encountered when testing programs on hardware. Profiling tools provide a means to discover where the program is spending most time, so that these areas can be targetted for optimisation.

For reference hardware, a profiling tool is available that writes profilling data to file, which can then be analysed on a PC. For details, see cedar\generic\base\e32utils\analyse\profiler.rtf in DevKit source code.

Third party tools may also be available for profiling.

RThread::GetCpuTime() gets the CPU usage for a thread. Its functionality is optional, and may not be available on production phones.

Note that the RDebug profiling APIs available on the previous kernel (EKA1) are not available on the current kernel (EKA2).

Some suggestions for techniques for optimisation are provided in How to optimise application start-up time.