--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/platforms/wince-customization.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,264 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** 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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $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
+*/