<?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>
</conbody></concept>