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:

> abld freeze

Either method will create the frozen .def file containing the projects exported functions. Note that the 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 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 succint 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.