/****************************************************************************

**

** 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

*/