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. At Version 7.0, for C++ development, the edit/compile/build cycle can be based either on Metrowerks CodeWarrior for Symbian Professional, or 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 OS headers and libraries. The resulting binary is then run on the emulator. Builds can be debug or release: 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 toolchain-specific project files for CodeWarrior, Microsoft Visual C++, and the GCC toolchain that is used to compile for ARM-targets. 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, sound files, etc., are built into the appropriate 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. 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.

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

As the emulator-based process accurately mimics a real phone, the major 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.

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.

For Symbian OS v7.0, two hardware reference boards are supported: these are Intel's Assabet board, and the ARM Integrator.

Building a simple Hello World application shows just how easy basic development is.

HelloWorld 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. The example project can be found in the Developer Library examples at doc\examples\HelloWorld.

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 OS .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
TARGETPATH \system\apps\HelloWorld
TARGETTYPE app
UID 0x100039CE 0x10004299
SOURCEPATH .
SOURCE HelloWorld_Main.cpp
SOURCE HelloWorld_Application.cpp
SOURCE HelloWorld_Document.cpp
SOURCE HelloWorld_AppUi.cpp
SOURCE HelloWorld_AppView.cpp
RESOURCE HelloWorld.rss
USERINCLUDE .
SYSTEMINCLUDE \epoc32\include
LIBRARY euser.lib apparc.lib cone.lib eikcore.lib

Note that:

• the TARGET and TARGETPATH specify the name and path respectively of the application

• the TARGETTYPE is specified as app, meaning the program is a GUI application

• the UID line specifies the unique system identifier for a GUI application (0x100039CE) and the unique identifier for this application (in this case 0x10004299).

• 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 . (i.e. the current directory).

• sources for application resources, which define all text shown by applications, as well as all menus, dialogs, and other customisable screen furniture, are specified by RESOURCE statements. Resources are compiled by a resource compiler, which is called as part of the build process.

• the locations of project-specific and system headers files are specified by the USERINCLUDE and SYSTEMINCLUDE statements respectively

• the LIBRARY statement lists the application framework and graphics libraries required for a GUI application

Applications can be built from the Metrowerks CodeWarrior for Symbian Professional IDE, the Microsoft's Visual C++ 6.0 IDE, or from the command-line. The following sections explain each of these processes.

Important!

If you have not yet set a default development device, do so now, as detailed in the Essential setup section of Quick start.

Building with Metrowerks CodeWarrior for Symbian

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 HelloWorld.mmp file, and name the generated project HelloWorld.mcp.

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

You can then use the normal CodeWarrior commands to run, build, and debug the project. For example, build the project with the Project | Make command, and then run it with Project | Run. Symbian OS applications are a type of dynamic link library, rather than a stand-alone executable, so the program that is run is the emulator.

After the emulator has started, the Hello World application is available on the Extras bar. Launch the application by tapping on its icon.

Building with Microsoft Visual C++

If you're using MSVC++, type abld makefile vc6.

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

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.

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 the emulator has started, the Hello World application is available on the Extras bar. Launch the application by tapping on its icon.

Building from the command line

From a command prompt, do the following:

• Change to the example's directory, <path>doc\examples\HelloWorld

• Type bldmake bldfiles.

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

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

• For a command line release build to a real phone, enter the command abld build armi urel.

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

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 ARMI, using abld build armi urel on the command line.

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.

The typical means of distributing add-on programs commerically is to make the packaged 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 (e.g. through a web browser).

See also

Application installation guide