|
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-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 |
|
13 application.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>The application uses the FreeBSD <codeph>cksum</codeph> utility as its |
|
14 engine. The checksum example is an application with a user interface and an |
|
15 engine written in C.</p> |
|
16 <p>The first stage in porting this program is to split the project into |
|
17 the engine (GUIAppEng) and the application (GUIApp).</p> |
|
18 <section id="SECTION_1B097EC0E8EC43BE82B88BE0D04DC5F8"><title>The engine</title> |
|
19 <p>The engine is written in C. At its core is the <codeph>crc()</codeph> |
|
20 function. This function accepts a file descriptor and returns the checksum and |
|
21 the file size.</p> |
|
22 <p>The engine's project specification file (<filepath>GUIAppEng.mmp</filepath>) |
|
23 is as follows:</p><codeblock xml:space="preserve">TARGET GUIAppEng.dll |
|
24 TARGETTYPE dll |
|
25 UID 0x1000008d 0x01000a02 |
|
26 VENDORID 0x70000001 |
|
27 SOURCEPATH . |
|
28 SOURCE crc.c |
|
29 SYSTEMINCLUDE \epoc32\include\libc \epoc32\include |
|
30 LIBRARY estlib.lib euser.lib |
|
31 |
|
32 #if defined(WINS) |
|
33 deffile GuiAppEngWINS.def |
|
34 #else if defined(ARM) |
|
35 deffile GuiAppEngARM.def |
|
36 #endif |
|
37 nostrictdef</codeblock> |
|
38 <p> |
|
39 The output file is <filepath>GUIAppEng.dll</filepath>, whose import library |
|
40 will be included by the UI. |
|
41 </p> |
|
42 <p> |
|
43 The first UID specified (<codeph>0x1000008d</codeph>) is the standard UID |
|
44 for an interface DLL. The second UID (<codeph>0x01100a02</codeph>) is unique to the |
|
45 <filepath>GUIApp</filepath> project. |
|
46 </p> |
|
47 <p> |
|
48 Splitting the project into engine and UI means that the definition of |
|
49 <codeph>crc()</codeph> in <filepath>crc.c</filepath> must be marked <codeph>EXPORT_C</codeph> |
|
50 because this function will be exported from the engine's DLL. |
|
51 </p> |
|
52 <p> |
|
53 For more information on DLLs, see <xref href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita">DLLs</xref>. |
|
54 </p> |
|
55 </section> |
|
56 <section> |
|
57 <title>Porting checksum - the GUI app</title> |
|
58 <p> |
|
59 The implementation of checksum (<filepath>GUIApp.app</filepath>) limits the |
|
60 user to the selection of a single file at a time and uses the default algorithm |
|
61 <codeph>crc()</codeph>, defined in <filepath>crc.c</filepath>, to produce a 32-bit value. |
|
62 </p> |
|
63 <p> |
|
64 The user interface provides two main menu commands; <codeph>Calculate |
|
65 checksum</codeph> (invokes a file selection dialog) and <codeph>View |
|
66 checksums</codeph>. When a file is selected and <codeph>OK</codeph> is pressed, the |
|
67 selected file name is retrieved and opened as shown in the following code: |
|
68 </p> |
|
69 <codeblock xml:space="preserve">const TUint16* fn = iFileName->PtrZ(); |
|
70 int fd = wopen( ( const wchar_t* )fn, O_RDONLY, 0 ); </codeblock> |
|
71 <p> |
|
72 This code fragment is taken from |
|
73 <filepath>examples\stdlib\GUIApp.cpp.</filepath> |
|
74 </p> |
|
75 <p> |
|
76 <codeph>open()</codeph> returns a file descriptor which the engine's |
|
77 <codeph>crc()</codeph> function uses to identify the file. The checksum is |
|
78 calculated (unless an error occurred in attempting to open or read the file), |
|
79 and is displayed. The file is closed. |
|
80 </p> |
|
81 <p> |
|
82 The file name and checksum are appended to an array, the contents of |
|
83 which may be viewed by selecting <codeph>View checksums</codeph>. |
|
84 </p> |
|
85 </section> |
|
86 <section id="SECTION_7A8BA355A42C45C3A14EDF1756AB1126"> |
|
87 <title>Linking to STDLIB - The project specification</title> |
|
88 <p> |
|
89 The application program includes several STDLIB header files, located |
|
90 in <filepath>\epoc32\include\libc\</filepath>. At link time, the program includes |
|
91 <filepath>estlib.lib</filepath> and the engine DLL's <filepath>.lib</filepath> |
|
92 (<filepath>GUIAppEng.lib</filepath>). Unlike the previous examples, this application |
|
93 does not link to <filepath>ecrt0.lib</filepath>. In this application there is no |
|
94 <codeph>main()</codeph> and Symbian platform provides its own |
|
95 <codeph>E32Main()</codeph>. |
|
96 </p> |
|
97 <p> |
|
98 For information on Symbian applications, their project specification, |
|
99 and resource files, see <xref href="GUID-81835322-5EF7-5839-9DC1-9A3FD396BD36.dita">How to build GUI applications</xref>. |
|
100 </p> |
|
101 </section> |
|
102 <section> |
|
103 <title>Some potential issues</title> |
|
104 <ul id="UL_632D231449CE4474996ACD148CB9754D"> |
|
105 <li> |
|
106 <p><b>Removing writeable static</b></p> |
|
107 <p> |
|
108 The PETRAN stage of building may report a message similar to the |
|
109 following: |
|
110 </p> |
|
111 <codeblock xml:space="preserve">WARNING: Dll 'SLSUMENG[0x01000a02].DLL' has initialised data.</codeblock> |
|
112 <p> |
|
113 This warning, which is not reported when building for the Emulator, |
|
114 indicates that the DLL contains non-const static data. This is not allowed in |
|
115 ARM builds. If it is not obvious where the problem occurs, the associated |
|
116 <filepath>.map</filepath> file |
|
117 (<filepath>epoc32\release\<target>\urel\<dllname>.map</filepath>) contains |
|
118 information which can help to track down the source file involved. A search for |
|
119 <codeph>from *(.bss)</codeph> (to find uninitialised data) or <codeph>from |
|
120 *(.data)</codeph> (to find initialised data) in <filepath>GUIAPPEng.map</filepath> will |
|
121 reveal the file in which the problem occurs, and the names of the offending |
|
122 variables, although static variables will not be named. |
|
123 </p> |
|
124 </li><li id="LI_BAD062FD16EC4CC8A11F13D0ACEE8378"><p><b>Include file clashes</b></p> |
|
125 <p> |
|
126 In C++ source files which use STDLIB routines, the Symbian platform |
|
127 C++ include files must be included before any of the STDLIB files. Failure to |
|
128 do this will result in the following warning: |
|
129 </p> |
|
130 <codeblock xml:space="preserve">'NULL' : macro redefinition"</codeblock> |
|
131 </li> |
|
132 <li> |
|
133 <p><b>Mixing C and C++</b></p> |
|
134 <p> |
|
135 C and C++ have different views about the names of functions. If you |
|
136 refer to a C function from C++, ensure that its prototype is declared as |
|
137 <codeph>extern "C"</codeph>. If there are several such function declarations, it |
|
138 may be more convenient to enclose them within the following: |
|
139 </p> |
|
140 <codeblock xml:space="preserve">#ifdef __cplusplus |
|
141 extern "C" |
|
142 { |
|
143 #endif |
|
144 ... |
|
145 #ifdef __cplusplus |
|
146 } |
|
147 #endif</codeblock> |
|
148 <p> |
|
149 See for example <filepath>examples\stdlib\GUIApp\extern.h</filepath>. |
|
150 </p> |
|
151 </li> |
|
152 |
|
153 <li id="LI_68EE8B3B25594B48864D5183BA8155AB"> |
|
154 <p><b>Stack usage</b></p> |
|
155 <p> |
|
156 Some programs produce the following error: |
|
157 </p> |
|
158 <codeblock xml:space="preserve">unresolved external symbol __chkstk</codeblock> |
|
159 <p> |
|
160 unless the amount of stack they use is reduced. Symbian threads have |
|
161 only 8k stack by default. |
|
162 </p> |
|
163 </li> |
|
164 |
|
165 <li> |
|
166 <p><b>Resource cleanup</b></p> |
|
167 <p> |
|
168 Symbian platform has a requirement that all resources which were |
|
169 allocated by an application must be cleaned up by the time the program |
|
170 terminates. On the Emulator, in debug builds, failure to do this will cause a |
|
171 panic from the <codeph>__UHEAP_MARKEND</codeph> macro. |
|
172 </p> |
|
173 <p> |
|
174 Because the data allocated in the thread-local storage for STDLIB's |
|
175 DLL (the <codeph>_reent</codeph> structure) is not automatically cleaned up when |
|
176 the environment is destroyed, it must be cleaned up by the user of STDLIB. |
|
177 </p> |
|
178 <p> |
|
179 The function to achieve this is <codeph>CloseSTDLIB()</codeph>. To use |
|
180 this function, file <filepath>epoc32\include\libc\sys\reent.h</filepath> must be |
|
181 included in the project. Call <codeph>CloseSTDLIB()</codeph> after the point at |
|
182 which it is known that code in STDLIB's DLL will no longer be called and its |
|
183 thread-local storage no longer needed. |
|
184 </p> |
|
185 <p> |
|
186 For example, see the destructor for <codeph>CExampleDocument</codeph> in |
|
187 <filepath>examples\stdlib\GUIApp\GUIApp.cpp</filepath>. |
|
188 </p> |
|
189 |
|
190 </li> |
|
191 </ul> |
|
192 |
|
193 |
|
194 </section> |
|
195 |
|
196 </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> |