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.