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.