<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-CF8287B9-2063-5316-A1BF-7DFC58FCDE30" xml:lang="en"><title>How

to freeze exports</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>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 <codeph>exportunfrozen</codeph> 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 <codeph>exportunfrozen</codeph> keyword,

and supply a <filepath>.def</filepath> file listing the exports. </p>

<p>To create a <filepath>.def</filepath> file, build the project in the normal

way. A warning will be generated to the effect that the frozen <filepath>.def</filepath> file

does not yet exist. Once the project has been built you can freeze it by calling

the <codeph>freeze</codeph> target in the makefiles. You can do this with <codeph>abld</codeph> by

using: </p>

<p><userinput>abld freeze </userinput> </p>

<p>Either method will create the frozen <filepath>.def</filepath> file containing

the project’s exported functions. Note that the Symbian emulator targets and

ARM targets have different <filepath>.def</filepath> file formats, so that

if you build for both of these, you will need to store two def files. </p>

<p>Once the project is frozen, regenerate the makefiles so that the import

library will be created directly from the frozen <filepath>.def</filepath> file. </p>

<p>The project can be frozen in this way even if the <codeph>exportunfrozen</codeph> statement

is specified, but the import library will be created as a side-effect of linking

rather than from the frozen <filepath>.def</filepath> file, and this import

library will be created whether the project is frozen or not. </p>

<section><title>Storing deffiles </title><p>By default, the build tools look

for the Symbian emulator build def file in a <codeph>BWINS</codeph> directory

(at the same level as the directory containing the mmp file), and the ARM

def file in a <codeph>EABI</codeph> 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 <codeph>deffile</codeph> keyword. </p><p>Because the .def files

are different for different targets, it's necessary to use <codeph>#if defined</codeph> macros

to select the correct def file, depending on the target for which the project

is being built. The following example does this: </p><codeblock id="GUID-B5FB9EAB-EA32-567D-8190-45085E4497C5" xml:space="preserve">#if defined(WINS)

deffile    ..\freeze\CONVPLUG-WINS.DEF

#else

deffile    ..\freeze\CONVPLUG-EABI.DEF

#endif</codeblock><p>A more succinct syntax is also available:</p><codeblock id="GUID-47BB23C9-15DD-5B96-A567-C36AA55EAEE1" xml:space="preserve">deffile ..\~\x.def</codeblock><p>A

directory named ~ in a deffile path is automatically replaced with bwins or

eabi as necessary depending on which target is being built.  </p></section>

<section><title>Adding new exports </title><p>New exports can be added to

the frozen <filepath>.def</filepath> file by calling the <codeph>freeze</codeph> target

in the makefiles once the project has been built with the new exports incorporated. </p><p>The <codeph>freeze</codeph> target

calls a tool, <filepath>efreeze</filepath>, to compare the frozen <filepath>.def</filepath> file,

if it exists, with the one generated by the two-stage link process in directory: <filepath>epoc32\build\</filepath> <varname>absolute_path_to_mmp_file</varname> <filepath>\</filepath> <varname>mmp_basename</varname> <filepath>\</filepath> <varname>platform</varname> <filepath>\</filepath></p><p><filepath>efreeze</filepath> checks that the frozen exports are all present and correct

in the generated <filepath>.def</filepath> file, and appends any new exports

to the end of the frozen <filepath>.def</filepath> file. </p></section>