|
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-64D2B0E2-BB5D-4009-ACE5-7A3503016341" xml:lang="en"><title>Troubleshooting |
|
13 Tips</title><shortdesc>This section addresses the basic differences in the way things |
|
14 are done in Symbian Platform and in Linux. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-1"> <title>Symbian |
|
16 directory structure</title> <p>In Symbian platform, project source files |
|
17 are arranged based on the directory pattern shown below.</p><table id="GUID-AF9A4B8F-EC2B-4BBA-AE84-9B49F2081B4F"> |
|
18 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
19 <tbody> |
|
20 <row> |
|
21 <entry><p><b>Directory</b></p></entry> |
|
22 <entry><p><b>Description</b></p></entry> |
|
23 </row> |
|
24 <row> |
|
25 <entry><codeph>src</codeph></entry> |
|
26 <entry><p>Contains all the source files of the project.</p></entry> |
|
27 </row> |
|
28 <row> |
|
29 <entry><codeph>inc</codeph></entry> |
|
30 <entry><p>Contains all the header files of the project.</p></entry> |
|
31 </row> |
|
32 <row> |
|
33 <entry><codeph>group</codeph></entry> |
|
34 <entry><p>Contains MMP files, and bld.inf. </p></entry> |
|
35 </row> |
|
36 </tbody> |
|
37 </tgroup> |
|
38 </table> <p>The developer can choose whether to follow these tips.</p></section> |
|
39 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-2"> <title>EXPORT_C, |
|
40 DEF file and ordinal numbers</title> <p>This applies only for the DLL |
|
41 target type. If a DLL wants to export an API, the code definition should start |
|
42 with the macro <codeph>EXPORT_C</codeph>.</p><codeblock xml:space="preserve">// Declaration |
|
43 #ifdef SYMBIAN |
|
44 #define GLOBAL(type) EXPORT_C type |
|
45 #else |
|
46 #define GLOBAL(type) type |
|
47 #endif // SYMBIAN |
|
48 // Definition |
|
49 GLOBAL(void) |
|
50 jpeg_CreateDecompress (j_decompress_ptr cinfo, int version, size_t structsize) |
|
51 { |
|
52 int i; |
|
53 |
|
54 /* Guard against version mismatches between library and caller. */ |
|
55 cinfo->mem = NULL; /* so jpeg_destroy knows mem mgr not called */ |
|
56 if (version != JPEG_LIB_VERSION) |
|
57 ERREXIT2(cinfo, JERR_BAD_LIB_VERSION, JPEG_LIB_VERSION, version); |
|
58 if (structsize != SIZEOF(struct jpeg_decompress_struct)) |
|
59 ERREXIT2(cinfo, JERR_BAD_STRUCT_SIZE, |
|
60 (int) SIZEOF(struct jpeg_decompress_struct), (int) structsize); |
|
61 ... |
|
62 } </codeblock><p>Whenever a DLL is built on Symbian platform, it creates |
|
63 three files: </p><ul> |
|
64 <li><p><filepath><target>.dll</filepath> is the actual DLL that gets loaded |
|
65 at runtime </p></li> |
|
66 <li><p><filepath><target>.lib</filepath> is the static library which contains |
|
67 wrappers for each DLL exported function that, when run, will locate and execute |
|
68 the real function’s code in the appropriate runtime-loaded DLL. </p></li> |
|
69 <li><p><filepath><target.def></filepath> gets created when the user executes |
|
70 abld freeze. The <filepath>.def</filepath> file contains the list of exported |
|
71 DLL functions along with their ordinal numbers. Symbian platform does not |
|
72 store exported symbol names in DLL; instead, the exported functions are referenced |
|
73 using only their ordinal numbers. Storing the ordinal numbers instead of names |
|
74 reduces the size of the DLL. </p></li> |
|
75 </ul><p>The following is a sample <filepath>.def</filepath> file created for <codeph>libjpeg</codeph>:</p><codeblock xml:space="preserve">EXPORTS |
|
76 jcopy_block_row @ 1 NONAME |
|
77 jcopy_sample_rows @ 2 NONAME |
|
78 jdiv_round_up @ 3 NONAME |
|
79 jinit_1pass_quantizer @ 4 NONAME |
|
80 jinit_2pass_quantizer @ 5 NONAME |
|
81 jinit_c_coef_controller @ 6 NONAME |
|
82 jinit_c_main_controller @ 7 NONAME |
|
83 jinit_c_master_control @ 8 NONAME |
|
84 jinit_c_prep_controller @ 9 NONAME |
|
85 jinit_color_converter @ 10 NONAME |
|
86 </codeblock><p>The following example shows how to declare and define an exportable |
|
87 function from a DLL and to make it callable from a Symbian C++ application: |
|
88 </p><p>In <filepath>xxx.h</filepath></p><codeblock xml:space="preserve">#ifdef __cplusplus |
|
89 extern "C" |
|
90 #endif |
|
91 IMPORT_C int Foo(); |
|
92 </codeblock><p>In <codeph>xxx.c</codeph></p><codeblock xml:space="preserve">extern "C" EXPORT_C int Foo() |
|
93 { |
|
94 return something; |
|
95 } |
|
96 </codeblock> </section> |
|
97 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-3"> <title><codeph>dlsym()</codeph> or <codeph>g_module_symbol()</codeph></title> |
|
98 <p>Since DLL entry points are not exported by name, DLL symbol lookup |
|
99 functions do not work on Symbian platform. For more information about alternatives |
|
100 suggested on Symbian platform, see <xref href="GUID-9D278187-8B5E-581D-9869-EE8861048F93.dita">Dynamic |
|
101 Link Libraries</xref>.</p><p>The functions <codeph>dlsym()</codeph> from <codeph>libdl</codeph> and <codeph>g_module_symbol()</codeph> from GLib are examples of such functions. Look for usage of these functions |
|
102 in the OSS port and change the code.</p><codeblock xml:space="preserve">ret = g_module_symbol (module, "jinit_c_prep_controller", &ptr); |
|
103 </codeblock><p>needs to be changed to:</p><codeblock xml:space="preserve">ret = g_module_symbol (module, "9", &ptr);</codeblock><p>For |
|
104 example, for <codeph>dlsym()</codeph> pass the function's ordinal number as |
|
105 symbol parameter (refer the library's list of exports, the DEF file for the |
|
106 function's ordinal number):</p><codeblock xml:space="preserve">dlsym(&handle, "foo") |
|
107 </codeblock><p>needs to be changed to:</p><codeblock xml:space="preserve">dlsym (&handle, "3")</codeblock></section> |
|
108 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-4"><title>Problem with |
|
109 a variable list of arguments in macros</title><p>This section suggests a way |
|
110 to overcome the problems faced when macros with a variable list of arguments |
|
111 are used.</p><codeblock xml:space="preserve">#define DEBUG(a,...)</codeblock><p>The above statement |
|
112 causes a compilation error. One of the solutions to solve this problem is |
|
113 as follows:</p><codeblock xml:space="preserve">#define DEBUG _DEBUG |
|
114 static inline void _DEBUG (const char *a, ...) |
|
115 { |
|
116 }</codeblock> </section> |
|
117 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-5"> <title>Keep |
|
118 changes to OSS to a minimum</title><p>While porting the OSS code, keep the |
|
119 changes to the OSS code as few as possible. The OSS code is already tested |
|
120 and used by a bigger community, and is unlikely to have any compilation errors |
|
121 or major logical errors. In many cases code changes that are necessary brings |
|
122 potential logical flaws to the OSS port. Minimum changes to the OSS code while |
|
123 porting also helps in merging to the new OSS. </p> </section> |
|
124 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-6"> <title>Exporting |
|
125 variables from a DLL</title> <p>Exporting data from a DLL is not allowed |
|
126 in Symbian platform . The following pattern can be used:</p><ol> |
|
127 <li id="GUID-FE2ACA35-3472-47C2-8C3F-B65CAEE09C66"><p>Do not export global |
|
128 variables. Within DLL, there is one global variable, for example:</p><codeblock xml:space="preserve">int globalVal; </codeblock></li> |
|
129 <li id="GUID-F6A52B57-7E83-4DFE-9FD3-AB8E7D9B55D4"><p> Export one method |
|
130 that returns a pointer to that variable.</p><codeblock xml:space="preserve">extern "C" EXPORT_C int* GlbData () |
|
131 { |
|
132 return &globalVal |
|
133 } |
|
134 </codeblock></li> |
|
135 <li id="GUID-3231DC39-90BF-4775-BC66-2ADC9A60463E"><p>Define a macro for the |
|
136 user of the DLL. See the example below. Within the DLL header (for example, <filepath>xxx.h</filepath>), |
|
137 define the following:</p><codeblock xml:space="preserve">#ifdef __cplusplus |
|
138 extern "C" |
|
139 #endif |
|
140 IMPORT_C int* GlbData (); |
|
141 #define globalVal (*GlbData())</codeblock></li> |
|
142 </ol> </section> |
|
143 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-7"> <title>Application |
|
144 is not loaded</title> <p>The absence of the dependent libraries could |
|
145 be one of the reasons for the application not to load in the mobile device. |
|
146 On the target device, Symbian platform looks for libraries in <filepath>c:\sys\bin</filepath> or |
|
147 in <filepath>z:\sys\bin</filepath>.</p><p>Do make sure that all the libraries |
|
148 are present in either of the above-mentioned libraries. </p> </section> |
|
149 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-8"> <title>Capabilities |
|
150 not known</title> <p>Capabilities are specified in the MMP file. The |
|
151 primary information source is the P.I.P.S. API reference documentation. If |
|
152 problems with capabilities remain, one known method to find the capability |
|
153 is to analyze the [Debug Messages] window in CodeWarrior IDE (while debugging). |
|
154 During development, <codeph>CAPABILITY All –Tcb</codeph> is acceptable, but |
|
155 for release code it is good practice to give a valid capability in the MMP |
|
156 file in order to have the application successfully signed. The following is |
|
157 a sample of a capability error found in the [Debug Messages] window. </p><codeblock xml:space="preserve">*PlatSec* ERROR - Capability check failed - Process hellogst.exe[10015942]0001 was checked by Thread c32exe.exe[101f7989]0001::ESock_IP and was found to be missing the capabilities: NetworkServices. </codeblock> </section> |
|
158 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-9"> <title>Environment |
|
159 variables</title> <p>At the moment, environment variables are not completely |
|
160 supported in Symbian C++. Therefore be wary of using library functions like <codeph>getenv()</codeph> which |
|
161 work on environment variables. Make sure the library initialization routine |
|
162 calls <codeph>setenv()</codeph> with the proper value of the environment variable. |
|
163 Also, be wary of functions like <codeph>g_get_home_dir()</codeph> which may |
|
164 not work as they behave in Linux.</p><codeblock xml:space="preserve">if ((memenv = getenv("JPEGMEM")) != NULL) // will not work properly</codeblock><p>Suggested |
|
165 change: </p><codeblock xml:space="preserve">void LibraryInit() |
|
166 { |
|
167 setenv ("JPEGMEM ", "XXXXX", 1); |
|
168 }</codeblock> </section> |
|
169 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-10"> <title>Assembly |
|
170 code</title> <p>The syntax for inline assembly code is different in |
|
171 Symbian platform. The following is a code snippet of assembly code syntax |
|
172 in Symbian platform.</p><codeblock xml:space="preserve">EXPORT_C __NAKED__ TUint16 TTemplate::Register16(TUint anAddr) |
|
173 /** |
|
174 Read a 16-bit register |
|
175 @returns register contents |
|
176 */ |
|
177 { |
|
178 asm("ldrh r0,[r0]"); |
|
179 __JUMP(,lr); |
|
180 } </codeblock><p>In common practice the assembly code has the extension <filepath>.CIA</filepath> in |
|
181 Symbian platform, whereas in Linux the assembly code has the extension <filepath>.S</filepath>. |
|
182 </p> </section> |
|
183 <section id="GUID-77D7347D-8DEC-45D0-A677-8FDBDFB8FF81-GENID-1-8-1-11-1-1-5-1-3-1-9-1-3-11"> <title>Glossary</title> |
|
184 <p>The following table lists terms used in Linux and their approximate |
|
185 equivalents in Symbian platform: </p><table id="GUID-BFB874F5-148B-44B2-A110-F37AC084756B"> |
|
186 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
187 <tbody> |
|
188 <row> |
|
189 <entry><p><b>Linux</b></p></entry> |
|
190 <entry><p><b>Symbian</b></p></entry> |
|
191 </row> |
|
192 <row> |
|
193 <entry><p><codeph>-D</codeph> of Makefile </p></entry> |
|
194 <entry><p><codeph>MACRO</codeph> of theMMP file </p></entry> |
|
195 </row> |
|
196 <row> |
|
197 <entry><p><codeph>-I</codeph> of Makefile</p></entry> |
|
198 <entry><p><codeph>USERINCLUDE</codeph> of the MMP file </p></entry> |
|
199 </row> |
|
200 <row> |
|
201 <entry><p><codeph>SO</codeph></p></entry> |
|
202 <entry><p>DLL</p></entry> |
|
203 </row> |
|
204 <row> |
|
205 <entry><p><codeph>A</codeph></p></entry> |
|
206 <entry><p>LIB</p></entry> |
|
207 </row> |
|
208 <row> |
|
209 <entry><p>Makefile</p></entry> |
|
210 <entry><p>MMP file</p></entry> |
|
211 </row> |
|
212 <row> |
|
213 <entry><p>SOURCES of Makefile </p></entry> |
|
214 <entry><p>SOURCE of the MMP file </p></entry> |
|
215 </row> |
|
216 <row> |
|
217 <entry><p><filepath>/usr/include/</filepath></p></entry> |
|
218 <entry><p><filepath>\EPOC32\INCLUDE</filepath></p></entry> |
|
219 </row> |
|
220 <row> |
|
221 <entry><p><filepath>/usr/lib/</filepath></p></entry> |
|
222 <entry><p><filepath>\epoc32\data\c\sys\bin</filepath> on an emulator, <filepath>\sys\bin</filepath> on |
|
223 a target device</p></entry> |
|
224 </row> |
|
225 </tbody> |
|
226 </tgroup> |
|
227 </table><p>The following table lists a few important things about the Symbian |
|
228 platform: </p><table id="GUID-A43D5623-C816-4308-9AFC-FCA97DA75A2D"> |
|
229 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/> |
|
230 <tbody> |
|
231 <row> |
|
232 <entry><p><codeph>ABI_DIR</codeph></p></entry> |
|
233 <entry><p>Platform, for example winscw or armv5</p></entry> |
|
234 </row> |
|
235 <row> |
|
236 <entry><p><codeph>BUILD_DIR</codeph></p></entry> |
|
237 <entry><p>UDEB or UREL</p></entry> |
|
238 </row> |
|
239 <row> |
|
240 <entry><p><filepath>c:</filepath> drive in emulator </p></entry> |
|
241 <entry><p><filepath>\epoc32\data\c</filepath> and <filepath>\epoc32\winscw\c</filepath></p></entry> |
|
242 </row> |
|
243 <row> |
|
244 <entry><p><filepath>z:</filepath> drive in emulator</p></entry> |
|
245 <entry><p><filepath>Z:\epoc32\data\z</filepath></p></entry> |
|
246 </row> |
|
247 <row> |
|
248 <entry><p><filepath>bld.inf</filepath></p></entry> |
|
249 <entry><p>Lists public header files and their location in <filepath>\EPOC32\INCLUDE</filepath></p></entry> |
|
250 </row> |
|
251 </tbody> |
|
252 </tgroup> |
|
253 </table> </section> |
|
254 </conbody></concept> |