Start on documentation for Qt for Symbian development in Qt Creator

doc/qtcreator.qdoc

@@ -19,30 +19,6 @@
     {qt-creator-request@trolltech.com}. For more information on Qt mailing
     lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.
 
-    Qt Creator includes a wide range of useful features. Among them are:
-    \list 1
-        \o \bold{Smart Code Editor}: The code editor provides syntax
-            highlighting as well as code completion.
-        \o \bold{Qt4 Project Generating Wizard}: This wizard allows the user
-           to generate a project for a console application, a GUI application,
-           or a C++ library.
-        \o \bold{Qt Help Integration}: Qt's entire documentation can be
-           accessed easily by clicking on the \gui{Help} button.
-        \o \bold{Qt Designer Integration}: User interface forms can be designed
-           within Qt Creator. Simply double-click on a \c{.ui} file within the
-           \gui{Project Explorer} to launch the integration.
-        \o \bold{Locator}: A powerful navigation tool that lets the user locate
-           files and classes using minimal keystrokes.
-        \o \bold{Support for qmake's .pro file format}: The project's \c{.pro}
-           file is used as a project description file.
-        \o \bold{Debugging Interface}: Applications can be debugged
-           within Qt Creator using a graphical frontend to the GNU symbolic
-           debugger (GDB) and the Microsoft Console Debugger (CDB).
-    \endlist
-
-    To learn more about the Qt Creator, click on one of the links below:
-
-
     \raw HTML
     <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
     \endraw 
@@ -60,6 +36,7 @@
        \o   \l{Debugging with Qt Creator}
        \o   \l{CMake Support in Qt Creator}
        \o   \l{Support for Generic Projects in Qt Creator}
+       \o   \l{Development of Qt for Symbian Based Applications}
        \o   \l{Handling External Libraries}
        \o   \l{Tips and Tricks}
        \o   \l{Keyboard Shortcuts}
@@ -462,7 +439,7 @@
             \i \image qtcreator-qt4-qtversions-win-symbian.png
                If you are using Qt for Symbian and your S60 SDK is registered
                with \c devices.exe, Qt Creator will detect the Qt version automatically.
-               If this does not work, point Creator to \c qmake.exe of Qt for Symbian.
+               A known issue is that you cannot just point Creator to \c qmake.exe of Qt for Symbian.
                You can add the path to the Metrowerks Compiler (\gui {MWC Directory})
                if you want to use to build for the emulator. This requires Carbide 2.0
                to be installed. the MWC directory should then point to the directory 
@@ -1495,7 +1472,7 @@
     \contentspage index.html
     \previouspage creator-cmake-support.html
     \page creator-generic-projects.html
-    \nextpage creator-external-library-handling.html
+    \nextpage creator-qt-for-symbian.html
 
     \title Support for Generic Projects in Qt Creator
 
@@ -1554,10 +1531,151 @@
     \c{$BUILDDIR} which should work fine.
 */
 
-
 /*!
     \contentspage index.html
     \previouspage creator-generic-projects.html
+    \page creator-qt-for-symbian.html
+    \nextpage creator-external-library-handling.html
+
+    \title Development of Qt for Symbian Based Applications
+
+    Qt Creator 1.3 comes with preliminary support for development of
+    applications using Qt for the Symbian Platform.
+
+    \e{Note that this is highly experimental, and not intended for production use.
+    The primary aim is to allow Symbian developers to familiarize themselves with Qt Creator
+    and provide feedback that will help us improve Symbian support in future versions of
+    Qt Creator.}
+
+    Please provide us with feedback, using the mailing list or IRC, as described on the
+    \l{http://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.
+
+    \section2 Getting Started
+
+    You need the following software installed on your PC.
+    Only Windows development is supported.
+
+    \list
+        \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}
+            {S60 Platform SDK 3rd Edition FP1 or higher}
+        \o \l{http://www.forum.nokia.com/main/resources/technologies/openc_cpp/}
+            {Open C/C++ v1.6.0 or higher.} Install this to all S60 SDKs you plan to use Qt with.
+            This is included in the Qt for Symbian binary installers.
+        \o Either the GCCE Arm Toolchain that is included in the S60 Platform SDKs, or
+            RVCT 2.2 [build 686] or later (which is not available free of charge).
+            Your environment needs to find the compiler in the PATH.
+        \o Qt for Symbian 4.6.0, installed into the S60 SDKs you want to use.
+
+    \endlist
+
+    And for deploying and running applications on the device
+    \list
+        \o The Nokia USB drivers that come e.g. with PC Suite.
+        \o The \l{http://tools.ext.nokia.com/trk/}{App TRK} application for your device.
+    \endlist
+
+    Running Qt based applications on real devices requires the following packages to be installed on
+    your device. The packages can be found in the S60 SDK where you installed Open C/C++:
+    \list
+        \o nokia_plugin\\openc\\s60opencsis\\pips_s60_\<version\>.sis
+        \o nokia_plugin\\openc\\s60opencsis\\openc_ssl_s60_\<version\>.sis
+        \o nokia_plugin\\opencpp\\s60opencppsis\\stdcpp_s60_\<version\>.sis
+    \endlist
+
+    If you want to run your applications in the Symbian Emulator, you also need to install
+    Carbide.c++ v2.0.0 or higher.
+
+    \section2 Setting up Qt Creator
+
+    When you run Qt Creator after installing the S60 Platform SDK and Qt for Symbian,
+    the installed SDKs and their corresponding Qt versions are automatically detected.
+    For each detected S60 SDK with Qt, a special entry is made in the Qt Version Management settings
+    \gui{Tools -> Options... -> Qt4 -> Qt Versions}.
+
+    \e{Note that you must use one of these special Qt version entries for building projects
+    for the emulator or devices. You can not just point Qt Creator to the qmake executable
+    like you would do for a desktop version of Qt.}
+
+    \image qtcreator-qt4-qtversions-win-symbian.png
+
+    If you want to run your applications in the Symbian Emulator, you need to point Qt Creator
+    to the Metrowerks Compiler that you want to use, by setting the \gui{MWC Directory}
+    of the Qt version to the corresponding Carbide.c++ installation directory.
+
+    You can check what S60 SDKs and corresponding Qt versions are found in the
+    \gui{Tools -> Options... -> Qt4 -> S60 SDKs} preference page.
+    At the moment it is not possible to override the autodetected settings.
+
+    \image qtcreator-qt4-s60sdks.png
+
+    \section2 Setting up Your Project
+
+    After installing all the prerequisites and checking the setup in Qt Creator as described
+    above, you need to make some settings for your project.
+    \e{Note that the only supported build system for Qt for Symbian applications in Qt Creator
+    is qmake.}
+
+    \section3 Building your Project
+
+    Before you can build your project for the Symbian Platform you need to create build
+    configurations for it.
+    Open \gui{Projects mode} and make sure that your project is selected for editing in
+    \gui{Edit Project Settings for Project ...}. Add debug and release build configurations
+    for the Symbian target by selecting the corresponding Qt version from the build configuration
+    \gui{Add} menu.
+
+    \image qtcreator-symbian-add-buildconfiguration.png
+
+    The created build configurations default to using the GCCE tool chain. If you want to build
+    for the device using RVCT, or for the Symbian Emulator using WINSCW, change the tool chain in
+    the \gui{General} section of the build configuration settings (press the \gui{Show Details}
+    button first).
+
+    Now you can switch to building your project for the device by selecting one of the
+    new build configurations as the active configuration at the top of \gui{Projects mode}.
+
+    \image qtcreator-symbian-change-buildconfiguration.png
+
+    \section3 Running your Project on the Device
+
+    Similar to the build configuration setup for your project you need to create a run configuration
+    for running your project on a Symbian device. Add a new run configuration in \gui{Projects mode}
+    via \gui{Run Settings}, \gui{Add -> YourApplication on Symbian Device} button.
+
+    \image qtcreator-symbian-add-runconfiguration.png
+
+    \image qtcreator-symbian-details-runconfiguration.png
+
+    In the details of the run configuration you can specify a certificate to use, and
+    select one of the devices that you have currently attached to your computer.
+    The only connection mode supported at the moment is USB in \e{PC Suite} mode.
+    For actually running your application on the device, you need to set the device run configuration
+    as the active configuration at the top of \gui{Projects mode}.
+    Start the \gui{App TRK} application on your device and press the run button to create
+    a package for your application, deploy, install and run it automatically on your device.
+
+    \image qtcreator-symbian-change-runconfiguration.png
+
+    When something goes wrong check the following things:
+    \list
+        \o Is the device run configuration selected as the active run configuration?
+        \o Did you build your application with one of the special Qt versions created for the
+            S60 SDKs?
+        \o Is the device connected via USB in \e{PC Suite} mode?
+        \o Is App TRK running on the device, using the USB connection, and does it have status
+            \e{connected}?
+        \o Is your device detected and selected in the run configuration details?
+    \endlist
+
+    If neither of this helps to solve your problem, search the qt-creator@trolltech.com
+    mailinglist archives or provide feedback to us via the methods described on the
+    \l{http://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.
+
+*/
+
+/*!
+    \contentspage index.html
+    \previouspage creator-qt-for-symbian.html
     \page creator-external-library-handling.html
     \nextpage creator-tips.html