Testing, debugging and deploying

From UIQ Books

Testing, Debugging and Deploying

This chapter covers testing and debugging of your UIQ 3 application and discusses its deployment to end users.

Many of the topics discussed are applicable to software testers, project managers or indeed anyone looking to improve procedures and quality within their software projects.

Testing and debugging should be a core part of your software development lifecycle from the point at which you start writing code through to your last maintenance release. These activities are typically most critical between a beta state of your software and final production-quality release.

Deployment is often seen as the small activity at the end of the project where you just get your application on to the user’s smartphone.

In this chapter we will summarize and introduce some of the more useful techniques, so that you have a good base to build upon.

Back to Basics

A good starting point is to take a step back and look at some general behavior characteristics to which all applications should aim to adhere. These have been generated from many lessons learned supporting software suppliers in the mobile handset industry. They should be considered as minimum requirements and you should assess your application against them at every stage of your software development process.

1 - Your application is a guest on the phone so it must be well behaved

UIQ mobile phones are based on an open operating system and are capable of supporting many third party applications. To understand the variety of applications available for the Symbian Operating System, in March 2007 there were well over 7000 third party Symbian applications available commercially. In the past there have been instances of third party applications that take over the mobile phone, suggesting that the developer considered the application to be the only one running. On many occasions we have seen that the designers, the developers and even the testers were concentrating so hard on getting their application ready to ship that they forgot to consider how their application inter-operated with the rest of the smartphone.

2 - Your application is not the only application on the phone

A UIQ mobile phone offers many functions beyond telephony; it’s a business tool, a music player, a camera, a diary, an address book, a games machine and ever more as technology develops. Users depend upon many of these functions and are very unhappy if they become unreliable. Your application is one part of this and must work in harmony with the mobile phone and its applications.

3 - Restarting your phone is not an option

Mobile phone users frequently leave the phone switched on for days, weeks and even months at a time. There can be no expectation of a daily re-start like there is for many desktop computers. Therefore, your application must not degrade itself, other applications or the operating environment over time. The need to frequently restart a mobile phone, for example, when a fatal error occurs is a common cause for users to reject and return a mobile phone to the supplier. This creates a bad impression and loss of money for mobile operators.

4 - A smartphone is a limited resource device

Despite the significant advances in hardware (memory, processor speed, battery capacity and so on), the mobile phone should still be considered as limited resource device when compared to a desktop computer or laptop. For example, allocating memory because you may need it and not freeing resources when you have finished is bad practice. Symbian provides good documentation including the C++ Coding Standards and also the Coding Idioms available from the Symbian Developer Network which should be followed as closely as possible.

5 - Events, Events, Events!

The mobile phone is an event-driven device. Here are just a few of the common events: low battery, new message, incoming call, beamed file, user input, flight mode, no signal, GPRS detach, remove memory stick, WiFi available, USB connected and key lock. Many of these will affect your application, for example it loses the foreground when a message notification is received. You need to ensure that not only do you code for them but you also test for them. Your application may perform well in isolation; however, what happens when you are using it and you receive an incoming call? Does it still function in flight mode? Testing and coding for events, particularly during integration and inter-operability testing is crucial to establishing a stable and reliable application.

An Example of Bad Behavior

Bad behavior does not have to be malicious or damaging; it is sometimes just a small oversight in application design. As an example, consider an application that automatically starts up and connects to GPRS in order to access a web service. It may run very well in the development office and test lab and pass all tests. In real life however, it must cope with areas of no service. A Connect dialog may seem ­­like a good idea to inform the user when the connection is initiated, however if that dialog is automatically displayed every time service is lost, it could become very intrusive. The user could be playing a game or reading offline Email while in the subway or in flight mode. At the very least, there should be an option to disable the dialog box or switch to manual connect.

Testing

The quality of your testing process is one factor that can reflect in the quality of the application that you are delivering. Delivering a low quality application will affect the image of the application or service that it provides. More significantly, this can affect your brand image as users always remember the bad things that you do and are happy to tell others about it, particularly if you make a poor first release.

There are so many different methods, types, styles and models of testing software that to cover them all would take too much time and space. We do not intend to cover all test techniques available, or indeed cover individual techniques in depth. Instead we will highlight some of the key test techniques for UIQ 3 application development.

It is not always a dedicated person or team who carries out testing. Developers will complete a certain level of testing during the development process. There will also be users within your organization who will be involved in, for example, sales and marketing and management. You may also have external users. The examples below do not refer to one particular group as it should be simple to understand who completes the particular type of testing.

Unit Testing

In theory, you should be testing every unit of your application, with a unit being the smallest part of your application. As we are discussing an object-orientated platform then this unit will be a class. If we take a simple C++ application on Windows, this is a relatively simple task to perform. You would most likely create a test harness or test suite and run the application through all the different permutations required to ensure quality and stability. With Symbian OS and UIQ this can be a little more difficult because:

• The UIQ emulator can’t accurately emulate performance. If performance is key to your application, then you should model your code performance on target hardware.
• If your class performs certain tasks that require; for example, data connectivity, then again you should run your application on target hardware to get a true feel for how your unit performs.

To do either of these, you should consider developing a test harness UI to allow you to test your different class structures on target hardware. This would bring extra benefits when it comes to regression testing, which we discuss later. If you change or add features to a core or high risk component, then you should ensure that you regression-test it to check that any change you have made does not introduce further errors, or even re-introduce a previously fixed problem.

If this is something that you decide to do, you could find that it may not be feasible to write a test harness UI that interrogates all base/super classes. It will be up to you to employ good design to test the key features of your engine. It is also important to avoid creating a complex UI that is difficult to navigate. It could be that the complex UI itself leads to mistakes in your testing.

Functional Testing

In short, this is where you test your application against specification and design. At this point you should be ensuring that the functions or use cases that you planned to implement have been implemented correctly and the application provides the behavior expected of it. It is also important as it confirms that all the components in your application are working together (as opposed to unit testing, which is only concerned with component level and may be satisfied using a test harness). Functional testing is particularly important with UIQ phones as this is where you are really testing the UI.

One example of functional testing is the Symbian Signed Test Criterion PKG-02:

Installation and Startup - The SIS file installs and operates in accordance with user manual and standard application use expectations. The application starts up in a reasonable time period (normally considered to be five seconds) or provides an appropriate indication of its launch progress.

Although this is not a detailed functional test, it does ensure that the application operates in accordance with the user manual and standard application use expectations. The expected result is that the SIS file installs and operates in accordance with the functional specification.

In this chapter we reference Symbian Signed Test Criteria v2.11.0, which are presented in detail in Section 14.8.2.

Inter-operability Testing

Inter-operability testing is concerned with ensuring that your application can communicate and exchange information as expected with applications that it interfaces with. For example:

• asking the web browser to load a specific URL
• ensuring the image file you create is the correct format and can be viewed in the picture gallery
• ensuring that the sound file you download does not get corrupted and can be played by the music player.

A smartphone is a rich device and you need to ensure that your application is tested against all the applications or services that it interfaces with. The Symbian Signed Test Criterion CON-01:

Task List – The application can be closed through the task list

This test ensures that your application behaves correctly when the task manager asks it to shut down. By behaving correctly it should at a minimum save any user data and actually respond to the shutdown event and close as expected.

Integration Testing

On one level you can consider the integration of the individual components in to your application and how you test this. This may not be necessary as your functional tests should highlight any issues here. What’s most important when developing for UIQ is the integration testing of how your application integrates in to the smartphone itself and the other applications’ services.

Symbian Signed Test Criterion CON-04:

Backup and Restore Compliance - The application should not interfere with a system ‘Backup’ and should function correctly after a ‘Restore’. In addition, on Symbian OS v9 the application should correctly register itself for backup with the system (the developer explicitly opts into this behavior)

To ensure that your application is backup and restore aware you must create a valid backup registration file that will be used by the backup and restore engine to manage your application and data for you. If this is incorrect then, quite simply, your application will fail on some level.

Regression Testing

The aim of this type of testing is to identify the situation where previously working features and functionality no longer work. This is particularly important when your application is close to a release date and you are making bug fixes. You need to have some way of ensuring that changes you make do not introduce other bugs or break any of the functions in your application. You also need to ensure that these changes have not re-introduced a previously fixed defect. This problem may not occur as a result of coding; it may be to do with a problem in the build process or configuration management process.

Stress Testing

Stress testing checks that your application can handle exceptional, illegal or erroneous actions such as entering incorrectly formatted data or removing the memory card unexpectedly. It is important to ensure that your application survives stress testing and does not cause any damage to the operation of other applications.

Symbian Signed Test Criterion GEN-02, Section 14.8.2.10, defines a specific stress test that your application must pass. We recommend that you define a more comprehensive stress test for your internal testing.

Acceptance Testing

Acceptance testing is typically run by the customer. Your immediate customer may not be the end user – you may be delivering to an operator, handset manufacturer, or intermediate customer (as a sub contractor). In this case you should aim to agree a level of acceptance testing that ensures what you deliver is correct. On many occasions this is not limited to the application and its functionality; it may also include release documentation, design documentation and user guides.

If you are delivering direct to the end user, then it is important to consider the expectations of your target users. Apart from their expected requirement that all functionality is in place, it is beneficial to consider user-centric requirements; for example, performance:

• Does the UI respond in an acceptable time?
• Does the UI conform to the UIQ Style Guide (where appropriate)?
• Are the buttons in the right place?

Phone-Specific Testing

Some features are specific to particular phones. If you make use of such features, then as well as testing on the target phone, you should test that your application works (or gives a suitable warning) when installed on a different phone that does not have the feature.

UIQ 3 supports a variety of form factors (pen based, softkey, portrait, landscape). Even though it takes care of re-arranging the layout, you should ensure that your application is tested for each of the form factors that it supports. We advise you to consider phone-specific keys in your testing. For example, what happens when your application is running and the user presses the Camera button?

Testing on the Emulator

The UIQ emulator is a key software tool for the developer. Like many of the topics already discussed, there is a lot of reference information and how to information already available. This section will highlight some of the lesser known functions on the emulator to ensure that you can make the most of the tool during testing. For detailed information on these functions you should refer to the UIQ SDK Documentation.

The following sections discuss some of the key aspects of the emulator and how to modify it for your particular needs.

File locations

The emulator provides a Symbian file system by mapping drives to your PC file system. In general the emulator is always configured with at least two drives, these are:

Z: = \epoc32\release\<emulator build>\<build>\z
C: = \epoc32\<emulator build>\c\

Where <emulator build> = WINSCW etc
Where <build> = UDEB or UREL

The Z drive represents the mobile phone’s ROM and should be treated as such. When you build your application it will be deployed to the Z drive and it will be treated as a ROM based application. The C drive represents the main smartphone writable file system. Any file your phone creates during runtime should only appear in the file system from the root of the C drive upwards.

The emulator can be configured to map to other virtual drives on your PC file system. For example, adding the following line in your \epoc32\data\epoc.ini file will map the T drive on the emulator to C:\Temp on your PC file system:

EPOC_DRIVE_T C:\Temp

If you look at the file system using the QFileMan on your emulator, along with the default Z and C drive plus any drives you have mapped you may also see a number of other drives.

Figure 1 QFileMan

These drives represent the default drive emulation setup on the emulator. In the case of the UIQ 3 SDK these represent the following:

• U: FAT over emulated NAND flash drive
• V: ROFS over emulated NAND flash drive
• W: LFFS over emulated NOR flash drive
• X: FAT over emulated MMC drive
• Y: FAT over emulated RAM drive.

Rather than mapping to a directory on your PC file system, these drives map to individual BIN files in the \epoc32\data\media directory and the configuration of these drives are set in epoc32\release\\\Z\SYS\DATA\estart.txt.

Debug Keys

One emulator feature that is not always used but is easily available is the debug key functionality. These are divided in to three sections which are briefly discussed below.

The resource allocation keys provide information on resources used by your application.

There is also the ability to use the heap failure tool which simulates resource allocation failures and can be used to ensure that your application is handling allocation errors correctly. The tool operates in a number of modes. These are:

• deterministic, which means you can specify the rate at which the failures occur
• random, which means that the failures occur, as expected, in a fandom manor.

The heap failure tool supports application, window server and file (file access) resource failures and these can be switched on independently or all at the same time.

The drawing keys allow you to simulate redraw or window server events.

Finally, there are some other debug keys that provide you with useful emulator functionality.

The debug keys can assist you in both development and testing. In particular, tools such as heap failure should be used throughout development to ensure that you have the correct error checking in place so that your application handles any resource problems gracefully. As we can see with the sample application Commands1, with heap failure set to Random and following a number of attempts to add new entries eventually we receive a Not enough memory dialog.

Figure 2 Not enough memory dialog

The application handles this and as expected (as we have random heap failure) continues to work after the dialog is dismissed.

Debug Output

The emulator outputs certain information to a log file. This log file is located by default in c:\documents and settings\\local settings\temp\epocwind.out. This file is re-created each time the emulator starts and all entries are logged relative to the emulator starting. The emulator lists configuration information and system messages in this log file, these system messages include:

• application panics
• thread information detailing when threads are created and destroyed
• Platform Security information.

With regards to Platform Security, the emulator logs the Platform Security settings at the time it starts up and also when any application attempts to use an API or perform a function, such as writing to a protected directory. For example, we modified LayoutManager1 so that it tried to create a file in another application’s private directory. LayoutManager1 could only do this if it had the required capability, however, in the case of this example we set the application to have no capabilities.

When this example is run, there are two results to consider. From a code point of view when we actually try to create the file the RFile.Create call returns KerrPermissionDenied (-46). If you then look in the epocwind.out file you will see the following:

81.335 *PlatSec* ERROR - Capability check failed - A Message (function number=0x0000001f)
from Thread LayoutManager1[edead004]0001::LayoutManager1, sent to Server !FileServer,
was checked by Thread EFile.exe[100039e3]0001::Main and was found to be missing the capabilities: AllFiles .
Additional diagnostic message: \Private\100051e6\NaughtyFile.txt Used to call: Create File

This error message is very detailed; it tells you which application has the error, what function it was trying to call and what capability it needs to complete this call. In this example it even specifies the file it was trying to create and where it was trying to create it. This sort of extra information is extremely useful as KerrPermissionDenied only indicates in the documentation that you the request failed “the permissions on the file do not allow the requested operation to be performed”. Naturally you would expect that there are file permission problems and would not automatically know that your error was caused because your application does not have the required capability.

Emulator Configuration – Epoc.ini

The default configuration for the emulator is \epoc32\data\epoc.ini and this can be used to modify a number of the basic emulator settings. These include screen size and key mappings. Unless you are implementing a bespoke application it is most likely that you will never need to alter these settings. For example, if you are writing a console application, such as a test harness, then by defining textshell in epoc.ini the emulator will load in textshell mode, if textshell is missing then the default emulator will load.

Not all possible value/parameter settings are in the emulator. If they are missing, then the emulator will pick default values. Some of the more useful options are listed below:

Epoc.ini also defines the Platform Security settings for the emulator’s runtime environment. This gives you the ability to turn on and off various Platform Security checks. These are:

PlatSecDisabledCaps WriteUserData+WriteDeviceData

We expect that you will use epoc.ini to define different emulator runtime settings at different stages of your software development. We recommend, however, that you put all checking on at some point to verify that your application is behaving as expected. This checking should match as closely as possible the phone or phones that your application is targeting.

Emulator Configuration – UIQEnv

UIQEnv is a tool used to define common configuration settings for the UIQ SDK and emulator. It is particularly powerful when it comes to configuring communications components. Rather than configuring the Symbian CommsDat XML database manually, UIQEnv can be used to set and modify configuration settings.

UIQEnv also provides a quick and easy way to change the screen orientation of the emulator to allow you to, for example, test the behavior in landscape mode. There are shortcuts to set the most common modes:

UiqEnv –ui softkey
UiqEnv –ui softkeytouch
UiqEnv –ui pen
UiqEnv –ui SoftKeySmall
Uiqenv –ui PenLandscape

As an example, Uiqenv –ui PenLandscape:

Figure 3 Pen Style Landscape UI configuration

In fact you can, by the use of a bit-wise OR create the correct configuration to allow the emulator to match the phone you are working on.

For example,

Uiqenv –ui 17025

configures Softkey Style Touch.

Emulator Configuration – SDK Configuration

When you install the UIQ SDK to your machine, the SDK configuration tool is installed by default. This tool allows you to manage a number of different UIQ SDKs through a GUI interface and it also allows you to set emulator styles and communication settings. This tool is essentially a GUI for UIQEnv.

Figure 4 SDK configurator tool

Figure 5 Emulator in Softkey Style Touch and Pen Style UI configurations

Testing a SIS File in the Emulator (Install)

The actual install and uninstall of your SIS file should always be verified to ensure that it enters and leaves the phone correctly. You can use the emulator to verify this and troubleshoot any issues. Using the LayoutManager1 example application, we will walk through the process from building the software to installing it (via SIS) on to the emulator.

The first step is to build debug emulator binaries and check that once the application is installed, that we can run it. It is important to ensure that the package file is setup correctly so that the correct files get deployed to the correct location on the file system. To build the LayoutManager1 application, the following commands should be run from the Layout Manager1 directory.

bldmake bldfiles
abld build winscw udeb

At this point the binaries, resource files, images and so on are deployed in their relevant places within the SDK file structure. When testing and troubleshooting SIS files it can be beneficial to write a small script (usually batch file, however this can be done in the language of your choice) to pull all the required files for the SIS in to one directory. The advantage of this is to ensure that you always pick up the same files and that you can examine (date and time stamps, sizes) and validate them (using the Symbian tool Petran) to check that the correct files are going in to your SIS.

The following copy commands work for LayoutManager1 and assume that you want to copy them to your current directory. These commands are only concerned with the WINSCW UDEB binaries.

copy \epoc32\release\winscw\udeb\Z\private\10003a3f\apps\LayoutManager1_reg.rsc .
copy \epoc32\release\winscw\udeb\z\Resource\Apps\LayoutManager1_loc.rsc .
copy \epoc32\release\winscw\udeb\z\Resource\Apps\LayoutManager1_icons.mbm .
copy \epoc32\release\winscw\udeb\z\Resource\Apps\LayoutManager1.mbm .
copy \epoc32\release\winscw\udeb\z\Resource\Apps\LayoutManager1.rsc .
copy \epoc32\release\winscw\udeb\Layoutmanager1.exe .

Note that now you have extracted the required files for the SIS, you will want to clean up your build. Otherwise, when you eventually try to install your SIS file, the software installer will correctly tell you that the software is already installed. As we are testing a straight install and not an upgrade to a ROM application, then you need ensure the output from the build is removed.

abld reallyclean

The next step is to construct the package file.

; Languages supported.
&EN

; Localised vendor name.
%{"Sony Ericsson Mobile Communications"}

; Global vendor name.
:"Sony Ericsson Mobile Communications"

; Standard PKG file header.
#{"LayoutManager1"}, (0xEDEAD004), 1, 0, 0, TYPE=SA

; Platform Dependency.
(0x101F6300), 3, 0, 0, {"UIQ30ProductID"}

; File to install.
"LayoutManager1_reg.rsc"-"c:\private\10003a3f\import\apps\LayoutManager1_reg.rsc"
"LayoutManager1_loc.rsc"-"c:\Resource\Apps\LayoutManager1_loc.rsc"
"LayoutManager1_icons.mbm"-"c:\Resource\Apps\LayoutManager1_icons.mbm"
"LayoutManager1.mbm"-"c:\Resource\Apps\LayoutManager1.mbm"
"LayoutManager1.rsc"-"c:\Resource\Apps\LayoutManager1.rsc"
"LayoutManager1.exe"-"c:\Sys\Bin\LayoutManager1.exe"

At this point the SIS file can be built:

makesis LayoutManager1.pkg LayoutManager1_unsigned.sis

Now we have a SIS file to install; however, we can take this one step further and sign the SIS file. The UIQ SDK provides three certificate/key pairs located in \epoc32\tools\cert. These are:

• NoCaps.key and NoCaps.cert
• AllUserCaps.key and AllUserCaps.cert
• AllCaps.key and AllCaps.cert.

The names of these certificate and key pairs are quite self- explanatory. NoCaps will sign your application however it will not allow it access to any capabilities. AllUserCaps will provide your application with user capabilities which consist of those in the basic set and extended set. Finally, AllCaps provides your application with access to all Platform Security capabilities. By signing with the appropriate certificate you can test that your final SIS file is accepted as expected by the software installer.

signsis LayoutManager1_unsigned.sis LayoutManager1_signed.sis \epoc32\tools\cert\AllCaps.cert \epoc32\tools\cert\AllCaps.key

Once signed, you are ready to test the full installation of your application on the emulator.

Figure 6 SIS install sequence in the emulator

Configuring the Software Installer

The software installer is the gatekeeper of the smartphone. It examines which capabilities an application has declared and then checks to see if the application signature satisfies the requirements.

Configuring the emulator can be done using

\epoc32\release\winscw\udeb\Z\system\data\swipolicy.ini as this sets the software installer policy. There are a number of settings that can be modified, however, the key line for your testing is:

AllowUnsigned = true

With this set to true unsigned SIS files can be installed. Setting this to false means that your SIS file will be checked by the software installer at install time. Examples below are given with AllowUnsigned set to false so that the installed checks for a signature.

Figure 7 Installation with SIS checking enabled

In this case, LayoutManager1 has been built with a capability, however, the SIS file has not been signed. As the software installer is checking the capabilities then it will refuse installation.

AllowGrantUserCapabilities = true

This variable defines if the user is allowed to grant capabilities. If this is set to true then the user has the ability to accept an application with capabilities defined with the variable UserCapabilities. In the case of the default SWIPolicy.ini file this is:

UserCapabilities = NetworkServices LocalServices ReadUserData WriteUserData Location UserEnvironment

This means that if an application requires one, some or all of these capabilities then the user can grant them during installation.

Figure 8 Dialog for users to grant User capabilities

Although you have the ability to modify the software installer policy in the emulator, you do not have this ability on mobile phones. The installation policy is set by the individual manufacturers and there is no guarantee that each manufacturer will set the same policy.

Testing Tools

LeaveScan

Symbian has developed a lightweight and simple exception handling mechanism that allows methods to leave. For example, a method that has code which may result in an exception can leave and is called a leaving method. As a result of this there is a convention within Symbian that states that the name any leaving method must end in L. For example:

CqikAppUI::HandleCommandL(CQikCommand &aCommand)

This application function takes command objects when a menu item is selected. Depending upon which menu item is selected, for example, Save, the appropriate function will be called. The point here is that, as a developer you can see that HandleCommandL is a function that may leave. If it does hit an exception, then the exception will propagate up to a point where it is caught by a trap harness.

If the naming convention of putting the L suffix at the end of the function is not followed, then any users of the function will not expect that it may leave. This means that the user of the function will program to handle, for example, a potential memory leak.

LeaveScan is a tool provided by Symbian to help you track down problem with your leaves and ensures that your code follows the convention. It checks that any function that Leaves, or calls a function that Leaves (other than in a TRAP harness), must have a name ending in L. LayoutManager1 was modified to include a new utility function which unfortunately did not follow the naming convention:

void CAppSpecificUi::BadLeave (CLeakClass* aLeakClass)
{
CLeakClass * leakExample1 = new(ELeave) CLeakClass;

// Some code here.
delete (leakExample1);
}

Everything will be alright as long as BadLeave can successfully create a new CLeakClass and returns it to the calling function. However, if the new CleakClass could not be created an unexpected leave would occur. Running LeaveScan over the CPP file that contains this code will highlight this problem:

V:\SampleApp2\LayoutManager1>leavescan LayoutManager1.cpp
LayoutManager1.cpp(262) : CAppSpecificUi::BadLeave Calls new(ELeave).

The tool simply tells you which line of code has the problem and what the problem is. It should be run over all code that you produce and any third party source that you use to ensure that you adhere to this coding standard.

Petran

Petran is a Symbian build tool and it is particularly useful as a debugging tool in that you can check your Symbian OS executable file (E32) to check various aspects of your build binaries. We built the example SignedAppPhase3 using GCCE for target. This resulted in SignedApp_0x20000462.exe being built. We then used Petran to confirm the header of this executable. Note that Petran outputs a large amount of information about the executable. Command line parameters can be used to reduce this:

petran -dump h SignedApp_0x20000462.exe

PETRAN - PE file preprocessor V02.01 (Build 549)
Copyright (c) 1996-2005 Symbian Software Ltd.

E32ImageFile 'SignedApp_0x20000462.exe'
V2.00(505)      Time Stamp: 00e1156f,669cc1c0
EPOC Exe for ARMV5 CPU
Priority Foreground
Secure ID:      20000462
Vendor ID:      00000000
Capabilities:   00000000 00000000
Uids:           1000007a 00000000 20000462 (ecfcaed6)
Header CRC:     6a28e743
File Size:      0000dea4
Code Size:      0000cd74
Data Size:      00000000
Compression:    101f7afc
Min Heap Size:  00001000
Max Heap Size:  00100000
Stack Size:     00005000

For the purpose of this example, we have removed some of the information, otherwise the output would span over many pages. We can see from the information above that we can obtain ID (Secure and Vendor), UID, capability declaration and heap size. In complex build environments it can be very useful to ensure that the binaries which you are distributing are as expected. Petran is not limited to returning just these values; it can also analyse the code and data section, provide export information and examine the import table.

Debugging

Panics

A panic within the Symbian OS indicates a programming error of some sort. At the point of a panic the thread in which the panic occurs is stopped so that the thread can no longer continue to run. A panic is critical to your application. However, depending on where it occurs and taking in to account that Symbian OS terminates the thread that causes the problems, this means that your application can not continue to run and cause further problems to the operating system and phone.

A panic will not always have the same result. If it is in the main thread of the application then the process in which that thread runs will close. If it is in a sub-thread (spawned from the main thread) then the main thread will survive and, depending on the application structure and design, the main thread may be able to recover. If however the panic occurs in a thread that is identified as a system thread (for example, essential for the operating system) then the panic may cause the phone to restart.

The following piece of code is a purposefully bad example. Firstly, it attempts to create a file in the private directory of another application. Secondly, the developer has been particularly lazy and has not performed complete error checking. It is not a particularly useful piece of code; it simply aims to demonstrate operating system panics.

_LIT(KFileName, "C:\\Private\\100051e6\\NaughtyFile.txt");

User::LeaveIfError(iFsSession.Connect());
iFile.Create(iFsSession,KFileName,EFileShareExclusive);
iFile.Size(fileSize);
iFsSession.Close();

As the application does not have the correct capability, AllFiles, to create the file, the iFile.Create call will fail. As there is no error checking on the Create call, the iFile.Size call will cause a panic. This is one of the most common panics reasons that you will see, KERN_EXEC, however this panic has over 50 different associated reason codes.

Figure 9 KERN_EXEC panic

On most occasions when a panic occurs, a dialog box is displayed with the title Program Closed. Three further pieces of information are displayed:

• the program name (process name)
• the reason code (panic category)
• the reason number.

The panic categories are well defined within the Symbian documentation and should be understood when debugging general application problems. There are too many reason codes (categories) to list here; refer to the SDK for full details. The explanation for the above example is as follows:

• Reason Code KERN-EXEC – These panics represent program errors which are detected by the Kernel Executive. Typically, they are caused by passing bad or contradictory parameters to functions. Threads which cause exceptions also raise a KERN-EXEC panic.
• Reason Number 0 – This panic is raised when the Kernel cannot find an object in the object index for the current process or current thread using the specified object index number (the raw handle number).

Although this does not state exactly where the error occurs, it does give you an indication of what to look for. The object it can’t find is the handle to the file object. Depending on the complexity of your application, it may not be that obvious from the panic as to where the problem lies. Further debugging techniques discussed later may help you track this down.

Assertions

Assertions are a standard C++ method to detect errors as soon as they occur. Those of you who are familiar to C++ but not Symbian OS C++ should still be familiar with using assertion macros. Within Symbian OS there are two key assertions defined in \epoc32\include\e32def.h.

# define __ASSERT_ALWAYS(c,p) (void)((c)||(p,0))

# if defined(_DEBUG)
# define __ASSERT_DEBUG(c,p) (void)((c)||(p,0))
# endif

As you can see from this, assertions can be used in both debug and non debug builds. From the macro statements you can also see that the OR means that if parameter c is false then p is called. You as a developer define what p is; the assert statements do not handle this for you. We recommend that you should always terminate the running code and flag up the failure, rather than return an error or leave.

Taking the example from the previous Panic section we can enhance the badly implemented example to help us to track down the root cause of our problem.

User::LeaveIfError(iFsSession.Connect());
TInt err = iFile.Create(iFsSession,KFileName,EFileShareExclusive);

_LIT(KMyFileSession, "FileCreation");
TInt myFileSessionError = 999;
__ASSERT_DEBUG((KErrNone === err), User::Panic(KMyFileSession, myFileSessionError));

iFile.Size(fileSize);
iFsSession.Close();

Now when the new code is implemented we receive a different error.

Figure 10 Panic error dialog with enhanced information

Of course you will say that this can be handled more efficiently using good error checking and you would be right in saying so. This code snippet is particularly extreme in order to show a specific example. You may not always be in the position where you can easily check all the code logic in, for example, a code review. The file creation process may be abstracted away from you and if so you would rightly assume that that part of the code responsible for creating the file is checking for errors correctly. In this case it would be right to see this as an exception for the file not to be available and check using an assertion macro.

Debug Macros

When developing for UIQ phones we keep reminding ourselves that we are developing for phones with limited resources, especially memory. To assist developers, Symbian OS provides a number of tools to help you check for, track down and test for memory management issues.

Heap checking

There are two types of heap checking macros, the first can stimulate out of memory scenarios and the second can check to ensure that your application is not leaking memory. These macros are only built in to your debug builds so, unlike assertion macros, they will not increase the size or affect the performance of your release code.

The following example creates an object of type CLeakClass on the heap.

CLeakClass : public Cbase {};

__UHEAP_MARK

CLeakClass * leakExample = new(ELeave) CLeakClass;

// Some more code here.

__UHEAP_MARK_END

As delete is not called then the heap check macro will result in the following panic.

Figure 11 Panic on calling heap check macro

The reason code is not that clear; ALLOC indicates that this panic has been caused because a memory leak has been detected. The value following ALLOC is a hexadecimal pointer to the first orphaned heap cell. You will notice that this is truncated, however, the debug output file for the emulator (c:\documents and settings\\local settings\temp\epocwind.out) logs the panic in full:

Thread LayoutManager1::LayoutManager1 Panic ALLOC: 73e4bb8

One method to track down the cause of your memory leak (assuming that you have multiple instances of heap checking) is to switch on just in time debugging in the emulator. In this case the following dialog is presented when the error occurs:

Figure 12 Application error dialog in the emulator

Choosing Yes will load the just in time debugger and the call stack can be used to track down the cause of your problem.

Figure 13 Just in time debugging in the emulator

This is again a simplified example and it may not always be this easy to track down the root cause. It may be necessary to put a watch on the memory address, run further tests or add extra logging to find the troublesome code.

In addition to checking for memory leaks, the macro __UHEAP_FAILNEXT can be used to force memory allocations to fail. It is called specifying a Tint parameter that indicates which particular allocation fails. The following code sets a heap allocation failure on the second allocation attempt:

__UHEAP_FAILNEXT(2);

CLeakClass * leakExample1 = new(ELeave) CLeakClass;
CLeakClass * leakExample2 = new(ELeave) CLeakClass;
CLeakClass * leakExample3 = new(ELeave) CLeakClass;

// Some more code here.

delete (leakExample1);
delete (leakExample2);
delete (leakExample3);

__UHEAP_RESET;

This results in a standard Not enough memory dialog when the second allocation is attempted.

Figure 14 Not enough memory dialog

We discussed earlier that the emulator supports a similar debug function in the form of the simulated heap failure tool. Unlike the emulator heap failure option, the heap failure macros can be set in specific parts of your code to ensure that specific allocation failures are handled correctly by your application. It is important to note that using __UHEAP_FAILNEXT at the same time as the emulator heap failure tool can cause confusing results, so ensure that you use the tools wisely.

Deploying

Testing is Still Required

Although you have tested your application in the emulator and fixed most of the software defects and usability issues, you still have further testing to do. At this stage your application should work as expected on the emulator. Despite this, you can not make the assumption that it will also do so on target hardware. The emulator will do as it says and emulate your target hardware, however, there will always be differences that can only be experienced by using real hardware.

For the purpose of the examples below we assume that we are distributing an application that uses one or more Device Manufacturer capabilities. The tools used in the signing process are documented in detail within your UIQ SDK.

File System Support

The size and performance of emulated drives, for example ROFS/FAT over NAND flash, are unlikely to be the same as the size and performance on target hardware. For a start, your application may be deployed to numerous different UIQ phones, each with differing hardware platforms. There is configuration support within the emulator to help you achieve a closer emulation matching that of the specific hardware that you are targeting:

• Adjusting disk access speeds by modifying the read and write speeds within epoc.ini.
• Create a partitioned drive on your Windows machine that matches the storage size of target hardware. You can then map the emulator C drive to the partitioned drive and ensure that low memory situations can be handled.

Further details on each of these methods (and others) are available in your SDK documentation.

Floating Point Management

Intel x86 processors have floating point hardware which means that the compiler will generate instructions that use this hardware directly. If this facility is not available in hardware then the compiler must implement the calculations in software, which is obviously much slower. The emulator benefits from this hardware support; however, it may be the case that your target hardware does not have a floating point unit; if your application relies heavily on this type of arithmetic then in this scenario you may see performance differences between emulator and target.

Processes and Threads

The emulator runs in a single Win32 process on your Windows Laptop or PC. You can see this by looking at task manager on your computer; you will see a single epoc.exe process running that represents the entire emulator. Within this process, each Symbian OS executable is run as an individual thread. This differs from target hardware where each Symbian OS executable is launched as a separate process that has a single main thread.

This difference can cause a problem because Win32 process threads share their writable memory. The emulated processes run as threads; they do not have a process boundary to provide them with memory protection. It could be the case that on the emulator a process accesses another’s address space, be it on purpose or by mistake. This is very undesirable, and on target hardware it will result in an access violation.

Stack and Heap

The default heap size on the emulator is 64 MB, which means that when you load your emulator it will emulate a device with a total heap size of 64 MB. The advantage with heap size is that it can be modified by changing the following setting in \epoc32\data\epoc.ini.

MegabytesofFreeMemory 64

This allows you to emulate more precisely a specific target handset.

This MegabytesofFreeMemory value sets the total available heap available to all processes (emulated as threads on Win32) which mean that they must share this memory. When each emulated Symbian OS executable starts it will be given an initial maximum default heap; again this value can be modified by setting the epocheapsize within the appropriate MMP file.

The default heap size and the initial maximum default heap are values that you can modify to ensure that your emulator and application match the target environment as closely as possible. This is not possible with the process stack; on the emulator the stack size will increase as required to much larger limits imposed by the Windows operating system. This can result in stack misuse on the emulator being hidden, only to be highlighted when the application is run on target hardware as a stack overflow (KERN-EXEC panics).

Default stack size on target hardware are typically small, the default value is 8k. Although this can be modified if your application requires, the epocstacksize keyword in your applications MMP file is not supported for emulator builds.

Further Differences

Further differences in operation between emulator and target hardware include USB support, timer resolution, serial ports, scheduling and machine word alignment. The key point is that deploying and testing on hardware is another key step in your development process and differences in application behavior must be considered at this stage.

SIS Files

A native UIQ application can be transferred on to the phone using a number of different approaches that include:

• connectivity software
• sending by Bluetooth, infrared, MMS or Email
• downloading over the Internet
• copying on to a memory card.

Regardless of the approach that is used, your application can only be installed when built in to a SIS file. There is an exception when developing Java based applications however this is outside the scope of this book. Some SIS files are referred to as SISX; this name change distinguishes the format change in Symbian OS v9.1.

Unless you are delivering software that will go in to a mobile phone manufacturer’s ROM then the SIS file is the only mechanism to get your application deployed to target hardware. Here is a simplified overview of this process.

Figure 15 Generating a SIS file

Any SIS file can contain one or many optional embedded SIS files. There is no difference in the process used to generate embedded SIS files; if you use embedded files then you will find that it is a recursive process.

Your package file will define what files (binaries, executables, resource files, text files etc) make up your final application. It will also define application version, vendor, dependency, and language information.

SIS file dependency is used to indicate that your application has a dependency on another component. If the correct version of this component is not available then your application will not install.

Dependency checks can and should also be used to verify the hardware and UI platform of the target phone. Many applications aimed at UIQ 3 are simply deployed with the standard dependency:

(0x101f6300), 3, 0, 0,{"UIQ30ProductID"}

This informs the software installer that the application is dependent on the UIQ 3 platform which means that the application can be installed to any UIQ 3 phone. If your application has only been developed for a specific UIQ phone then it is most likely that it has only been tested on that phone. As a developer, you should consider the effect on your application being deployed to phones that it has not been tested on. There are further cases for restrictions; you may not want to install an application that uses WiFi on non-WiFi phones. You might also want to restrict your application for licensing reasons. Information on how to use dependencies to restrict installation is available from the various handset manufacturers’ developer websites.

Once your package file is defined, you can use the makeSIS tool to build your SIS file.

At the point where you have your final SIS file you have a number of options depending on the intentions of this SIS file:

• Testing, debugging, evaluation, demonstration – In these cases you sign your application with a developer certificate. Figure 16 shows this process.
• Deployment to market – In this case you need to get your application Symbian Signed. Figure 17 shows this process using Certified Signed.

There is an exception to the case above. It may be that you are not using System or Device Manufacturer capabilities and that for whatever reason you do not wish to have your application signed. Under these circumstances your application is ready to be deployed.

If your SIS file is intended for testing, debugging, evaluation or demonstration then you need to use Open Signed, as described in Chapter 14. If you have a Publisher ID, you can download a developer certificate. This certificate along with the Trust Key used to generate the certificate request file will be used by signSIS to generate a signed SIS file. This SIS file will be limited to the target phone IMEIs that were declared when the developer certificate was requested.

Figure 16 Using Open Signed with Publisher ID to deploy for testing

If you use the Certified Signed method, then pre-signing with your Publisher ID (Trust Certificate) is required before your application is submitted to Symbian Signed. Figure 17 takes quite a simplistic view. It does not include:

• documentation required by the Test House such as the capability request form and any test case waiver documentation
• quotation process required to agree on the Test House fee
• handling embedded SIS files that also require signing.

Figure 17 Using Certified Signed to deploy to customers

Summary

Resources

This chapter has examined the various methods and approaches available when testing, debugging and deploying your application to a UIQ phone. The UIQ SDK provides documentation and software tools to support you in this process. There is also further material and tools available from the Symbian Developer Network and the UIQ Developer Portal. There are many third party tools available for use; when deciding upon a strategy you should consider all available options and decide upon an approach that suits your application, company, marketplace and end user.

Key points

The key points to take from this chapter are:

• Do not forget the basics; your application is a guest on the user’s phone, it must be well behaved and respond to the phone specific features and constraints.
• There are many different testing techniques and approaches available. Due to the nature of the hardware and software platform that your application will run on, test techniques such as inter-operability, integration and regression, to name but a few, should feature heavily in your test plans.
• The emulator is a key tool for you to use during development and testing. It is highly configurable and can be adapt to help meet your needs. You should also take in to account that despite the flexibility of the emulator you will still need to test on target hardware.
• All the tools and techniques made available by Symbian and UIQ, for example, Assertions and Debug Macros should be used where appropriate to help detect and reduce software defects.

Application vendors, along with Symbian, UIQ and handset manufacturers have a vested interest that high quality applications are developed and delivered to the end user. This will assist in the sustained growth of the UIQ based handset market and the tools and techniques listed in this chapter go some way to ensure that this goal is achieved.