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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

    14 <p>Released versions of DLLs should freeze their exports, so as to ensure

    15 the backward compatibility of new releases of a library. While you are developing

    16 a DLL, you can use the <codeph>exportunfrozen</codeph> keyword in the project's

    17 mmp file, to tell the build process that exports are not yet frozen. When

    18 you are ready to freeze, remove the <codeph>exportunfrozen</codeph> keyword,

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

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

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

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

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

    24 using: </p>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    39 def file in a <codeph>EABI</codeph> directory. If def files are stored in

    40 these locations, the project files does not need to specify the location of

    41 the def files explicitly. If you want to store the def files in some other

    42 location, you will need to specify in the project file where the .def files

    43 are using the <codeph>deffile</codeph> keyword. </p><p>Because the .def files

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

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

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

    47 deffile    ..\freeze\CONVPLUG-WINS.DEF

    48 #else

    49 deffile    ..\freeze\CONVPLUG-EABI.DEF

    50 #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

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

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

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

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

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

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

    57 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

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

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

    60 </conbody></concept>