33 #if defined(WINS) |
33 #if defined(WINS) |
34 deffile GuiAppEngWINS.def |
34 deffile GuiAppEngWINS.def |
35 #else if defined(ARM) |
35 #else if defined(ARM) |
36 deffile GuiAppEngARM.def |
36 deffile GuiAppEngARM.def |
37 #endif |
37 #endif |
38 nostrictdef</codeblock> <p> The output file is <filepath>GUIAppEng.dll</filepath>, |
38 nostrictdef</codeblock> <p> The output file is <filepath>GUIAppEng.dll</filepath>, whose import library will be included by the UI. </p> |
39 whose import library will be included by the UI. </p> <p> |
39 <p> The first UID specified (<codeph>0x1000008d</codeph>) |
40 The first UID specified (<codeph>0x1000008d</codeph>) is the standard UID |
40 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 |
41 for an interface DLL. The second UID (<codeph>0x01100a02</codeph>) is |
41 and UI means that the definition of <codeph>crc()</codeph> in <filepath>crc.c</filepath> must be marked <codeph>EXPORT_C</codeph> because |
42 unique to the <filepath>GUIApp</filepath> project. </p> <p> |
42 this function will be exported from the engine's DLL. </p> |
43 Splitting the project into engine and UI means that the definition of |
43 <p> For more information on DLLs, see <xref href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita">DLLs</xref>. |
44 <codeph>crc()</codeph> in <filepath>crc.c</filepath> must be marked <codeph>EXPORT_C</codeph> |
44 </p> </section> |
45 because this function will be exported from the engine's DLL. </p> |
45 <section id="GUID-52000200-5CFD-4FE1-B80E-0A5F4C7E050D"> <title>Porting |
46 <p> For more information on DLLs, see <xref href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita">DLLs</xref>. |
46 checksum - the GUI app</title> <p> The implementation of checksum |
47 </p> </section> |
47 (<filepath>GUIApp.app</filepath>) limits the user to the selection |
48 <section id="GUID-52000200-5CFD-4FE1-B80E-0A5F4C7E050D"> <title>Porting checksum - the GUI app</title> <p> The implementation |
48 of a single file at a time and uses the default algorithm <codeph>crc()</codeph>, defined in <filepath>crc.c</filepath>, to produce |
49 of checksum (<filepath>GUIApp.app</filepath>) limits the user to the selection |
49 a 32-bit value. </p> <p> The user interface provides |
50 of a single file at a time and uses the default algorithm <codeph>crc()</codeph>, |
50 two main menu commands; <codeph>Calculate checksum</codeph> (invokes |
51 defined in <filepath>crc.c</filepath>, to produce a 32-bit value. </p> |
51 a file selection dialog) and <codeph>View checksums</codeph>. |
52 <p> The user interface provides two main menu commands; <codeph>Calculate |
52 When a file is selected and <codeph>OK</codeph> is pressed, the |
53 checksum</codeph> (invokes a file selection dialog) and <codeph>View |
53 selected file name is retrieved and opened as shown in the following |
54 checksums</codeph>. When a file is selected and <codeph>OK</codeph> is |
54 code: </p> <codeblock xml:space="preserve">const TUint16* fn = iFileName->PtrZ(); |
55 pressed, the selected file name is retrieved and opened as shown in the |
55 int fd = wopen( ( const wchar_t* )fn, O_RDONLY, 0 ); </codeblock> |
56 following code: </p> <codeblock xml:space="preserve">const TUint16* fn = iFileName->PtrZ(); |
56 <p> This code fragment is taken from <filepath>examples\stdlib\GUIApp.cpp.</filepath> </p> <p> <codeph>open()</codeph> returns a file descriptor |
57 int fd = wopen( ( const wchar_t* )fn, O_RDONLY, 0 ); </codeblock> <p> |
57 which the engine's <codeph>crc()</codeph> function uses to identify |
58 This code fragment is taken from <filepath>examples\stdlib\GUIApp.cpp.</filepath> |
58 the file. The checksum is calculated (unless an error occurred |
59 </p> <p> <codeph>open()</codeph> returns a file descriptor which |
59 in attempting to open or read the file), and is displayed. The |
60 the engine's <codeph>crc()</codeph> function uses to identify the file. |
60 file is closed. </p> <p> The file name and checksum |
61 The checksum is calculated (unless an error occurred in attempting to |
61 are appended to an array, the contents of which may be viewed |
62 open or read the file), and is displayed. The file is closed. </p> |
62 by selecting <codeph>View checksums</codeph>. </p> </section> |
63 <p> The file name and checksum are appended to an array, the contents |
63 <section id="SECTION_7A8BA355A42C45C3A14EDF1756AB1126"> <title>Linking to STDLIB - The project specification</title> <p> |
64 of which may be viewed by selecting <codeph>View checksums</codeph>. |
64 The application program includes several STDLIB header files, located |
65 </p> </section> |
65 in <filepath>\epoc32\include\libc\</filepath>. At link time, the |
66 <section id="SECTION_7A8BA355A42C45C3A14EDF1756AB1126"> <title>Linking |
66 program includes <filepath>estlib.lib</filepath> and the engine |
67 to STDLIB - The project specification</title> <p> The application |
67 DLL's <filepath>.lib</filepath> (<filepath>GUIAppEng.lib</filepath>). Unlike the previous examples, this application does not link |
68 program includes several STDLIB header files, located in <filepath>\epoc32\include\libc\</filepath>. |
68 to <filepath>ecrt0.lib</filepath>. In this application there is no |
69 At link time, the program includes <filepath>estlib.lib</filepath> and |
69 <codeph>main()</codeph> and the Symbian platform provides its |
70 the engine DLL's <filepath>.lib</filepath> (<filepath>GUIAppEng.lib</filepath>). |
70 own <codeph>E32Main()</codeph>. </p> </section> |
71 Unlike the previous examples, this application does not link to <filepath>ecrt0.lib</filepath>. |
|
72 In this application there is no <codeph>main()</codeph> and the Symbian |
|
73 platform provides its own <codeph>E32Main()</codeph>. </p> <p> |
|
74 For information on Symbian applications, their project specification, |
|
75 and resource files, see <xref href="GUID-81835322-5EF7-5839-9DC1-9A3FD396BD36.dita">How |
|
76 to build GUI applications</xref>. </p> </section> |
|
77 <section id="GUID-39A0C47A-38DC-4487-981D-D8BBC50D6DCF"> <title>Some potential issues</title> <ul id="UL_632D231449CE4474996ACD148CB9754D"> |
71 <section id="GUID-39A0C47A-38DC-4487-981D-D8BBC50D6DCF"> <title>Some potential issues</title> <ul id="UL_632D231449CE4474996ACD148CB9754D"> |
78 <li> <p><b>Removing writeable static</b></p> <p> The PETRAN stage |
72 <li> <p><b>Removing writeable static</b></p> <p> The PETRAN |
79 of building may report a message similar to the following: </p> |
73 stage of building may report a message similar to the following: |
80 <codeblock xml:space="preserve">WARNING: Dll 'SLSUMENG[0x01000a02].DLL' has initialised data.</codeblock> |
74 </p> <codeblock xml:space="preserve">WARNING: Dll 'SLSUMENG[0x01000a02].DLL' has initialised data.</codeblock> <p> This warning, which is not reported when building for |
81 <p> This warning, which is not reported when building for the Emulator, |
75 the Emulator, indicates that the DLL contains non-const static |
82 indicates that the DLL contains non-const static data. This is not allowed |
76 data. This is not allowed in ARM builds. If it is not obvious |
83 in ARM builds. If it is not obvious where the problem occurs, the associated |
77 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 |
84 <filepath>.map</filepath> file (<filepath>epoc32\release\<target>\urel\<dllname>.map</filepath>) |
78 file involved. A search for <codeph>from *(.bss)</codeph> (to |
85 contains information which can help to track down the source file involved. |
79 find uninitialised data) or <codeph>from *(.data)</codeph> (to |
86 A search for <codeph>from *(.bss)</codeph> (to find uninitialised data) |
80 find initialised data) in <filepath>GUIAPPEng.map</filepath> will |
87 or <codeph>from *(.data)</codeph> (to find initialised data) in <filepath>GUIAPPEng.map</filepath> will |
81 reveal the file in which the problem occurs, and the names of |
88 reveal the file in which the problem occurs, and the names of the offending |
82 the offending variables, although static variables will not be |
89 variables, although static variables will not be named. </p> </li> |
83 named. </p> </li> |
90 <li id="LI_BAD062FD16EC4CC8A11F13D0ACEE8378"><p><b>Include file clashes</b></p> <p> |
84 <li id="LI_BAD062FD16EC4CC8A11F13D0ACEE8378"><p><b>Include file clashes</b></p> <p> In C++ source files which use STDLIB routines, the Symbian |
91 In C++ source files which use STDLIB routines, the Symbian platform |
85 platform C++ include files must be included before any of the |
92 C++ include files must be included before any of the STDLIB files. Failure |
86 STDLIB files. Failure to do this will result in the following |
93 to do this will result in the following warning: </p> <codeblock xml:space="preserve">'NULL' : macro redefinition"</codeblock> </li> |
87 warning: </p> <codeblock xml:space="preserve">'NULL' : macro redefinition"</codeblock> </li> |
94 <li> <p><b>Mixing C and C++</b></p> <p> C and C++ have different views |
88 <li> <p><b>Mixing C and C++</b></p> <p> C and C++ have different |
95 about the names of functions. If you refer to a C function from C++, ensure |
89 views about the names of functions. If you refer to a C function |
96 that its prototype is declared as <codeph>extern "C"</codeph>. If there |
90 from C++, ensure that its prototype is declared as <codeph>extern |
97 are several such function declarations, it may be more convenient to enclose |
91 "C"</codeph>. If there are several such function declarations, it |
98 them within the following: </p> <codeblock xml:space="preserve">#ifdef __cplusplus |
92 may be more convenient to enclose them within the following: |
|
93 </p> <codeblock xml:space="preserve">#ifdef __cplusplus |
99 extern "C" |
94 extern "C" |
100 { |
95 { |
101 #endif |
96 #endif |
102 ... |
97 ... |
103 #ifdef __cplusplus |
98 #ifdef __cplusplus |
104 } |
99 } |
105 #endif</codeblock> <p> See for example <filepath>examples\stdlib\GUIApp\extern.h</filepath>. |
100 #endif</codeblock> <p> See for example <filepath>examples\stdlib\GUIApp\extern.h</filepath>. </p> </li> |
106 </p> </li> |
101 <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> |
107 <li id="LI_68EE8B3B25594B48864D5183BA8155AB"> <p><b>Stack usage</b></p> <p> |
102 <p> unless the amount of stack they use is reduced. Symbian |
108 Some programs produce the following error: </p> <codeblock xml:space="preserve">unresolved external symbol __chkstk</codeblock> |
103 threads have only 8k stack by default. </p> </li> |
109 <p> unless the amount of stack they use is reduced. Symbian threads |
104 <li> <p><b>Resource cleanup</b></p> <p> The Symbian platform has |
110 have only 8k stack by default. </p> </li> |
105 a requirement that all resources which were allocated by an application |
111 <li> <p><b>Resource cleanup</b></p> <p> The Symbian platform |
106 must be cleaned up by the time the program terminates. On the |
112 has a requirement that all resources which were allocated by an application |
107 Emulator, in debug builds, failure to do this will cause a panic |
113 must be cleaned up by the time the program terminates. On the Emulator, |
108 from the <codeph>__UHEAP_MARKEND</codeph> macro. </p> <p> Because the data allocated in the thread-local storage for STDLIB's |
114 in debug builds, failure to do this will cause a panic from the <codeph>__UHEAP_MARKEND</codeph> macro. |
109 DLL (the <codeph>_reent</codeph> structure) is not automatically |
115 </p> <p> Because the data allocated in the thread-local storage |
110 cleaned up when the environment is destroyed, it must be cleaned |
116 for STDLIB's DLL (the <codeph>_reent</codeph> structure) is not automatically |
111 up by the user of STDLIB. </p> <p> The function to achieve |
117 cleaned up when the environment is destroyed, it must be cleaned up by |
112 this is <codeph>CloseSTDLIB()</codeph>. To use this function, |
118 the user of STDLIB. </p> <p> The function to achieve this is <codeph>CloseSTDLIB()</codeph>. |
113 file <filepath>epoc32\include\libc\sys\reent.h</filepath> must be |
119 To use this function, file <filepath>epoc32\include\libc\sys\reent.h</filepath> must |
114 included in the project. Call <codeph>CloseSTDLIB()</codeph> after |
120 be included in the project. Call <codeph>CloseSTDLIB()</codeph> after |
115 the point at which it is known that code in STDLIB's DLL will |
121 the point at which it is known that code in STDLIB's DLL will no longer |
116 no longer be called and its thread-local storage no longer needed. |
122 be called and its thread-local storage no longer needed. </p> |
117 </p> <p> For example, see the destructor for <codeph>CExampleDocument</codeph> in <filepath>examples\stdlib\GUIApp\GUIApp.cpp</filepath>. </p> </li> |
123 <p> For example, see the destructor for <codeph>CExampleDocument</codeph> in |
|
124 <filepath>examples\stdlib\GUIApp\GUIApp.cpp</filepath>. </p> </li> |
|
125 </ul> </section> |
118 </ul> </section> |
126 </conbody><related-links> |
119 </conbody><related-links> |
127 <link href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita"><linktext>DLLs</linktext> |
120 <link href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita"><linktext>DLLs</linktext> |
128 </link> |
121 </link> |
129 <link href="GUID-81835322-5EF7-5839-9DC1-9A3FD396BD36.dita"><linktext>How to build |
|
130 GUI applications</linktext></link> |
|
131 </related-links></concept> |
122 </related-links></concept> |