source: trunk/doc/src/platforms/wince-customization.qdoc@ 769

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** 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 have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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