How +to freeze exports

Released versions of DLLs should freeze their exports, so as to ensure +the backward compatibility of new releases of a library. While you are developing +a DLL, you can use the exportunfrozen keyword in the project's +mmp file, to tell the build process that exports are not yet frozen. When +you are ready to freeze, remove the exportunfrozen keyword, +and supply a .def file listing the exports.

To create a .def file, build the project in the normal +way. A warning will be generated to the effect that the frozen .def file +does not yet exist. Once the project has been built you can freeze it by calling +the freeze target in the makefiles. You can do this with abld by +using:

Either method will create the frozen .def file containing +the project’s exported functions. Note that the Symbian emulator targets and +ARM targets have different .def file formats, so that +if you build for both of these, you will need to store two def files.

Once the project is frozen, regenerate the makefiles so that the import +library will be created directly from the frozen .def file.

The project can be frozen in this way even if the exportunfrozen statement +is specified, but the import library will be created as a side-effect of linking +rather than from the frozen .def file, and this import +library will be created whether the project is frozen or not.

Storing deffiles

By default, the build tools look +for the Symbian emulator build def file in a BWINS directory +(at the same level as the directory containing the mmp file), and the ARM +def file in a EABI directory. If def files are stored in +these locations, the project files does not need to specify the location of +the def files explicitly. If you want to store the def files in some other +location, you will need to specify in the project file where the .def files +are using the deffile keyword.

Because the .def files +are different for different targets, it's necessary to use #if defined macros +to select the correct def file, depending on the target for which the project +is being built. The following example does this:

#if defined(WINS) +deffile ..\freeze\CONVPLUG-WINS.DEF +#else +deffile ..\freeze\CONVPLUG-EABI.DEF +#endif

A more succinct syntax is also available:

deffile ..\~\x.def

A +directory named ~ in a deffile path is automatically replaced with bwins or +eabi as necessary depending on which target is being built.

Adding new exports

New exports can be added to +the frozen .def file by calling the freeze target +in the makefiles once the project has been built with the new exports incorporated.

The freeze target +calls a tool, efreeze, to compare the frozen .def file, +if it exists, with the one generated by the two-stage link process in directory: epoc32\build\ absolute_path_to_mmp_file \ mmp_basename \ platform \

efreeze checks that the frozen exports are all present and correct +in the generated .def file, and appends any new exports +to the end of the frozen .def file.