Symbian3/PDK/Source/GUID-BB39DE14-B314-59CB-A8EC-BBD2A5C1BCD9.dita
changeset 1 25a17d01db0c
child 3 46218c8b8afa
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-BB39DE14-B314-59CB-A8EC-BBD2A5C1BCD9.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,196 @@
+<?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>
+<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-&gt;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 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>
+		<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\&lt;target&gt;\urel\&lt;dllname&gt;.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>
+			 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