|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \page windowsce-customization.html |
|
44 \ingroup qtce |
|
45 \title Windows CE - Working with Custom SDKs |
|
46 \brief How to set up Qt for use with custom Windows CE SDKs. |
|
47 |
|
48 When working with a custom SDK for Windows CE, Qt provides an easy way |
|
49 to add support for it to your development environment. The following is |
|
50 a tutorial that covers how to create a specification for Qt on Windows |
|
51 CE platforms. |
|
52 |
|
53 \tableofcontents |
|
54 |
|
55 \section1 Creating a Custom Build Specification |
|
56 |
|
57 Create a subdirectory in the \c mkspecs folder of the Qt directory. |
|
58 New specifications for Qt for Windows CE following this naming convention: |
|
59 |
|
60 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 0 |
|
61 |
|
62 Using this convention makes it possible for \l{qmake} to identify that |
|
63 you are building Qt for Windows CE, and will customize the compilation |
|
64 process accordingly. |
|
65 |
|
66 Create the files \c qmake.conf and \c qplatformdefs.h inside the new |
|
67 specification directory. Take a look at the implementation of the other |
|
68 Windows CE specifications included in the \c mkspecs directory to see |
|
69 what is required to build Qt for Windows CE successfully. |
|
70 |
|
71 |
|
72 \section1 Fine-Tuning Options |
|
73 |
|
74 Compared to the desktop versions, Qt for Windows CE needs two additional |
|
75 options: |
|
76 |
|
77 \list |
|
78 \o \bold{CE_SDK} specifies the name of the SDK. |
|
79 \o \bold{CE_ARCH} specifies information about the target architecture. |
|
80 \endlist |
|
81 |
|
82 Following is an example configuration for the Windows Mobile 5 for |
|
83 Pocket PC SDK: |
|
84 |
|
85 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 1 |
|
86 |
|
87 \note \l{qmake} uses this information to build a valid Visual Studio |
|
88 project file. You need to ensure that they are identical to the |
|
89 configuration of the custom SDK, otherwise you might not be able to compile |
|
90 or debug your project with Visual Studio. |
|
91 |
|
92 Additionally, most Windows CE SDKs use extra compiler options. These |
|
93 can be specified by expanding the \c DEFINES value. |
|
94 |
|
95 For example, with Windows Mobile 5 for Pocket PC, the \c DEFINES variable |
|
96 is expanded in the following way: |
|
97 |
|
98 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 2 |
|
99 |
|
100 The mkspec may require additional configuration to be used inside of Visual |
|
101 Studio, depending on the Windows CE SDK. The above example defines |
|
102 \c _M_ARM. This definition is available internally in Visual Studio. Hence, |
|
103 the compiler will warn you about redefinition during the build step. These |
|
104 warnings can be disabled by adding a \c default_post.prf file containing |
|
105 the following lines, within the subdirectory. |
|
106 |
|
107 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 8 |
|
108 |
|
109 |
|
110 \section1 Cross-compilation Environment for a Custom SDK |
|
111 |
|
112 Qt for Windows CE supports a convenience script, \c{setcepaths.bat}, that |
|
113 prepares the environment in a command prompt for cross-compilation. |
|
114 However, on custom SDKs, the \c checksdk tool is provided to identify the |
|
115 environment, so Qt compiles successfully. |
|
116 |
|
117 \c checksdk is generated during the \c configure step and allows for the |
|
118 following options: |
|
119 |
|
120 \list |
|
121 \o \c list: Returns a list of available Windows CE SDKs. (This list |
|
122 may contain one or more SDKs not supported on Qt for Windows CE, |
|
123 e.g., Pocket PC 2003.) |
|
124 \o \c sdk: The parameter to specify an SDK. Returns a setup of |
|
125 environment variables that must be set to cross-compile Qt. |
|
126 \o \c script: Stores your setup in a \c{.bat} file. This simplifies |
|
127 the process of switching environments when you load a command |
|
128 prompt in future. |
|
129 \endlist |
|
130 |
|
131 |
|
132 \section1 Compiling Qt for a Custom SDK |
|
133 |
|
134 Windows CE is highly customizable, hence it is possible that some SDKs have |
|
135 feature-stripped setups. Depending on the SDK's configuration, Qt may not |
|
136 compile in its standard configuration, as Qt for Windows CE is designed to |
|
137 be compatible with the Standard SDK setup. |
|
138 |
|
139 However, it is possible to exclude features of Qt and create a version that |
|
140 compiles for the desired SDK. |
|
141 |
|
142 Further information on stripping features can be found in the |
|
143 \l{Fine-Tuning Features in Qt}{QFeatures} documentation. |
|
144 |
|
145 |
|
146 \section1 Making Qt Applications Start on a Custom Device |
|
147 |
|
148 Sometimes, a Windows CE device has been created with a configuration |
|
149 different from the corresponding SDK's configuration. In this case, symbols |
|
150 that were available at linking stage will be missing from the run-time |
|
151 libraries. |
|
152 |
|
153 Unfortunately, the operating system will not provide an error message that |
|
154 mentions which symbols are absent. Instead, a message box with the following |
|
155 message will appear: |
|
156 |
|
157 \c{app.exe is not a valid CE application!} |
|
158 |
|
159 To identify the missing symbols, you need to create a temporary |
|
160 application that attempts to dynamically load the Qt for Windows CE |
|
161 libraries using \c LoadLibrary. The following code can be used for this: |
|
162 |
|
163 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 9 |
|
164 |
|
165 Once you have compiled and deployed the application as well as the Qt |
|
166 libraries, start a remote debugger. The debugger will then print the |
|
167 ordinal number of the unresolved symbol. |
|
168 |
|
169 Search for parts of Qt that rely on these functions and disable them using |
|
170 the \l{Fine-Tuning Features in Qt}{QFeatures} functionality. |
|
171 |
|
172 In our experience, when Qt applications do not start on Windows CE, it is |
|
173 usually the result of missing symbols for the following classes or |
|
174 features: |
|
175 \list |
|
176 \o \l{Drag and Drop} |
|
177 \o \l{QClipboard} |
|
178 \o \l{QCursor} |
|
179 \endlist |
|
180 |
|
181 Please refer to the Microsoft documentation |
|
182 \l{http://msdn.microsoft.com/en-us/library/e7tsx612.aspx}{here} for |
|
183 information on what ordinals are and how you can create them. Information |
|
184 on accessing the corresponding symbol name to a given ordinal value can |
|
185 also be found in the Microsoft documentation. |
|
186 |
|
187 */ |
|
188 |
|
189 /*! |
|
190 \page shadow builds-wince.html |
|
191 \ingroup qtce |
|
192 \title Windows CE - Using shadow builds |
|
193 \brief How to create a shadow build for Qt for Windows CE. |
|
194 |
|
195 \tableofcontents |
|
196 |
|
197 While developing for Windows CE you might want to compile a |
|
198 version of Qt for several different platforms and SDKs. In order |
|
199 to create those different builds of Qt you do not have to copy the |
|
200 whole Qt package or the Qt source. You are able to create multiple |
|
201 Qt builds from a single source tree. Such builds are called shadow |
|
202 builds. |
|
203 |
|
204 Basically a shadow build is created by calling configure.exe from a |
|
205 different directory. |
|
206 |
|
207 To make sure that the shadow build compiles correctly it is important |
|
208 that you following these guidelines: |
|
209 |
|
210 \list |
|
211 \o The original Qt source package must be left untouched - configure must |
|
212 never have been run in the source tree directory. |
|
213 |
|
214 \o The shadow build directory must be on the same level as the Qt source |
|
215 package.\br |
|
216 If the Qt package is in \c{C:\Qt\%VERSION%} the shadow build directory |
|
217 could be \c{C:\Qt\shadowbuild}. A shadow build from a directory like |
|
218 \c{C:\shadowbuild} will not compile. |
|
219 \o Avoid using "release" and "debug" in the path to the shadow build |
|
220 directory. (This is an internal limitation of the build system.) |
|
221 \o The \c{\bin} directory of the shadow build directory must be added to the |
|
222 \c PATH environment variable. |
|
223 \o Perl has been installed on your system. (\l{ActivePerl} is a popular |
|
224 distribution of Perl on Windows.) |
|
225 \endlist |
|
226 |
|
227 So lets assume you have installed Qt in \c{C:\Qt\%VERSION%} and you want |
|
228 to create a shadow build in \c{C:\Qt\mobile5-shadow}: |
|
229 |
|
230 \list |
|
231 \o First add \c{C:\Qt\mobile5-shadow\bin} to the \c PATH variable. |
|
232 |
|
233 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 3 |
|
234 |
|
235 \o Make sure the enviroment variables for your compiler are set. |
|
236 |
|
237 Visual Studio includes \c{vcvars32.bat} for that purpose - or simply use |
|
238 the "Visual Studio Command Prompt" from the Start menu. |
|
239 |
|
240 \o Now navigate to your shadow build directory and run configure: |
|
241 |
|
242 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 4 |
|
243 |
|
244 \o To build Qt, you have to update your \c{PATH, INCLUDE} and \c LIB paths |
|
245 to point to your target platforms. |
|
246 |
|
247 For a default installation of the Windows Mobile 5.0 Pocket PC SDK, you |
|
248 can do the following: |
|
249 |
|
250 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 5 |
|
251 |
|
252 We have provided a convenience script for this called \c{setcepaths}. Simply |
|
253 type: |
|
254 |
|
255 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 6 |
|
256 |
|
257 \o Finally, to build the shadow build type: |
|
258 |
|
259 \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 7 |
|
260 |
|
261 \o That's all. You have successfully created a shadow build of Qt in |
|
262 \c{C:\Qt\mobile5-shadow}. |
|
263 \endlist |
|
264 */ |