diff options
Diffstat (limited to 'doc/src/platforms/wince-customization.qdoc')
| -rw-r--r-- | doc/src/platforms/wince-customization.qdoc | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/doc/src/platforms/wince-customization.qdoc b/doc/src/platforms/wince-customization.qdoc new file mode 100644 index 0000000..06de1c8 --- /dev/null +++ b/doc/src/platforms/wince-customization.qdoc @@ -0,0 +1,264 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page windowsce-customization.html + \ingroup qtce + \title Windows CE - Working with Custom SDKs + \brief How to set up Qt for use with custom Windows CE SDKs. + + When working with a custom SDK for Windows CE, Qt provides an easy way + to add support for it to your development environment. The following is + a tutorial that covers how to create a specification for Qt on Windows + CE platforms. + + \tableofcontents + + \section1 Creating a Custom Build Specification + + Create a subdirectory in the \c mkspecs folder of the Qt directory. + New specifications for Qt for Windows CE following this naming convention: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 0 + + Using this convention makes it possible for \l{qmake} to identify that + you are building Qt for Windows CE, and will customize the compilation + process accordingly. + + Create the files \c qmake.conf and \c qplatformdefs.h inside the new + specification directory. Take a look at the implementation of the other + Windows CE specifications included in the \c mkspecs directory to see + what is required to build Qt for Windows CE successfully. + + + \section1 Fine-Tuning Options + + Compared to the desktop versions, Qt for Windows CE needs two additional + options: + + \list + \o \bold{CE_SDK} specifies the name of the SDK. + \o \bold{CE_ARCH} specifies information about the target architecture. + \endlist + + Following is an example configuration for the Windows Mobile 5 for + Pocket PC SDK: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 1 + + \note \l{qmake} uses this information to build a valid Visual Studio + project file. You need to ensure that they are identical to the + configuration of the custom SDK, otherwise you might not be able to compile + or debug your project with Visual Studio. + + Additionally, most Windows CE SDKs use extra compiler options. These + can be specified by expanding the \c DEFINES value. + + For example, with Windows Mobile 5 for Pocket PC, the \c DEFINES variable + is expanded in the following way: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 2 + + The mkspec may require additional configuration to be used inside of Visual + Studio, depending on the Windows CE SDK. The above example defines + \c _M_ARM. This definition is available internally in Visual Studio. Hence, + the compiler will warn you about redefinition during the build step. These + warnings can be disabled by adding a \c default_post.prf file containing + the following lines, within the subdirectory. + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 8 + + + \section1 Cross-compilation Environment for a Custom SDK + + Qt for Windows CE supports a convenience script, \c{setcepaths.bat}, that + prepares the environment in a command prompt for cross-compilation. + However, on custom SDKs, the \c checksdk tool is provided to identify the + environment, so Qt compiles successfully. + + \c checksdk is generated during the \c configure step and allows for the + following options: + + \list + \o \c list: Returns a list of available Windows CE SDKs. (This list + may contain one or more SDKs not supported on Qt for Windows CE, + e.g., Pocket PC 2003.) + \o \c sdk: The parameter to specify an SDK. Returns a setup of + environment variables that must be set to cross-compile Qt. + \o \c script: Stores your setup in a \c{.bat} file. This simplifies + the process of switching environments when you load a command + prompt in future. + \endlist + + + \section1 Compiling Qt for a Custom SDK + + Windows CE is highly customizable, hence it is possible that some SDKs have + feature-stripped setups. Depending on the SDK's configuration, Qt may not + compile in its standard configuration, as Qt for Windows CE is designed to + be compatible with the Standard SDK setup. + + However, it is possible to exclude features of Qt and create a version that + compiles for the desired SDK. + + Further information on stripping features can be found in the + \l{Fine-Tuning Features in Qt}{QFeatures} documentation. + + + \section1 Making Qt Applications Start on a Custom Device + + Sometimes, a Windows CE device has been created with a configuration + different from the corresponding SDK's configuration. In this case, symbols + that were available at linking stage will be missing from the run-time + libraries. + + Unfortunately, the operating system will not provide an error message that + mentions which symbols are absent. Instead, a message box with the following + message will appear: + + \c{app.exe is not a valid CE application!} + + To identify the missing symbols, you need to create a temporary + application that attempts to dynamically load the Qt for Windows CE + libraries using \c LoadLibrary. The following code can be used for this: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 9 + + Once you have compiled and deployed the application as well as the Qt + libraries, start a remote debugger. The debugger will then print the + ordinal number of the unresolved symbol. + + Search for parts of Qt that rely on these functions and disable them using + the \l{Fine-Tuning Features in Qt}{QFeatures} functionality. + + In our experience, when Qt applications do not start on Windows CE, it is + usually the result of missing symbols for the following classes or + features: + \list + \o \l{Drag and Drop} + \o \l{QClipboard} + \o \l{QCursor} + \endlist + + Please refer to the Microsoft documentation + \l{http://msdn.microsoft.com/en-us/library/e7tsx612.aspx}{here} for + information on what ordinals are and how you can create them. Information + on accessing the corresponding symbol name to a given ordinal value can + also be found in the Microsoft documentation. + +*/ + +/*! + \page shadow builds-wince.html + \ingroup qtce + \title Windows CE - Using shadow builds + \brief How to create a shadow build for Qt for Windows CE. + + \tableofcontents + + While developing for Windows CE you might want to compile a + version of Qt for several different platforms and SDKs. In order + to create those different builds of Qt you do not have to copy the + whole Qt package or the Qt source. You are able to create multiple + Qt builds from a single source tree. Such builds are called shadow + builds. + + Basically a shadow build is created by calling configure.exe from a + different directory. + + To make sure that the shadow build compiles correctly it is important + that you following these guidelines: + + \list + \o The original Qt source package must be left untouched - configure must + never have been run in the source tree directory. + + \o The shadow build directory must be on the same level as the Qt source + package.\br + If the Qt package is in \c{C:\Qt\%VERSION%} the shadow build directory + could be \c{C:\Qt\shadowbuild}. A shadow build from a directory like + \c{C:\shadowbuild} will not compile. + \o Avoid using "release" and "debug" in the path to the shadow build + directory. (This is an internal limitation of the build system.) + \o The \c{\bin} directory of the shadow build directory must be added to the + \c PATH environment variable. + \o Perl has been installed on your system. (\l{ActivePerl} is a popular + distribution of Perl on Windows.) + \endlist + + So lets assume you have installed Qt in \c{C:\Qt\%VERSION%} and you want + to create a shadow build in \c{C:\Qt\mobile5-shadow}: + + \list + \o First add \c{C:\Qt\mobile5-shadow\bin} to the \c PATH variable. + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 3 + + \o Make sure the enviroment variables for your compiler are set. + + Visual Studio includes \c{vcvars32.bat} for that purpose - or simply use + the "Visual Studio Command Prompt" from the Start menu. + + \o Now navigate to your shadow build directory and run configure: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 4 + + \o To build Qt, you have to update your \c{PATH, INCLUDE} and \c LIB paths + to point to your target platforms. + + For a default installation of the Windows Mobile 5.0 Pocket PC SDK, you + can do the following: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 5 + + We have provided a convenience script for this called \c{setcepaths}. Simply + type: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 6 + + \o Finally, to build the shadow build type: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 7 + + \o That's all. You have successfully created a shadow build of Qt in + \c{C:\Qt\mobile5-shadow}. + \endlist +*/ |