/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@nokia.com)
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/

/*!
    \contentspage index.html
    \if defined(qcmanual)
    \previouspage creator-developing-maemo.html
    \else
    \previouspage sdk-gs.html
    \endif
    \page creator-developing-symbian.html
    \if defined(qcmanual)
    \nextpage creator-build-process-customizing.html
    \else
    \nextpage creator-developing-meego.html
    \endif

    \title Connecting Symbian Devices

    When you install \QSDK, the build and run settings for Symbian devices
    are set up automatically in \QC. You only need to install and launch
    the \l{Using On-device Debugging Agents}{CODA on-device debugging agent}
    on the devices and connect the devices to the development PC.

    Make sure that \l{http://www.nokia.com/ovisuite}{Ovi Suite} or
    \l{http://www.nokia.com/pcsuite}{PC Suite} is installed on the development PC.
    Connect the device to the development PC with an USB cable in
    Ovi Suite or PC Suite Mode. This setting is in the device USB settings.
    If you have not previously used the device with Ovi Suite
    or PC Suite, all the necessary drivers are installed automatically.
    This takes approximately one minute.

    You can run Qt applications on Symbian devices if the software that Qt
    applications require (typically Qt, Qt Mobility, QtWebkit, and Open C) is
    installed on the device. On Symbian Anna and later devices, some version of Qt
    is pre-installed. For more information, see
    \l{http://developer.qt.nokia.com/wiki/Support_for_Symbian#4ebe3e7733f9c23c76ac25559fc814a1}
    {Device Configurations}.

    To deploy applications to earlier devices, you can package
    the application with Nokia Smart Installer for Symbian to automatically
    install the modules that Qt applications require. For more information about
    which Qt modules are supported on-demand for different Symbian device
    models, see
    \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}
    {Nokia Smart Installer for Symbian}.

    The tool chain for building applications locally on the development PC for
    the \gui {Symbian Device} target is only supported on Windows.
    If you develop on Linux or Mac OS, you must use the Remote Compiler
    interface to a compilation service at Nokia Developer. You can install
    Remote Compiler as part of the \QSDK. For more information, see
    \if defined(qcmanual)
    \l{Building with Remote Compiler}.
    \else
    \l{http://doc.qt.nokia.com/qtcreator/creator-remote-compiler.html}
    {Building with Remote Compiler}.
    \endif


    For more information about developing applications for the Symbian
    platform, select \gui {Help > Index} and look for \gui {Platform Notes},
    or see
    \l{http://doc.qt.nokia.com/4.8/platform-notes-symbian.html}
    {Platform Notes - Symbian}.

    \section1 Using On-device Debugging Agents

    To run and debug applications on Symbian devices from \QC, you must
    install the CODA on-device debugging agent on the device.

    Support for the App TRK on-device debugging agent has been removed from
    \QC 2.3. Only CODA is supported Qt SDK 1.1.3 onward. It offers the following
    benefits:

    \list

        \o  Extensive error information

        \o  Debugging over WLAN

        \o  Extensive information about the device

    \endlist

    \note CODA does not support debugging over a Bluetooth connection.

    \section2 Installing Debugging Agents

    The CODA installation package is delivered together with \QSDK. You can
    find it in the \QSDK installation folder in the
    \c{\Symbian\sis\<target>\CODA} folder. On Windows, you can use \gui Start
    menu commands to install CODA on Symbian devices.

    \section1 Setting Up Qt Creator

    When you run \QC after installing the Symbian SDK and Qt for
    Symbian, the installed SDKs and their corresponding Qt versions are
    automatically detected. For each detected Symbian SDK with Qt, a special entry
    is made in the Qt version management settings in \gui{Tools} >
    \gui{Options} > \gui{Build & Run} > \gui{Qt Versions}.

    If you manually add a Qt version for Symbian, you must
    also manually specify the Symbian SDK to use for this version.

    For more information about adding Qt versions and tool chains, see
    \if defined(qcmanual)
    \l{Setting Up Qt for Symbian Versions} and \l{Adding Tool Chains}.
    \else
    \l{http://doc.qt.nokia.com/qtcreator/creator-project-qmake.html#setting-up-qt-for-symbian-versions}
    {Setting Up Qt for Symbian Versions} and
    \l{http://doc.qt.nokia.com/qtcreator/creator-tool-chains.html}
    {Adding Tool Chains}.
    \endif


    \section1 Building and Running Applications

    You can test your application on a device by building and running
    it from \QC for the \gui {Symbian Device} target.

    \list 1

        \o Connect the device to the development PC through a USB cable.
        The target selector displays a green check mark when a
        device is connected.

        \image qtcreator-qt4-symbian-device-connected.png

        The tool tip of the target selector shows more details about the actual
        device that will be used when you run your application.

        \o Start the CODA debugging agent on the device.

        \o Select \gui Options to select USB as connection type.

        \o Click \gui Projects to edit the \gui {Build Settings} for the
        \gui {Symbian Device} target. Select the Qt version to use for building
        the application. For more information, see
        \l{Selecting Qt for Symbian Versions}.

        \o Click the \gui Run button in \QC.

    \endlist

    \section2 Selecting Qt for Symbian Versions

    When you select the Qt for Symbian version to build the application with, consider
    which version provides the application with the widest support on different
    Symbian platforms. The binary compatibility promise of Qt and Symbian means
    that applications that are built against Qt 4.6.3 also run on Qt 4.7.3.
    Similarly, applications that are supported on S60 5th Edition are also
    supported
    on Symbian Anna and Belle. However, dependencies, such as Qt Quick or Qt Mobility API
    versions might restrict the choice of Qt versions that you have.

    If you use Qt Quick in the application, you can use \gui {S60 5th Edition
    Qt 4.7.3} to build it. The application is supported on both S60 5th Edition
    and Symbian Anna and Belle devices. However, if you only target Symbian
    Anna and Belle, you can use the state of art Qt in the \gui {Symbian Anna
    Qt 4.7.4} target to build the application. This allows you to re-use the
    application for MeeGo Harmattan devices.

    If you want to use the native Symbian Belle APIs and make sure that the
    application created for earlier Symbian platforms work on Belle as well,
    use \gui {Symbian Belle Qt 4.7.4} to build them. You cannot run such
    applications on Symbian Anna or earlier Symbian platforms.

    \note The \QSDK only contains the latest tool chains available for
    developing applications for a particular Symbian platform. The Qt 4.6.3 for
    Symbian and Qt 4.7.3 for Symbian^3 and Symbian Anna targets have been
    removed from \QSDK 1.1.4. To develop for those targets, use \QSDK 1.1.2.

    If you use native Symbian APIs, you must check that they are available on
    the target devices. For more information about the API differences between
    Symbian platforms, see the \bold {Symbian
    Reference Documentation for Qt}, which is delivered together with \QSDK
    and which you can view in the \gui Help mode.

    You can use a set of ready-made UI components called Qt Quick Components
    for Symbian that enforce a Nokia UI look and feel. \QSDK updates the Qt
    Quick Components to version 1.1 that contains usability and other
    improvements. All devices that support Qt Quick Components for Symbian
    support version 1.1.

    The following table summarizes the supported configurations for each Qt
    version available in \QC build settings:

    \table
        \header
            \o  Qt Version
            \o  Qt Quick
            \o  Qt Quick Components
            \o  Qt Mobility Version
            \o  Native Symbian C++ APIs
            \o  Qt OpenGL Support
        \row
            \o  S60 5th Edition Qt 4.7.3 (online installer only)
            \o  1.0
            \o  No
            \o  1.1.3
            \o  No
            \o  No
        \row
            \o  Symbian Anna Qt 4.7.4
            \o  1.1
            \o  1.1
            \o  1.2
            \o  Yes (Symbian Anna APIs)
            \o  Yes
        \row
            \o  Symbian Belle Qt 4.7.4 (online installer only)
            \o  1.1
            \o  1.1
            \o  1.2
            \o  Yes (Symbian Belle APIs)
            \o  Yes
    \endtable

    \section2 Developing Applications Using Qt 4.6.3 or Qt 4.7.3 for Symbian

    S60 3rd Edition devices support only Qt 4.6.3, not Qt 4.7 or later. Further,
    support for the App TRK on-device debugging agent has been removed from
    \QC 2.3. Only CODA is supported from Qt SDK 1.1.3 onward, and CODA does not
    support S60 3rd Edition. Therefore, you can no longer run and debug
    applications from \QC on S60 3rd Edition devices.

    The tool chains for developing applications using Qt 4.6.3 for Symbian
    and Qt 4.7.3 for Symbian^ 3 and Symbian Anna have been removed from \QSDK
    1.1.4. To develop such applications,
    \l{http://qt.nokia.com/downloads/downloads}
    {download and use \QSDK version 1.1.2} instead. It contains Qt 4.6.3 for
    Symbian and Qt 4.7.4 for Symbian support for Symbian devices with
    the Application TRK debug agent.

    \note Problems may arise if you install multiple instances of Qt SDK on the
    same development PC using the same user account. Use separate user accounts
    to install them or install them on separate development PCs.

    \note Do not update \QSDK 1.1.2 with the \QSDK update tool, because
    the updater removes App TRK support.

    In general, if you use only Qt 4.6 APIs in the application, you
    can use \gui {S60 5th Edition Qt 4.6.3} to build it. The application is
    supported on both S60 5th Edition and later devices.

    The following table summarizes the supported configurations for each Qt
    version available in \QC build settings if you installed \QSDK 1.1.2.

    \table
        \header
            \o  Qt Version
            \o  Qt Quick
            \o  Qt Quick Components
            \o  Qt Mobility Version
            \o  Native Symbian C++ APIs
            \o  Qt OpenGL Support
        \row
            \o  Qt 4.6.3 for Symbian^1 (S60 5th Edition)
            \o  No
            \o  No
            \o  1.0.2
            \o  No
            \o  No
        \row
            \o  Qt 4.6.3 for Symbian^3
            \o  No
            \o  No
            \o  1.0.2
            \o  Yes (Symbian^3 APIs)
            \o  No
        \row
            \o  Qt 4.7.3 for Symbian^3 and Symbian Anna
            \o  1.0
            \o  1.0
            \o  1.1.3
            \o  Yes (Symbian Anna APIs)
            \o  Yes
    \endtable

    \section1 Advanced Development with Symbian SDK

    For normal Qt application development, \QSDK provides all you need even if
    the application needs native Symbian OS API access.

    However, for more advanced Symbian application development, Nokia provides
    the \l{http://www.developer.nokia.com/carbide_cpp}{Carbide C++ IDE} and
    \l{http://www.developer.nokia.com/Resources/Tools_and_downloads/Other/Symbian_SDKs/}
    {Symbian C++ SDKs}. You can use them also for Qt application development.
    For example, these SDKs provide Symbian device emulators that are built
    mostly from the software that the actual devices are running. Therefore,
    they provide much closer emulation of the device than \QS.

*/
