In many cases, you will have a choice of several projects to port, but on some occasions you may not have to make a choice at all – the project may be selected for you or perhaps you're the author of an original project that you want to port. Where there are multiple projects available, it is often possible to make an initial selection purely by examining project websites and documentation.

Making a selection is not an exact science and depends on a number of personal and technical preferences, such as whether you are familiar with the software as a user, or are more comfortable with C than with C++.

Figure 2.1. The porting process

Here are some other things to bear in mind when making a selection:

If you are using open source code in a commercial project then you need to check the license details very carefully and it would be wise to have your company's legal advisors give approval to proceed. However, even open source developers need to be careful as there can be incompatibilities between licenses which prevent the combination of source code licensed under different terms.

Having selected a candidate project, it's time to have a look at the code. It is definitely worth spending some time on this to avoid nasty surprises later. The goal here isn't to understand how everything works but to get an idea of how the project is structured. You want to work out roughly how much of the code will work unchanged, what will need modifying and which parts will need to be re-written. This should give you a rough idea of how much work is involved, which is useful to know before you start, even if you haven't got a manager breathing down your neck demanding estimates!

If you're exceptionally fortunate, your project will be neatly divided into portable and platform-specific code, perhaps even with a porting guide explaining which parts need to be re-written and how to go about it. In most cases, you won't be anywhere near this lucky and will have to scan through individual files or folders to assess the scale and difficulty of the task. If you're dealing with an open source project, please consider documenting this process for those that follow you, porting to other platforms. It might even be you that benefits from this documentation, if you need to port your entire project to another platform, or if you come back to this project later after changing your mind and attempting to port another one (I've actually been in this situation – all I can say is that documentation for academic projects sometimes rather exaggerates the actual quality of the code!). However good the documentation and code appear to be, it is always useful to compile and run the code on a supported platform. Doing this can not only give you a feel for the maturity and stability of the project but also provide additional information about configuration and the level of compiler warnings to expect.

If your code is pure C or C++ (i.e., it does not call external libraries) then it will probably run on the Symbian platform unchanged. Most standard C/C++ and POSIX libraries are also supported but user interface and multimedia functionality, or anything that directly accesses other hardware, is probably not. For details of which libraries are supported and how to use them on the Symbian platform, see Chapter 4. Examples of libraries that are not currently available on the Symbian platform and how to port software that uses them is explained in Chapter 5.

If you have more than one suitable candidate project, it would be a good idea to confirm some of your assumptions from scanning the project documentation or website. How well documented or commented is the code? Check the included header files to see if there are any unexpected dependencies. Are there likely to be problems with limited resources? In some cases, it may be worth analyzing the code for several projects before making a final selection.

Having analyzed the code, you should consider any general architectural changes required in order to make the porting process (and future maintenance) easier. Where some of the code is portable and other parts need to be re-written, it usually helps to have a modular architecture in which the portable parts are separated from the rest of the project. For applications with a graphical interface, you want to find a nice clean separation between the user interface (UI) and the engine^[34] – if that isn't the case you might consider re-factoring the code on the original platform before you start the port. For small applications, it may not matter but for a large application it may be a sign that you should go back and select another project to port, assuming this is an option. If you are re-factoring a project to increase portability, it's advisable to discuss this with developers working on the project on other platforms if you want to re-integrate your changes when you are done. This kind of major re-factoring is likely to affect everyone using the code-base and integration of the changes will have to be managed carefully.

A popular way of splitting the UI and the engine for Symbian applications is to have them in separate binaries with the UI executable interfacing to a portable DLL. If this split doesn't already exist for the project you are porting then it may not always be sensible to create it artificially. However, you can still split the UI from the engine at a source code (file) level and compile to a single hybrid executable. Historically, one of the major reasons for the split into separate binaries on Symbian OS has been the desire to support multiple UI platforms with a single application engine. The single Symbian platform will reduce the benefit of separating at a binary level as device manufacturers make the transition to a single UI framework. There are still benefits to designing an application with such a split on any platform; for example, it makes it easy to exercise the engine from a test harness and also allows easy stubbing of the engine functions to test the UI. It is debatable whether introducing such a split to a ported project is worth the extra effort unless the core functionality is likely to be re-used in other applications. These alternative application architectures are illustrated in Figure 2.2.

On several platforms, applications often use a polling paradigm: they check the status of various input devices or ongoing operations each time they are scheduled. Depending on the type of application, this may not be very power efficient. For example, it's fine for an arcade-style game^[35] where the user is constantly interacting anyway but perhaps not so good for a chess game or a document viewer where the user only interacts occasionally. On the Symbian platform, the preferred model is event-driven programming (with active objects – see Chapter 3 for details), in which an application's process is suspended, waiting to be notified by the system that an event in which it is interested has occurred. The event-driven paradigm is also used for multi-tasking on the Symbian platform in preference to multi-threading, for most use cases. However, for a ported application it is usually best to change as little as possible, since fewer changes mean fewer opportunities to introduce bugs. For that reason, it is generally recommended to keep existing polling and multi-threading designs where possible. Get the code working first and then determine whether performance or power consumption is a problem. Unfortunately, the lack of standard API availability in UI and multimedia areas forces design changes in some cases. Chapter 5 provides some examples.

Figure 2.2. Application architectures

Apart from major architectural changes that may be required to make the port possible or maintainable, you may also need minor changes to deal with quirks of the platform or performance issues. Some of these changes will require very little modification to code, for example by moving some functionality into another thread or having it run in a callback rather than polling a device. In these cases, you need to think carefully about how the change impacts the rest of the code and what you need to test to make sure it works.

At this stage, you also need to decide what to do with missing dependencies. There are three main options:

A porting layer involves writing wrappers with the original function names from the missing dependency and implementing the underlying functionality in native Symbian C++ code. This can be a good strategy if your project uses only a small subset of the functionality exposed by a missing library. Your choice also depends on how the project is going to be maintained. If it is to be maintained as part of the original project with conditional compilation, rather than as a separate project, then you will probably want to port the dependency or write a porting layer to minimize changes to the common core of the application.

If you need to use some native Symbian functionality to replace a missing dependency, it may also require some changes to the architecture. A common example is an executable that runs a main loop and needs to use Symbian functions that depend on active objects. Active objects require an active scheduler and that blocks the thread in which it is running. The obvious solution here is to run the active scheduler and associated active objects in a separate thread, making the request from the main thread and then polling for the result. However, if you are planning to wait for the result of the operation (i.e. you want a synchronous call), then you can simply start the active scheduler when you make the request and stop it again when you get the response, running the whole thing within one cycle of the main loop. This may not be a great idea if the main loop is running your user interface.

If you are new to Symbian development, then there are a number of tools and resources you will need to set up before you can get started with your port.

Prior to the introduction of Raptor^[40] in the latest version of the platform, the Symbian build system had been in roughly the same form since the early days of the operating system. This meant it was overdue a complete overhaul. Whatever platform you are porting from, you will need to adapt to the build system. This can be a difficult area for larger projects and a major headache if you want to add Symbian to the platforms already supported by a project under a common build system.^[41]

However, both Symbian build systems work with the same input files. In order to port build files to the Symbian system, you will need some understanding of how the builds work on both the original platform and the Symbian platform.

We can't cover all available build systems in this book, although this isn't a very difficult task and most build systems are very similar at an abstract level. The majority of open source software projects use make and all but the simplest also have some kind of configure script^[42] to generate makefiles from templates in order to adapt the build to the host platform.

Symbian has a similar makefile generation system in order to produce makefiles for different host (Windows-based emulator) and target (GCCE or ARM RVCT cross-compilation) builds. The primary inputs for the Symbian build system are a bld.inf file and MMP files. The bld.inf file is very simple: it specifies the target platforms, any exported files (headers, test data, configuration files, etc.) and one or more MMP files. The MMP files have a fairly simple syntax^[43] that lists the build target, target type and path as well as the source files, libraries and include paths used to build it. Many of these can be copied from the (possibly generated) makefile on the original platform, although note that all executables from Symbian OS v9 onwards must be installed to sysin.

PRJ_PLATFORMS,
DEFAULT
PRJ_EXPORTS
..incSoundTouch.h
..incFIFOSamplePipe.h
..incFIFOSampleBuffer.h
..incSTTypes.h
PRJ_MMPFILES
SoundTouch.mmp

TARGET          SoundTouch.dll
TARGETTYPE      dll
UID             0x1000008D 0x0839739D
CAPABILITY      None
USERINCLUDE     ..inc
SYSTEMINCLUDE   epoc32include epoc32includestdapis
SYSTEMINCLUDE   epoc32includestdapissys
SYSTEMINCLUDE   epoc32includestdapisstlport
SOURCEPATH      ..src
SOURCE          SoundTouch.cpp AAFilter.cpp

SOURCE          FIFOSampleBuffer.cpp FIRFilter.cpp
SOURCE          RateTransposer.cpp TDStretch.cpp
LIBRARY         euser.lib
LIBRARY         libc.lib libm.lib libstdcpp.lib

#{"SoundTouch DLL"},(0x0839739D),1,0,0
;Localised Vendor name
%{"Vendor-EN"}
;Unique Vendor name
:"Vendor"
"$(EPOCROOT)Epoc32
elease$(PLATFORM)$(TARGET)SoundTouch.dll"
                                -"!:systemlibsSoundTouch.dll"

This is the easy part! Simply press the Build button in your IDE and wait for it to spit out a great mass of errors. Unless you aren't expecting any problems or the project is very small and simple then it can be a very good idea to comment or #ifdef out large sections of the code and focus on getting some core functionality working. Also, make sure you try building with both the emulator and target compilers regularly to ensure you aren't introducing anything that doesn't work in both environments.

It's important to recognize that build errors generated during a port may be caused by various factors:

Here's where it gets interesting. Unless you are porting a purely computational library or an application or utility that only uses standard APIs that are available on the Symbian platform (see Chapter 4), then you need some knowledge of both the original platform and Symbian platform APIs in order to complete this stage. If you've already got plenty of both then this isn't a problem. If you're porting from one of the other mobile platforms covered in this book, then turn to the relevant chapter (Chapters 7 to 9) for further advice. Otherwise you'll need to consult the available documentation on each platform for any problem areas. As a good start, the first place to look for replacements for missing function calls is the Symbian Developer Library supplied with your SDK. The search function works reasonably well and problems only tend to arise where similar functionality isn't available or has a different name. There are far too many cases like this to list (and I'm sure I'm not aware of them all) but the various discussion forums^[47] are packed with questions and answers from thousands of developers that have trodden the same path before you. If you can't find what you're looking for, just post a new question.

Common problems when moving code to a mobile device platform from a desktop environment are resource limitations and handling the variation in device specifications. Screen size and the available input methods are also limited on mobile devices. While this can cause design issues, it is not as significant as the variation in these features across devices.

Once you have a subset of your code compiling and linking to produce an executable then you can run it in the emulator or install the generated SIS file to your device. We recommend that you do both as early as possible to ensure you aren't relying on features of the emulator (such as the fact that it is running on an x86 architecture processor rather than an ARM-based one) or using APIs that are not supported in your target device. How early you can sensibly test on the device depends on what you are developing and whether you have access to on-device debugging. The ability to set breakpoints, examine variable values and step through code on a real device is extremely valuable when porting code that doesn't produce many visible (or audible) results.

The subject of testing is too big and contentious to cover in detail in this book. However, there are a couple of questions worth addressing that are very relevant to porting. The first question is, 'How do I know when I've finished the port?' If you're working on a small personal project then the answer is probably, 'Whenever you're happy with it or have had enough!' For larger projects, those that you plan to release or re-integrate with the original code base and, particularly, for commercial projects, you will want some more objective criteria. I believe an excellent approach is the one championed in the Symbian ecosystem by Charles Weir of Penrillian^[48] (devise a set of tests on the original platform and make sure they pass there; port the tests as part of the project; when they all pass, you're done). Automated testing is preferred where possible – it allows you to apply test-driven development (TDD) practices to legacy code.^[49] If your project already has a test suite then you're all set. If not, then you either write one or define a set of manual test cases depending on the scale and type of project.

The second question is, 'What do I need to test?' The easy answer to that question is, 'Enough to make sure it works' although that isn't very useful. Optimists (or ostriches sticking their heads in the sand, depending on your point of view) will say, 'If I haven't changed a piece of code it doesn't need testing.' This isn't necessarily true since any number of differences to the environment in which the code is running could cause it to break: timing issues, resource constraints, differences in the compiler and platform can all be the source of new bugs in previously working code. Pessimists (or software quality engineers) will point to the issues I've just listed and say, 'Everything must be tested again!' In practice, it may not be feasible to do a complete re-test of a ported project, particularly if it doesn't already have an automated test suite. As usual, the real answer for each individual project lies somewhere between the extremes and you have to use your judgment.

The process of debugging ported code on the Symbian platform is not significantly different from debugging on other platforms. A key difference from a standard POSIX environment is the lack of stdout and stderr by default (although you can have a console which provides them, it would be in the way of a graphical application). Instead, you can write debugging output to a file or include e32debug.h and use the native Symbian RDebug::Printf() as a direct replacement.^[50]

Another important difference is what happens to errors from the system. Native Symbian C++ functions with names that end L, LC or LD may 'leave'.^[51] A leave that is not caught in an appropriate TRAP macro causes an application to 'panic' – its thread or process is terminated and an error message and code are displayed in a dialog box on the screen. Incorrect use of some system servers may also cause them to panic a thread. There is a system panic reference^[52] in the developer library to help you interpret the cause.

A common source of trouble at this stage is an ALLOC panic when you exit the application. A dialog pops up after your application closes that says 'Panic: ALLOC' followed by two hexadecimal numbers (the second one is usually zero). This means you have a memory leak and the first of the two numbers specifies the address of the heap cell that has been leaked. Other platforms tend to be much more forgiving about memory leaks than Symbian, so they may go undetected for years. Fortunately, thanks to each Symbian process having its own virtual address space, if the program makes the same allocations the same heap cell is leaked on subsequent runs.^[53] This allows for a simple method of debugging these leaks:^[54]

There are slightly more complex and scientific methods of tracking down leaks but this one usually suffices. If your leaked memory address changes because it relates to allocations that depend on remote content or user interaction then you may find the HookLogger an excellent tool to help you track them down.^[55]

Another point worth noting here is that, while the details of a panic are provided in the emulator by default, they are not provided on target devices. To get this information when working on target hardware it is necessary to enable it, or use a third-party crash monitoring tool. For further information on this, see wiki.forum.nokia.com/index.php/Extended_panic_code.

When you've got it all working, you may want to submit your changes back to the original project. This may not be practical if you've had to make significant changes. Where the changes are only minor, it's important to make sure that you can still compile and run on the original platform (and any others supported) by using the appropriate conditional compilation flags (__SYMBIAN32__ is defined for all Symbian targets). Even if you're not planning to re-integrate your code, you may still want to upgrade your port with a future version of the original. Bear this in mind while porting and keep your changes localized (small, neat and separate from the main code whenever possible).

If you're porting C++ code then a good strategy for coping with areas of unavoidable variation is to encapsulate them in a class with a common abstract interface (this could be an abstract base class for two classes, one for each platform). Platform-specific versions of the class can be kept in separate files and the appropriate one selected by the build system. If you can get this refactoring of the original code accepted back into the project then it will be much easier to maintain, with very little chance of merges required for the platform-specific files.

When you do intend to re-integrate your changes, the most important thing is communication with the original developers. It is difficult to give general advice other than that you should follow whatever processes and procedures the project already has in place. Further strategies for writing code to ease future maintenance are discussed in Chapter 15.

In this chapter, I've explained a process that you can follow to port code to the Symbian platform. General advice for the various steps of the process is provided along with options for different approaches that you can tailor to the specific needs of your project. Along the way, I've covered some common issues you might face while porting but general advice will only take you so far. To make your porting projects successful, you need to get into the details. The next three chapters provide the core knowledge you need to work with the Symbian platform. Chapter 3 introduces Symbian idioms and compares them with those used in standard C/C++ development. It also explains how to write safe standard C/C++ code for a resource-constrained device. Chapter 4 goes on to introduce the standard libraries that are supported on the Symbian platform and how you can use them to make porting easier. In contrast, Chapter 5 explains which popular libraries are not available to Symbian developers and what you can do about it.

Throughout this book, particularly in Chapters 10–12, there are examples of open source projects ported to the Symbian platform. The process described in this chapter has been used for those ports and I describe them in that context. Feel free to refer back here to refresh your memory while working through the examples.