← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/wince-customization.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/wince-customization.qdoc
1
 
/****************************************************************************
2
 
**
3
 
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4
 
** Contact: Nokia Corporation (qt-info@nokia.com)
5
 
**
6
 
** This file is part of the documentation of the Qt Toolkit.
7
 
**
8
 
** $QT_BEGIN_LICENSE:LGPL$
9
 
** Commercial Usage
10
 
** Licensees holding valid Qt Commercial licenses may use this file in
11
 
** accordance with the Qt Commercial License Agreement provided with the
12
 
** Software or, alternatively, in accordance with the terms contained in
13
 
** a written agreement between you and Nokia.
14
 
**
15
 
** GNU Lesser General Public License Usage
16
 
** Alternatively, this file may be used under the terms of the GNU Lesser
17
 
** General Public License version 2.1 as published by the Free Software
18
 
** Foundation and appearing in the file LICENSE.LGPL included in the
19
 
** packaging of this file.  Please review the following information to
20
 
** ensure the GNU Lesser General Public License version 2.1 requirements
21
 
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22
 
**
23
 
** In addition, as a special exception, Nokia gives you certain
24
 
** additional rights. These rights are described in the Nokia Qt LGPL
25
 
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26
 
** package.
27
 
**
28
 
** GNU General Public License Usage
29
 
** Alternatively, this file may be used under the terms of the GNU
30
 
** General Public License version 3.0 as published by the Free Software
31
 
** Foundation and appearing in the file LICENSE.GPL included in the
32
 
** packaging of this file.  Please review the following information to
33
 
** ensure the GNU General Public License version 3.0 requirements will be
34
 
** met: http://www.gnu.org/copyleft/gpl.html.
35
 
**
36
 
** If you are unsure which license is appropriate for your use, please
37
 
** contact the sales department at http://www.qtsoftware.com/contact.
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\4.5.2} 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\4.5.2} 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
 
*/