Initial contribution of the Adaptation Documentation.
<?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-BB39DE14-B314-59CB-A8EC-BBD2A5C1BCD9" xml:lang="en"><title>GUI
App: Porting an Engine for Use in a Symbian Application</title><shortdesc>This section describes the steps to port an engine for
use in a Symbian application.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The application uses the FreeBSD <codeph>cksum</codeph> utility
as its engine. The checksum example is an application with a user
interface and an engine written in C.</p>
<p>The first stage in porting this program is to split the project
into the engine (GUIAppEng) and the application (GUIApp).</p>
<section id="SECTION_1B097EC0E8EC43BE82B88BE0D04DC5F8"><title>The
engine</title> <p>The engine is written in C. At its core is the <codeph>crc()</codeph> function. This function accepts a file descriptor
and returns the checksum and the file size.</p> <p>The engine's
project specification file (<filepath>GUIAppEng.mmp</filepath>)
is as follows:</p><codeblock xml:space="preserve">TARGET GUIAppEng.dll
TARGETTYPE dll
UID 0x1000008d 0x01000a02
VENDORID 0x70000001
SOURCEPATH .
SOURCE crc.c
SYSTEMINCLUDE \epoc32\include\libc \epoc32\include
LIBRARY estlib.lib euser.lib
#if defined(WINS)
deffile GuiAppEngWINS.def
#else if defined(ARM)
deffile GuiAppEngARM.def
#endif
nostrictdef</codeblock> <p> The output file is <filepath>GUIAppEng.dll</filepath>, whose import library will be included by the UI. </p>
<p> The first UID specified (<codeph>0x1000008d</codeph>)
is the standard UID for an interface DLL. The second UID (<codeph>0x01100a02</codeph>) is unique to the <filepath>GUIApp</filepath> project. </p> <p> Splitting the project into engine
and UI means that the definition of <codeph>crc()</codeph> in <filepath>crc.c</filepath> must be marked <codeph>EXPORT_C</codeph> because
this function will be exported from the engine's DLL. </p>
<p> For more information on DLLs, see <xref href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita">DLLs</xref>.
</p> </section>
<section id="GUID-52000200-5CFD-4FE1-B80E-0A5F4C7E050D"> <title>Porting
checksum - the GUI app</title> <p> The implementation of checksum
(<filepath>GUIApp.app</filepath>) limits the user to the selection
of a single file at a time and uses the default algorithm <codeph>crc()</codeph>, defined in <filepath>crc.c</filepath>, to produce
a 32-bit value. </p> <p> The user interface provides
two main menu commands; <codeph>Calculate checksum</codeph> (invokes
a file selection dialog) and <codeph>View checksums</codeph>.
When a file is selected and <codeph>OK</codeph> is pressed, the
selected file name is retrieved and opened as shown in the following
code: </p> <codeblock xml:space="preserve">const TUint16* fn = iFileName->PtrZ();
int fd = wopen( ( const wchar_t* )fn, O_RDONLY, 0 ); </codeblock>
<p> This code fragment is taken from <filepath>examples\stdlib\GUIApp.cpp.</filepath> </p> <p> <codeph>open()</codeph> returns a file descriptor
which the engine's <codeph>crc()</codeph> function uses to identify
the file. The checksum is calculated (unless an error occurred
in attempting to open or read the file), and is displayed. The
file is closed. </p> <p> The file name and checksum
are appended to an array, the contents of which may be viewed
by selecting <codeph>View checksums</codeph>. </p> </section>
<section id="SECTION_7A8BA355A42C45C3A14EDF1756AB1126"> <title>Linking to STDLIB - The project specification</title> <p>
The application program includes several STDLIB header files, located
in <filepath>\epoc32\include\libc\</filepath>. At link time, the
program includes <filepath>estlib.lib</filepath> and the engine
DLL's <filepath>.lib</filepath> (<filepath>GUIAppEng.lib</filepath>). Unlike the previous examples, this application does not link
to <filepath>ecrt0.lib</filepath>. In this application there is no
<codeph>main()</codeph> and the Symbian platform provides its
own <codeph>E32Main()</codeph>. </p> </section>
<section id="GUID-39A0C47A-38DC-4487-981D-D8BBC50D6DCF"> <title>Some potential issues</title> <ul id="UL_632D231449CE4474996ACD148CB9754D">
<li> <p><b>Removing writeable static</b></p> <p> The PETRAN
stage of building may report a message similar to the following:
</p> <codeblock xml:space="preserve">WARNING: Dll 'SLSUMENG[0x01000a02].DLL' has initialised data.</codeblock> <p> This warning, which is not reported when building for
the Emulator, indicates that the DLL contains non-const static
data. This is not allowed in ARM builds. If it is not obvious
where the problem occurs, the associated <filepath>.map</filepath> file (<filepath>epoc32\release\<target>\urel\<dllname>.map</filepath>) contains information which can help to track down the source
file involved. A search for <codeph>from *(.bss)</codeph> (to
find uninitialised data) or <codeph>from *(.data)</codeph> (to
find initialised data) in <filepath>GUIAPPEng.map</filepath> will
reveal the file in which the problem occurs, and the names of
the offending variables, although static variables will not be
named. </p> </li>
<li id="LI_BAD062FD16EC4CC8A11F13D0ACEE8378"><p><b>Include file clashes</b></p> <p> In C++ source files which use STDLIB routines, the Symbian
platform C++ include files must be included before any of the
STDLIB files. Failure to do this will result in the following
warning: </p> <codeblock xml:space="preserve">'NULL' : macro redefinition"</codeblock> </li>
<li> <p><b>Mixing C and C++</b></p> <p> C and C++ have different
views about the names of functions. If you refer to a C function
from C++, ensure that its prototype is declared as <codeph>extern
"C"</codeph>. If there are several such function declarations, it
may be more convenient to enclose them within the following:
</p> <codeblock xml:space="preserve">#ifdef __cplusplus
extern "C"
{
#endif
...
#ifdef __cplusplus
}
#endif</codeblock> <p> See for example <filepath>examples\stdlib\GUIApp\extern.h</filepath>. </p> </li>
<li id="LI_68EE8B3B25594B48864D5183BA8155AB"> <p><b>Stack usage</b></p> <p> Some programs produce the following error: </p> <codeblock xml:space="preserve">unresolved external symbol __chkstk</codeblock>
<p> unless the amount of stack they use is reduced. Symbian
threads have only 8k stack by default. </p> </li>
<li> <p><b>Resource cleanup</b></p> <p> The Symbian platform has
a requirement that all resources which were allocated by an application
must be cleaned up by the time the program terminates. On the
Emulator, in debug builds, failure to do this will cause a panic
from the <codeph>__UHEAP_MARKEND</codeph> macro. </p> <p> Because the data allocated in the thread-local storage for STDLIB's
DLL (the <codeph>_reent</codeph> structure) is not automatically
cleaned up when the environment is destroyed, it must be cleaned
up by the user of STDLIB. </p> <p> The function to achieve
this is <codeph>CloseSTDLIB()</codeph>. To use this function,
file <filepath>epoc32\include\libc\sys\reent.h</filepath> must be
included in the project. Call <codeph>CloseSTDLIB()</codeph> after
the point at which it is known that code in STDLIB's DLL will
no longer be called and its thread-local storage no longer needed.
</p> <p> For example, see the destructor for <codeph>CExampleDocument</codeph> in <filepath>examples\stdlib\GUIApp\GUIApp.cpp</filepath>. </p> </li>
</ul> </section>
</conbody><related-links>
<link href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita"><linktext>DLLs</linktext>
</link>
</related-links></concept>