EPOC   SDK Home Glossary Indexes Previous   Up

EPOC Release 5 compatibility changes


Contents


Overview

EPOC Release 5 introduces a new feature, debug/release compatibility. Debug/release compatibility allows you to run debug builds of your own programs on a release-build ROM. Previously, it was possible to run debug programs only on a debug ROM, but as debug ROMs were not available to the majority of developers, in practice debug builds were restricted to the EPOC Emulator WINS platform.

Achieving debug/release compatibility will require updating of existing projects built with earlier SDKs (pre-ER5).

Note that as part of the move toward full Unicode support, ER5 also introduces changes in the way UIDs are specified in project files. Project files will therefore also need to be updated for these changes. Possibly, some minor source code changes will also be required. For general information about UIDs, see the UIDs topic in the main C++ System Documentation.

This document describes the changes required to upgrade existing projects to build and run on EPOC Release 5 or later SDKs.


Upgrade process

The aims of the upgrade process are:


Debug/release compatibility

Section Contents

Historically, EPOC components have considered debug and release builds as entirely distinct. There was no incentive to make them binary compatible with each other: the idea was that debugging gets done with debug builds and debug ROMs. However, debug ROMs are not generally available to developers, so debug variants for native platforms were of very limited use.

ER5 introduces changes which support compatibility between any mix of debug and release components (provided they are all built for the same platform).

These changes have affected the EPOC toolchain, specifically makmake, and you should apply the following checks and changes to all projects which export any functions or classes. The objective is to

For each project, you must check the following:

Additionally, if your component has any code which is conditionally compiled based on the _DEBUG or NDEBUG macros, you may need to do some work.

For more about the EPOC build process, current to ER5, see The build process in the main C++ System Documentation.


Identifying incompatibilities

After you have created the new makefile with makmake, you should try building the debug version of your project from the command line. If the link stage generates any warnings or errors from deftool, dlltool or the linker, there are three things to look for:

These tests and any changes you make are likely to be relatively simple for static interface DLLs and for EPOC applications. The latter typically only exports one function, NewApplication(), whose interface does not require change. For complex DLLs with significant built-in debug functionality, the changes are likely to be more complicated.


Testing your changes

The only way to be sure that your new release does achieve debug/release compatibility is to test it. Try the following:


Changes required for UID specification

Section Contents

In EPOC Release 5 the toolchain has been changed to handle UIDs somewhat differently. These changes are required for future Unicode support.


Makmake warning

mmp files now recognise the UNICODEUID statement which specifies UIDs for Unicode variants of projects. If you do not specify Unicode UIDs, makmake will warn you that only narrow makefile targets are available.


Removing old UID specifications

If you started your project using an early EPOC SDK, you may have coded your UIDs using syntax such as:

    #pragma data_seg(".E32_UID")
    __WINS_UID(0,KAppUidValue,369)
    #pragma data_seg()

You will now need to delete such statements. makmake will generate the UID based on the project file specification, and your project will not link correctly if you leave such statements in your project source code.

EPOC Release 3 SDKs introduced the AUTOUID makmake keyword which implemented the above directive automatically. Now this too is prohibited: you will have to remove the AUTOUID keyword from your .mmp files. The UID and UNICODEUID statements are sufficient to allow makmake to generate the necessary UIDs into your project.

EPOC       SDK Home Glossary Indexes Previous   Up