Fundamentals of Symbian C++/Tool Chain

Comments

(no comments yet)

Log in or Join to leave comments.

Article Metadata

---

Article

Created: hamishwillee (10 Jan 2011)

Last edited: hamishwillee (23 Jul 2012)

This article needs to be updated: If you found this article useful, please fix the problems below then delete the {{ArticleNeedsUpdate}} template from the article to remove this warning.

Reasons: hamishwillee (24 Aug 2011)
The article is still useful and fairly up to date. However it has broken links to the toolchain "Raptor". This information needs to be expanded because abld is now deprecated.

The Symbian platform provides a Windows-based Emulator which enables the developer to develop and debug software components on a PC before, and alongside, testing and debugging on the phone hardware.

This means that Symbian components need to be compiled for two different instruction sets:

• binaries built for the emulator are x86-based and are compiled using the CodeWarrior compiler
• binaries built for the phone hardware use the ARM instruction set and are compiled using ARM's RVCT compiler or the GCCE compiler.

In practice, there are more targets than these, but CodeWarrior (also called WINSCW), RVCT (also called ARMv5) and GCCE are the main set.

This article provides an overview of:

• the system used to build Symbian components for the various targets
• how to run and configure the Emulator
• how to build and install software on the phone hardware

Building Symbian software

Overview

The Symbian build tools abstract the differences between the different build targets, allowing the developer to supply a single set of build files for both targets and providing a common interface for building the components.

The diagram below shows a highly simplified view of the main participants in the build system with which the developer interacts:

Build tool chain

Source files

Source files are created and maintained by the developer and are used as input to the build system. We have distinguished are three sorts of source files here:

• C++ files
• resource files, which are used to specify user interface elements and localizable UI text
• build files, which are used to tell the build tools what to build and where to find it. There are two levels of build file:
  • each MMP file describes how to build a single binary
  • a bld.inf file lists all the MMP files that constitute a single component. A component is a collection of executables which are developed and delivered together: in the example here the component is a server consisting of a client-side DLL and a server-side EXE.

Build tools

There are two independent build systems.

The old build system uses a tool called bldmake while the new system, also known as SBSv2 for "Symbian Build System v2" uses a tool called sbs. Both tools accept the same build file formats.

It should be obvious that most of the tools involved in building Symbian components are not shown here. In reality tools like bldmake and sbs are just the user interface to the build system. This diagram, and the article, cover only the tools which are used directly by developers.

Intermediate files

In the old build system bldmake produces an intermediate file called abld.bat which is then used to build the software. SBSv2 allows the developer to build components from a bld.inf file in a single step.

Compiled output

Both build systems produce compiled binaries for all the supported targets.

Build files

The two main types of build files are:

• the component description file, which is always called bld.inf
• the project definition file, which is a file of type MMP

Both these files are typically stored in a /group directory under the component’s top-level directory.

bld.inf

The bld.inf defines the content of a component: , . For example, the main EXE for a server together with the client-side DLL, plus any test code, would probably be considered to be a single component. It consists of seven sections:

PRJ_MMPFILES	Lists the MMP files that comprise the component
PRJ_EXPORTS	Lists the files to be exported from the component directory into another directory, typically somewhere under /epoc32: for example, published header files and any initialization files.
PRJ_TESTMMPFILES	Lists the MMP files that comprise the component test suite
PRJ_TESTEXPORTS	Lists the test files to be exported from the component directory into another directory, typically somewhere under /epoc32: for example, test data or test scripts.
PRJ_PLATFORMS	List the build targets supported by the component: if this is not specified a default set it used. For example, a component could might specify the WINSCW compiler and the GCCE compiler as supported platforms.
PRJ_EXTENSIONS	Lists template extension makefiles.
PRJ_TESTEXTENSIONS	Lists template extension makefiles for test code.

Most component bld.inf files only contain the first four sections. The syntax is covered in detail in the Symbian Developer Library.

MMP files

An MMP file is a text file which describes how to build a single executable. A sample MMP file is shown below:

TARGET Example.exe
TARGETTYPE exe
UID 0 0xF1101100
CAPABILITY ReadUserData NetworkServices
SOURCEPATH          ..\src
SOURCE ExampleMain.cpp ExampleImp.cpp
SOURCE ExampleUtility.cpp
SYSTEMINCLUDE       \epoc32\include
USERINCLUDE         ..\inc
START RESOURCE Example.rss
TARGETPATH          \resource\apps
HEADER
END
 
LIBRARY euser.lib efsrv.lib

Each statement in a project definition file starts with a keyword. The most common keywords are described below.

TARGET	Name of the executable file to build
TARGETTYPE	Type of executable, most commonly EXE or DLL
UID	UID 2 and UID 3 values. The UID3 must be unique and must be allocated from Symbian Signed for the executable to run on a production device.
CAPABILITY	The Platform Security capabilities the program needs. Defaults to NONE.
SOURCEPATH	The path for files listed in the SOURCE statements.
SOURCE	The source files to be built.
SYSTEMINCLUDE	The directory for system headers (included using #include<>).
USERINCLUDE	The directory for internal headers (included using #include).
START RESOURCE	The beginning of a block of information about a .rss resource file
TARGETPATH	The build location for a compiled resource file.
LIBRARY	The import libraries needed by the executable.

The MMP file syntax is covered in detail in the Symbian Developer Library.

Resource files

Resource files are documented in detail in the Symbian Developer Library.

They are used:

• to specify UI elements such as menu bars and dialogs
• to define application properties used by the application launcher,
• for any text that needs to be localized for different language variants.

Resource files support the localization of an application into many languages. The EXE only needs to be built once and many different language-specific resource files can be deployed with an application. The appropriate one is then selected at runtime based on the phone’s region settings.

Resource files are written as human-readable text files with a .rss extension. They use a Symbian-specific syntax and are compiled independently, using the resource compiler, into a separate binary. The resource compiler generates the binary resource file as a .rsc file.

If the program’s MMP file specifies the HEADER keyword in the START RESOURCE...END blocks associated with the resource file, the resource compiler also generates a .rsg file which contains #define statements for each resource defined in the .rss file. The header can be used by C++ application code to access elements in the resource binary, by including it using the #include pre-processor directive. Most commonly it will contain defines such as MY_APP_DIALOG_TEXT which can be used by the program at runtime to retrieve the localized string appropriate to the current device language.

RSS files contain some data, such as UI control structures, that is unlikely to vary according to language, and other data, such as the localizable strings themselves, which certainly will. So rather than have one RSS file per language a common approach is to have one common RLS file which includes a .loc file. The .loc file contains only strings which need translation and is therefore easier for translators to with with.

Other Symbian C++ header file types that can be used in a resource file include .hrh ( a header file that can be shared between C++ and resource files) and .rh (a header file used purely by a resource file).

Build tools

The old and new build systems both accept bld.inf files as input and produce identical binaries when given the same options.

The key characteristics of the new system are that it can run on Microsoft Windows or Linux, and that by using third party parallel make programs it can run on multiple nodes in a build farm.

From the user’s point of view another characteristic is that the old system is a two stage process in which bldmake converts a bld.inf file into produces a batch file called abld.bat, which is actually used to build the component.

In the new system the user can build directly from a bld.inf file using the sbs interface.

Equivalent commands: SBS vs Abld

abld	sbs
abld build	sbs
abld build armv5	sbs -c armv5
abld export	sbs EXPORT
abld test build winscw	sbs –c winscw.test

SBSv2

Detailed documentation for SBSv2 is provided here: Raptor Build System. The Raptor Quick Reference article just gives a brief overview of the syntax and how it compares with abld.

The sbs tool is the main command-line interface to SBSv2. The syntax of an sbs command is:

sbs [options] [variable=value] [target]

Options

Two of the most important options are:

-b or --bldinf: this takes as an argument the path and filename of a bld.inf file. If it is omitted, sbs looks for a bld.inf in the current directory.

-c or --config: this takes as an argument an identifier specifying the platform and/or debug/release variant. It is the equivalent of abld’s platform and build arguments. Multiple instances of this argument are allowed. If it is omitted the command is executed for all platforms and variants. Valid identifiers include:

• armv5
• armv5_urel
• armv5_udeb
• winscw
• winscw_urel
• winscw_udeb

To build test components append “.test” to the identifier.

Variables

This is a mechanism for setting environment variables to be picked up by the makefiles.

Target

This specifies what you want sbs to do. It includes all the abld commands listed above. If it is omitted, the default action is build.

SBSv1 (bldmake and abld)

Building with bldmake is a two-stage process. From a directory containing a bld.inf file, typing the command:

bldmake bldfiles

will generate a batch file, abld.bat. You then use the abld.bat file to build the component and do not need to call bldmake bldfiles again unless the bld.inf file is changed.

Most abld commands have a common syntax:

abld <command> [<platform>] [<build>] [<program>]

command: the most common commands are:

• export: copies the files listed in the PRJ_EXPORTS section
• makefile: creates makefiles for the programs
• build: combines several other commands to perform a complete build of the programs listed under PRJ_MMPFILES
• reallyclean: erases exported files, makefiles, and all files generated by the compiler
• freeze: appends new exports to frozen .def files

The commands can take options as additional parameters. Useful options include:

• -w or -what: does not execute the command, but lists the files the command will create or use. For example, abld export –what lists the files that would be exported, and abld build –what lists the files that would be built.
• -v or –verbose: verbose mode, displays calls to the underlying tools.

The three arguments following command are optional, and are used to restrict the operation of the command:

platform: the build platform (or target). The most common choices are:

• WINSCW, which creates x86-format binaries for running code on the Windows emulator
• GCCE, which uses GCCE to create binaries to run on phone hardware
• ARMV5, which uses ARM’s RVCT complier to create binaries to run on phone hardware

build: debug or release, specified as udeb or urel.

program: an individual program identified by its MMP filename, without the extension.

Calling abld build with no parameters will build:

• all executables (MMP files) listed in the bld.inf ...
• in debug and release builds ...
• for all platforms.

To build test components, the modifier test is specified before the command:

abld test <command> <platform>] [<build>] [<program>]

The full syntax for abld is documented on the Symbian Developer Library. To access the command-line help type:

abld help commands

The Symbian Emulator

The Symbian Emulator is a Windows application called EPOC.EXE, which simulates the target runtime environment. The Emulator enables software development on the Symbian platform to be substantially PC-based in its early stages, although the final development stages will require the use of phone hardware.

The Emulator saves time in the early stages of development, because he debug cycle is much faster without the need to install the software to the phone.

The emulator writes debug output to a temporary file named epocwind.out (%TEMP%\epocwind.out).

The emulator can be configured through an initialization file called epoc.ini, which is stored in \epoc32\data. Among a large number of configuration options, it is possible to configure disk read/write speed and available heap memory so as to match more closely the constraints of phone hardware.

Programs which do not need a GUI can run the emulator in console mode using the StartUpMode keyword in epoc.ini. This makes boot much faster.

Detailed documentation for the Emulator is available in the Developer Library.

Emulator file system

The file system of the phone is mapped to the PC as follows:

• the internal writable drive is usually mapped to \epoc32\winscw\c
• the ROM drive is mapped to \epoc32\release\winscw\udeb\z for the debug build, and \epoc32\release\winscw\urel\z for the release build.

The exception to this is the location of executables: on phone hardware they are stored in \sys\bin, but on the emulator they remain where they are built (e.g. \epoc32\release\wins\udeb).

All these paths are relative to %EPOCROOT%.

MMC emulation

It is possible to set up the emulator to behave as if a removable drive is present, and to simulate inserting or removing the card.

• pressing and holding F5 emulates opening the MMC door and removing an MMC.
• releasing F5 emulates closing the door, with the original card returned
• pressing F4 while F5 is held cycles between 2 different cards being present, and no card being present

By default the emulator maps the MMC drive to x:.

The emulated card is implemented as a file in Windows and does not involve access to any real MMC hardware.

Documentation on MMC emulation is available in the Developer Library.

Building for hardware

ARM compilers

EABI, GCCE, RVCT

The Embedded Application Binary Interface (EABI) is a standard defining the binary interface of code running in ARM environments, and enables interoperation between binaries produced by different conforming compilers.

In theory any EABI-compliant compiler can be used to build Symbian C++ binaries. There are currently two compliant compilers:

• GNU Compiler Collection for Embedded (GCCE), identified by the build tools as the GCCE target
• ARM’s RealView Compiler Tools (RVCT) compiler, identified by the build tools as the ARMV5 target

Unlike RVCT, GCCE is freely available, but cannot at present be used to compile the whole OS – it is intended only for application development.

In practice, GCCE-produced binaries can link with RVCT-produced ones, but the reverse has not been fully tested.

Additionally, there are two versions of the EABI: while RVCT can produce ABI_V2 binaries or ABI_V1 binaries, GCCE only produces ABI_V2 binaries, and cannot link to ABI_V1 binaries produced by RVCT.

ARM and THUMB builds

The ARM processor has two instruction sets: a 32-bit set (ARM) and a 16-bit set (THUMB). The ARM instruction set is usually faster but less compact than the THUMB set.

By default, kernel-side code is built for ARM and most other code is built for THUMB. The syntax of bld.inf and MMP files includes directives to override this policy.

Installing applications to phone hardware

The only way to deploy an application to a Symbian platform-based phone is to package it as an installation file, also known as a SIS file, and present that to the software installer either by copying it to the phone or by installing from a PC using the manufacturer’s connectivity software.

The tool for creating a SIS file is called MakeSIS. It takes as input:

• a text file called a package file (.pkg) to specify the files to include and metadata associated with the application.
• the EXEs and DLLs comprising the application itself
• the set of compiled resource files, one for each language supported

Most phones based on the Symbian platform require that a SIS file is signed in order to be installed. Signing by trusted certificates grants application access to protected APIs. For details of the signing requirements for accessing various APIs see www.symbiansigned.com.

To create a signed SIS file, the SIS is fed into another tool, called SignSIS.

Application installation toolchain

MakeSIS and SignSIS are wrapped by the CreateSIS tool. The Symbian Developer Library provides full documentation for the tools involved in creating SIS files.

Package file format

The most important package file metadata specifies:

• the list of language variants included with the application
• the name of the vendor, and name and version of the application
• the type of install package: whether the SIS file is a complete install package, an upgrade to a previously installed package
• an identifier specifying the target platform (e.g. S60, UIQ)

Package files can include options for what happens during installation: they can display a text file (such as a license file) or run another executable.

Package file syntax can contain conditional statements that test some aspect of the environment (for example, whether the device has a QWERTY keyboard) and control installation accordingly.

Differences between the emulator and phone hardware

Although it is easier to debug code on the Emulator than on phone hardware, not all problems show up on the Emulator. It helps to understand the differences between the Emulator and the phone hardware.

A detailed guide to the differences is in the Developer Library. This section lists some of the more commonly encountered problems.

• writable static data support in the emulator is limited: refer to this WSD and the Singleton Pattern for details.
• memory protection: on the emulator, code in one process can access the memory of code in another process, but on phone hardware this will generate a memory exception. This is a common issue for client-server code.
• stack size: on phone hardware the stack size is only 8KB by default. Although for GUI applications set this to be much larger, it is still much smaller than on the emulator.
• floating-point: the emulator is likely to have access to floating-point hardware, but Symbian platform-based phones often do not, which will make floating-point arithmetic much slower
• machine word alignment: the architecture used by phone hardware requires that 32-bit quantities are aligned to a 32-bit machine word boundary. The emulator does not.
• pixel sizes are slightly different on the emulator and on phone hardware
• the performance characteristics of the emulator and of the phone hardware are likely to be very different, especially disk read/write speed and the latency of TCP/IP connections