--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-BB39DE14-B314-59CB-A8EC-BBD2A5C1BCD9.dita Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,131 @@
+<?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> <p>
+ For information on Symbian applications, their project specification,
+ and resource files, see <xref href="GUID-81835322-5EF7-5839-9DC1-9A3FD396BD36.dita">How
+to build GUI applications</xref>. </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>
+<link href="GUID-81835322-5EF7-5839-9DC1-9A3FD396BD36.dita"><linktext>How to build
+GUI applications</linktext></link>
+</related-links></concept>
\ No newline at end of file