From ea0f526ac3a7daef5d4ebff2373a01d4088e28c3 Mon Sep 17 00:00:00 2001 From: Alessandro Portale Date: Thu, 19 Nov 2009 20:33:01 +0100 Subject: Improved documentation Qt for the Symbian platform By Janne Anttila: - Switched links/references from 'S60' to 'Symbian' - Added collection page for Symbian specific documentation - Added page about application deployment for Symbian - Update supported compiler list for Symbian to more specific one - Added bullet about dev env. setup to Symbian installation page - Commented that SBSv2 is not offically supported by current S60 SDKs - Moved S60 3rd FP1 special patching note after SDK installation bullet - Recommedation to look into Qt quick start guide from Symbian Forum - Added Symbian bullet to known issues page and link to wiki - Added link to "state of support" document from symbian docs main page By aportale: - Rephrasing - More consistent naming of 'Qt for the Symbian platform' - Implementation of suggestions from other Nokians Reviewed-By: Janne Anttila --- doc/src/deployment/deployment.qdoc | 102 ++++++++++- doc/src/getting-started/installation.qdoc | 73 +++++--- doc/src/getting-started/known-issues.qdoc | 7 + doc/src/howtos/exceptionsafety.qdoc | 2 +- doc/src/platforms/compiler-notes.qdoc | 5 + doc/src/platforms/qt-embedded.qdoc | 9 +- doc/src/platforms/s60-introduction.qdoc | 152 ---------------- doc/src/platforms/supported-platforms.qdoc | 4 +- doc/src/platforms/symbian-exceptionsafety.qdoc | 2 +- doc/src/platforms/symbian-introduction.qdoc | 197 +++++++++++++++++++++ doc/src/platforms/winsystem.qdoc | 4 +- doc/src/qt4-intro.qdoc | 2 +- doc/src/snippets/code/doc_src_deployment.qdoc | 41 +++++ doc/src/snippets/code/doc_src_installation.qdoc | 7 + .../snippets/code/doc_src_s60-introduction.qdoc | 69 -------- .../code/doc_src_symbian-introduction.qdoc | 69 ++++++++ 16 files changed, 483 insertions(+), 262 deletions(-) delete mode 100644 doc/src/platforms/s60-introduction.qdoc create mode 100644 doc/src/platforms/symbian-introduction.qdoc delete mode 100644 doc/src/snippets/code/doc_src_s60-introduction.qdoc create mode 100644 doc/src/snippets/code/doc_src_symbian-introduction.qdoc diff --git a/doc/src/deployment/deployment.qdoc b/doc/src/deployment/deployment.qdoc index b5b1b9c..ea841f9 100644 --- a/doc/src/deployment/deployment.qdoc +++ b/doc/src/deployment/deployment.qdoc @@ -187,6 +187,7 @@ \o \l{Deploying an Application on Windows}{Qt for Windows} \o \l{Deploying an Application on Mac OS X}{Qt for Mac OS X} \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux} + \o \l{Deploying an Application on the Symbian platform}{Qt for the Symbian platform} \endlist \sa Installation {Platform-Specific Documentation} @@ -1492,8 +1493,101 @@ macdeployqt supports the following options: \list - \o -no-plugins: Skip plugin deployment - \o -dmg : Create a .dmg disk image - \o -no-strip : Don't run 'strip' on the binaries - \endlist + \o -no-plugins: Skip plugin deployment + \o -dmg : Create a .dmg disk image + \o -no-strip : Don't run 'strip' on the binaries + \endlist +*/ + +/*! + \page deployment-symbian.html + \contentspage Deploying Qt Applications + + \title Deploying an Application on the Symbian platform + + Applications are deployed to Symbian devices in signed \c .sis package files. + The \c .sis file content is controlled with \c .pkg files. The \c .pkg file contains a set + of instructions used by tools to produce a \c .sis file. \c qmake generates a + default \c .pkg file for your project. The \c .pkg file generated by \c qmake is typically + fully functional for testing purposes but when planning to deliver your application + to end-users some changes are needed. This document describes what changes are + typically needed and how to implement them. + + \section1 Static Linking + + Qt for the Symbian platform does currently not support static linking of + Qt libraries. + + \section1 Shared Libraries + + When deploying the application using the shared libraries approach we must ensure that the + Qt runtime is correctly redistributed along with the application executable, + and also that all Qt dependencies are redistributed along with the application. + + We will demonstrate these procedures in terms of deploying the \l {widgets/wiggly}{Wiggly} + application that is provided in Qt's examples directory. + + \section2 Building Qt as a Shared Library + + We assume that you already have installed Qt as a shared library, + in the \c C:\path\to\Qt directory which is the default when installing Qt for Symbian. + For more information on how to build Qt, see the \l {Installation} documentation. + + \section1 Shared Libraries + + After ensuring that Qt is built as a shared library, we can build + the \l {widgets/wiggly}{Wiggly} application. First, we + must go into the directory that contains the application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 55 + + To prepare the application for deployment we must ensure that the \c .pkg file generated by + \c qmake contains the relevant vendor information and embeds the necessary + dependencies to the application deployment file (\c .sis). The content of the generated \c .pkg + file can be controlled with the Symbian specific \c qmake \l DEPLOYMENT keyword extensions. + + First, we will change the vendor statement to something more meaningful. The application + vendor is visible to end-user during the installation. + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 56 + + Second we will tell the Symbian application installer that this application supports + only S60 5.0 based devices: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 57 + + You can find a list of platform and device indentification codes from + \l {http://wiki.forum.nokia.com/index.php/S60_Platform_and_device_identification_codes}{Forum Nokia Wiki}. + By default \c .pkg file generated by \c qmake adds support for all + S60 3rd edition FP1, S60 3rd edition FP2 and S60 5th edition devices. + + As a last step we will embed the Open C, Open C++ and Qt \c .sis files to the Wiggly + deployment file: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 58 + + By embedding all dependencies to the application deployment file, the + end-user does not need to download and install all dependencies separately. + The drawback of \c .sis embedding is that the application \c .sis file size becomes + big. To address these problems Forum Nokia is planning to release a smart installer + which will take care of downloading and installing the necessary dependencies + over-the-air. The expected availability of smart installer is 1Q 2010. + + Now we are ready to compile the application and create the application + deployment file. Run \c qmake to create Symbian specific makefiles, resources (\.rss) + and deployment packaging files (\c .pkg). And do build to create the + application binaries and resources. + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 59 + + If everything compiled and linked without any errors, we are now ready to create + an application installation file: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 60 + + If all binaries and dependencies were found, we should now have a self-signed + \c wiggly_release-gcce.sis ready to be installed on a device. For more information + about creating a \c .sis file and installing it to device see also + \l {The Symbian platform - Introduction to Qt#Installing your own applications}{here}. + */ diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc index c8e225c..1a5cd99 100644 --- a/doc/src/getting-started/installation.qdoc +++ b/doc/src/getting-started/installation.qdoc @@ -495,12 +495,12 @@ in the \l{Qt for Windows CE Requirements} document. */ /*! \page install-Symbian-installer.html -\title Installing Qt on the Symbian Platform from a Binary Package -\ingroup qts60 +\title Installing Qt on the Symbian platform from a Binary Package +\ingroup qtsymbian \brief How to install Qt on the Symbian platform from a binary package. -\note Qt for Symbian platform has some requirements that are given in more detail -in the \l{Qt for Symbian platform Requirements} document. +\note Qt for the Symbian platform has some requirements that are given in more detail +in the \l{Qt for the Symbian platform Requirements} document. \list 1 @@ -517,13 +517,16 @@ in the \l{Qt for Symbian platform Requirements} document. to try out. An excellent starting point is the "fluidlauncher" demo. To run the demo on a real device, you first have to install \c{qt.sis} and \c{fluidlauncher.sis} found in the Qt installation - directory. Begin by connecting your phone using the USB cable and - selecting "PC Suite mode". In Windows Explorer right click on the - \c{.sis} files and select "Install with Nokia Application Installer" + directory. Also, check if the device needs additional + \l{Qt for the Symbian platform Requirements}{requirements}. + Begin by connecting your device via USB cable to a computer that has + the \l{http://www.nokia.com/pcsuite}{Nokia PC Suite} installed. + On the device, select "PC Suite mode". In Windows Explorer right click + on the \c{.sis} files, select "Install with Nokia Application Installer" and follow the instructions. To run the demos and examples on the emulator, you need to build them first. - Open the "Qt for Symbian platform Command Prompt" from the Start menu and type: + Open the "Qt for the Symbian platform Command Prompt" from the Start menu and type: \snippet doc/src/snippets/code/doc_src_installation.qdoc 25 @@ -534,7 +537,7 @@ in the \l{Qt for Symbian platform Requirements} document. For more information about building and running Qt programs on the Symbian platform, - see \l{Symbian platform - Introduction to Qt}. + see \l{The Symbian platform - Introduction to Qt}. We hope you will enjoy using Qt. @@ -542,25 +545,40 @@ Symbian platform, */ /*! \page install-Symbian.html -\title Installing Qt on the Symbian Platform +\title Installing Qt on the Symbian platform \ingroup installation -\ingroup qts60 +\ingroup qtsymbian \brief How to install Qt on the Symbian platform. \note Qt for the Symbian platform has some requirements that are given in more detail -in the \l{Qt for Symbian Platform Requirements} document. +in the \l{Qt for the Symbian platform Requirements} document. \note \bold {This document describes how to install and configure Qt for the Symbian platform from scratch. If you are using pre-built binaries, follow the instructions given in the -\l{Installing Qt on the Symbian Platform from a Binary Package} document.} +\l{Installing Qt on the Symbian platform from a Binary Package} document.} \list 1 + \o Setup the development environment + + Make sure your Symbian development environment is correctly installed and + patched as explained in the \l{Qt for the Symbian platform Requirements} document. + + After you have finished the Symbian development environment setup, it is good + to verify that environment is functional for example by compiling one + of the pure Symbian examples for both emulator and HW. This can be done from + command prompt as follows: + + \snippet doc/src/snippets/code/doc_src_installation.qdoc 32 + + If all steps pass without errors your Symbian development environment is + very likely installed correctly. + \o Install Qt - Uncompress the package into the directory you want Qt installed, - e.g. \c{C:\Qt\%VERSION%}. + Uncompress the \l{http://qt.nokia.com/downloads}{downloaded} source package into the + directory you want Qt installed, e.g. \c{C:\Qt\%VERSION%}. \note Qt must be installed on the same drive as the Symbian SDK you are using, and the install path must not contain any spaces. @@ -589,10 +607,11 @@ If you are using pre-built binaries, follow the instructions given in the to build the tools using MinGW, and the libraries using abld. or \snippet doc/src/snippets/code/doc_src_installation.qdoc 31 - to build the tools using MinGW, and the libraries using sbsv2. + to build the tools using MinGW, and the libraries using SBSv2. - For other options, type \c{configure -help} to get a list of all available - options. + SBSv2 also known as a (\l{http://developer.symbian.org/wiki/index.php/Introduction_to_RAPTOR} {Raptor}) + is a next-generation Symbian build system. SBSv2 is not officially + supported by any of the S60 SDKs currently available from Forum Nokia. \o Build Qt @@ -631,7 +650,7 @@ If you are using pre-built binaries, follow the instructions given in the \snippet doc/src/snippets/code/doc_src_installation.qdoc 27 For more information about building and running Qt programs on the -Symbian platform, see \l{Symbian platform - Introduction to Qt}. + Symbian platform, see \l{The Symbian platform - Introduction to Qt}. We hope you will enjoy using Qt. @@ -666,7 +685,7 @@ Symbian platform, see \l{Symbian platform - Introduction to Qt}. \list \o \l{Qt for Embedded Linux Requirements} \o \l{Qt for Mac OS X Requirements} - \o \l{Qt for Symbian platform Requirements} + \o \l{Qt for the Symbian platform Requirements} \o \l{Qt for Windows CE Requirements} \o \l{Qt for Windows Requirements} \o \l{Qt for X11 Requirements} @@ -951,12 +970,12 @@ Symbian platform, see \l{Symbian platform - Introduction to Qt}. /*! \page requirements-symbian.html - \title Qt for Symbian Platform Requirements + \title Qt for the Symbian platform Requirements \ingroup installation \brief Setting up the Symbian platform environment for Qt. \previouspage General Qt Requirements - Qt for Symbian platform requires the following software installed on your development PC: + Qt for the Symbian platform requires the following software installed on your development PC: \list \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/carbide_cpp/}{Carbide.c++ v2.0.0 or higher} \list @@ -969,7 +988,11 @@ Symbian platform, see \l{Symbian platform - Introduction to Qt}. \o \bold{Note:} According to Symbian, version 5.6.1 build 638 is mandatory. Using later versions may result in unexplained errors. \endlist \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}. + \list + \o \bold{Note:} Users of \bold{S60 Platform SDK 3rd Edition FP1} also need special update. The update can be found + \l{http://pepper.troll.no/s60prereleases/patches/}{here}. + \endlist + \o \l{http://www.forum.nokia.com/main/resources/technologies/openc_cpp/}{Open C/C++ v1.6.0 or higher}. Install this to all Symbian SDKs you plan to use Qt with. \o Building Qt tools from scratch requires \l{http://www.mingw.org/}{MinGW 3.4.5 or higher}, or another windows compiler. \list @@ -987,8 +1010,8 @@ Symbian platform, see \l{Symbian platform - Introduction to Qt}. \o \c{nokia_plugin\opencpp\s60opencppsis\stdcpp_s60_.sis} \endlist - \note Users of \bold{S60 Platform SDK 3rd Edition FP1} also need special updates. The update can be found - \l{http://pepper.troll.no/s60prereleases/patches/}{here}. + We recommend you to take a look of \l{http://developer.symbian.org/wiki/index.php/Qt_Quick_Start}{Symbian Foundation - Qt Quick Start} + to get more information about how to setup the development environment. \sa {Known Issues in %VERSION%} */ diff --git a/doc/src/getting-started/known-issues.qdoc b/doc/src/getting-started/known-issues.qdoc index 5c8888d..3c92257 100644 --- a/doc/src/getting-started/known-issues.qdoc +++ b/doc/src/getting-started/known-issues.qdoc @@ -131,4 +131,11 @@ window will cause it to flash. This behavior has been reported to Apple (bug number 5827676). \endlist + + \section2 Symbian + + \list + \o Check known issues for Symbian at + \l{http://qt.gitorious.org/qt/pages/Qt460KnownIssues} {Known Issues Wiki}. + \endlist */ diff --git a/doc/src/howtos/exceptionsafety.qdoc b/doc/src/howtos/exceptionsafety.qdoc index fa1427b..2f561a0 100644 --- a/doc/src/howtos/exceptionsafety.qdoc +++ b/doc/src/howtos/exceptionsafety.qdoc @@ -147,7 +147,7 @@ \section2 The Symbian platform The Symbian platform implements its own exception system that differs from the standard - C++ mechanism. When using Qt for Symbian platform, and especially when writing code to + C++ mechanism. When using Qt for the Symbian platform, and especially when writing code to access Symbian functionality directly, it may be necessary to know about the underlying implementation and how it interacts with Qt. diff --git a/doc/src/platforms/compiler-notes.qdoc b/doc/src/platforms/compiler-notes.qdoc index 88e1e37..0ae32c3 100644 --- a/doc/src/platforms/compiler-notes.qdoc +++ b/doc/src/platforms/compiler-notes.qdoc @@ -303,4 +303,9 @@ Make sure you have the \l{http://www-1.ibm.com/support/search.wss?rs=32&tc=SSEP5D&dc=D400}{latest upgrades} installed. + + \section2 GCCE (Symbian) + + GCCE cannot be used to compile Qt libaries for the Symbian platform, but GCCE is supported + when compiling Qt applications for Symbian platform. */ diff --git a/doc/src/platforms/qt-embedded.qdoc b/doc/src/platforms/qt-embedded.qdoc index b38c94f..afed540 100644 --- a/doc/src/platforms/qt-embedded.qdoc +++ b/doc/src/platforms/qt-embedded.qdoc @@ -67,10 +67,9 @@ Applications use the appropriate style for the embedded environment and use native features, such as menus, to conform to the native style guidelines. - \o \l{Symbian Platform - Introduction to Qt}{Qt for the Symbian - platform} is used to create applications running in existing Symbian - platform environments. Applications use the appropriate style for the - embedded environment and use native features, such as menus, to conform - to the native style guidelines. + \o \l{Qt for the Symbian platform} is used to create applications running + in existing Symbian platform environments. Applications use the appropriate + style for the embedded environment and use native features, such as menus, + to conform to the native style guidelines. \endtable */ diff --git a/doc/src/platforms/s60-introduction.qdoc b/doc/src/platforms/s60-introduction.qdoc deleted file mode 100644 index 0581982..0000000 --- a/doc/src/platforms/s60-introduction.qdoc +++ /dev/null @@ -1,152 +0,0 @@ -/**************************************************************************** -** -** 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 symbian-with-qt-introduction.html - - \title Symbian Platform - Introduction to Qt - \brief An introduction to Qt for Symbian platform developers. - \ingroup howto - \ingroup qts60 - - \tableofcontents - - \section1 Required tools - - See \l{Qt for Symbian Platform Requirements} to see what tools are - required to use Qt for Symbian platform. - - \section1 Installing Qt and running demos - - Follow the instructions found in \l{Installing Qt on the Symbian platform from a Binary Package} - to learn how to install Qt using a binary package and how to build and run Qt demos. - - Follow the instructions found in \l{Installing Qt on the Symbian Platform} to learn how to install Qt using - using source package and how to build and run the Qt demos. - - \section1 Building your own applications - - If you are new to Qt development, have a look at \l{How to Learn Qt}. - In general, the difference between developing a - Qt application on the Symbian platform compared to any of the other platforms supported - by Qt is not that big. - - Once you have created a \c .pro file for your project, generate the - Carbide specific \c Bld.inf and \c .mmp files this way: - - \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 0 - - For more information on how to use qmake have a look at the \l - {qmake Tutorial}. - - Now you can build the Qt for the Symbian platform application with - standard build tools. By default, running \c make will produce binaries for - the emulator. However, the Symbian platform comes with several alternative - build targets, as shown in the table below: - - \table - \row \o \c debug-winscw \o Build debug binaries for the emulator (default). - It is currently not possible to build release - binaries for the emulator. - \row \o \c debug-gcce \o Build debug binaries for hardware using GCCE. - \row \o \c release-gcce \o Build release binaries for hardware using GCCE. - \row \o \c debug-armv5 \o Build debug binaries for hardware using RVCT. - \row \o \c release-armv5 \o Build release binaries for hardware using RVCT. - \row \o \c run \o Run the emulator binaries from the build directory. - \row \o \c sis \o Create signed \c .sis file for project. - \endtable - - The following lines perform a debug build for the emulator - and deploy all the needed files: - - \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 1 - - To work on your project in Carbide, simply import the \c .pro file - by right clicking on the project explorer and executing "Import...". - - \section1 Installing your own applications - - To install your own applications on hardware, you need signed \c .sis file. - The signed \c .sis file can be created with \c make \c sis target. \c sis target - is only supported for executables or projects with \c DEPLOYMENT statements. - By default the \c sis target will create signed \c .sis file for last build - target. For example, the following sequence will generate the needed makefiles, - build the project for \c debug-winscw and \c release-armv5, and create - self-signed \c .sis file for \c release-armv5 target: - - \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 2 - - If you want to use different certificate information or override the default - target for \c .sis file creation you can use the environment variables as - shown in the table below: - - \table - \row \o \c QT_SIS_OPTIONS \o Options accepted by \c .sis creation. - -i, install the package right away using PC suite. - -c=, read certificate information from a file. - Execute the \c{createpackage.pl} script without any - parameters for more information about options. - By default no otions are given. - \row \o \c QT_SIS_TARGET \o Target for which \c .sis file is created. - Accepted values are build targets listed in - previous table. By default last build target. - \row \o \c QT_SIS_CERTIFICATE \o The certificate file used for signing. - By default self-signed certificate. - \row \o \c QT_SIS_KEY \o The certificate's private key file. - By default key is associated to self-signed certificate. - \row \o \c QT_SIS_PASSPHRASE \o The certificate's private key file's passphrase. - By default empty. - \endtable - - For example: - - \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 4 - - The environment variables for \c make can also be given as parameters: - - \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 3 - - If you want to install the program immediately, make sure that the device - is connected to the computer in "PC Suite" mode, and run \c sis target - with the \c QT_SIS_OPTIONS=-i, like this: - - \snippet doc/src/snippets/code/doc_src_s60-introduction.qdoc 5 -*/ diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc index 1609b55..be098bc 100644 --- a/doc/src/platforms/supported-platforms.qdoc +++ b/doc/src/platforms/supported-platforms.qdoc @@ -89,8 +89,8 @@ \o gcc (\l{http://www.codesourcery.com/}{Codesourcery version)} \row \o Windows CE 5.0 (ARMv4i, x86, MIPS) \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii) - \row \o Symbian (S60 3.1, 3.2 and 5.0) - \o RVCT, GCCE, WINSCW + \row \o Symbian (Symbian/S60 3.1, 3.2 and 5.0) + \o RVCT 2.2 [build 686 or later], WINSCW 3.2.5 [build 482 or later], GCCE (for applications) \endtable \section1 Tier 2 Platforms diff --git a/doc/src/platforms/symbian-exceptionsafety.qdoc b/doc/src/platforms/symbian-exceptionsafety.qdoc index 88f4d03..99bd2d8 100644 --- a/doc/src/platforms/symbian-exceptionsafety.qdoc +++ b/doc/src/platforms/symbian-exceptionsafety.qdoc @@ -42,7 +42,7 @@ /*! \page symbianexceptionsafety.html \title Exception Safety with Symbian - \ingroup qts60 + \ingroup qtsymbian \brief A guide to integrating exception safety in Qt with Symbian. The following sections describe how Qt code can interoperate with Symbian's diff --git a/doc/src/platforms/symbian-introduction.qdoc b/doc/src/platforms/symbian-introduction.qdoc new file mode 100644 index 0000000..c0c4fb3 --- /dev/null +++ b/doc/src/platforms/symbian-introduction.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qtsymbian + \title Qt for the Symbian platform + \ingroup qt-embedded + \brief Documents related to Qt on the Symbian platform + + Qt for Symbian is a C++ framework for GUI and application development + for embedded devices running Symbian. Qt for Symbian provides all + functionality required to develop rich end-user applications for devices + running S60 3.1 and later. + + \table 100% + \header \o Getting Started \o Reference \o Development + \row + \o + \list + \o \l {Qt for the Symbian platform Requirements} + \o \l {Installing Qt on the Symbian platform from a Binary Package} + \o \l {Installing Qt on the Symbian platform} + \o \l {The Symbian platform - Introduction to Qt}{Introduction to using Qt} + \endlist + \o + \list + \o \l {Exception Safety with Symbian} + \o \l {Platform Notes - Symbian} {Qt for the Symbian platform - state of support} + \o \l {qmake Platform Notes#Symbian platform} {Qt for Symbian extensions for qmake} + \endlist + \o + \list + \o \l {Deploying an Application on the Symbian platform}{Deploying Applications} + \endlist + \endtable +*/ + +/*! + \page symbian-with-qt-introduction.html + + \title The Symbian platform - Introduction to Qt + \brief An introduction to Qt for the Symbian platform developers. + \ingroup howto + \ingroup qtsymbian + + \tableofcontents + + \section1 Required tools + + See \l{Qt for the Symbian platform Requirements} to see what tools are + required to use Qt for the Symbian platform. + + \section1 Installing Qt and running demos + + Follow the instructions found in \l{Installing Qt on the Symbian platform from a Binary Package} + to learn how to install Qt using a binary package and how to build and run Qt demos. + + Follow the instructions found in \l{Installing Qt on the Symbian platform} to learn how to install Qt using + using source package and how to build and run the Qt demos. + + \section1 Building your own applications + + If you are new to Qt development, have a look at \l{How to Learn Qt}. + In general, the difference between developing a + Qt application on the Symbian platform compared to any of the other platforms supported + by Qt is not that big. + + Once you have created a \c .pro file for your project, generate the + Symbian specific \c Bld.inf and \c .mmp files this way: + + \snippet doc/src/snippets/code/doc_src_symbian-introduction.qdoc 0 + + For more information on how to use qmake have a look at the \l + {qmake Tutorial}. + + Now you can build the Qt for the Symbian platform application with + standard build tools. By default, running \c make will produce binaries for + the emulator. However, the Symbian platform comes with several alternative + build targets, as shown in the table below: + + \table + \row \o \c debug-winscw \o Build debug binaries for the emulator (default). + It is currently not possible to build release + binaries for the emulator. + \row \o \c debug-gcce \o Build debug binaries for hardware using GCCE. + \row \o \c release-gcce \o Build release binaries for hardware using GCCE. + \row \o \c debug-armv5 \o Build debug binaries for hardware using RVCT. + \row \o \c release-armv5 \o Build release binaries for hardware using RVCT. + \row \o \c run \o Run the emulator binaries from the build directory. + \row \o \c sis \o Create signed \c .sis file for project. + \endtable + + The following lines perform a debug build for the emulator + and deploy all the needed files: + + \snippet doc/src/snippets/code/doc_src_symbian-introduction.qdoc 1 + + To work on your project in Carbide, simply import the \c .pro file + by right clicking on the project explorer and executing "Import...". + + \section1 Installing your own applications + + To install your own applications on hardware, you need a signed \c .sis file. + (Refer to the \l{http://developer.symbian.org/wiki/index.php/Platform_Security_%28Fundamentals_of_Symbian_C%2B%2B%29#Self-Signed_Applications} + {Platform Security Article} for more informations about self-signing.) + The signed \c .sis file can be created with \c make \c sis target. \c sis target + is only supported for executables or projects with \c DEPLOYMENT statements. + By default the \c sis target will create signed \c .sis file for last build + target. For example, the following sequence will generate the needed makefiles, + build the project for \c debug-winscw and \c release-armv5, and create + self-signed \c .sis file for \c release-armv5 target: + + \snippet doc/src/snippets/code/doc_src_symbian-introduction.qdoc 2 + + If you want to use different certificate information or override the default + target for \c .sis file creation you can use the environment variables as + shown in the table below: + + \table + \row \o \c QT_SIS_OPTIONS \o Options accepted by \c .sis creation. See + \l{Supported options for QT_SIS_OPTIONS}{Supported options} + below. By default no otions are given. + \row \o \c QT_SIS_TARGET \o Target for which \c .sis file is created. + Accepted values are build targets listed in + previous table. By default last build target. + \row \o \c QT_SIS_CERTIFICATE \o The certificate file used for signing. + By default self-signed certificate. + \row \o \c QT_SIS_KEY \o The certificate's private key file. + By default key is associated to self-signed certificate. + \row \o \c QT_SIS_PASSPHRASE \o The certificate's private key file's passphrase. + By default empty. + \endtable + + The suppported options for \c QT_SIS_OPTIONS: + + \target Supported options for QT_SIS_OPTIONS + \table + \row \o -i \o Install the package right away using PC suite. + \row \o -p \o Only preprocess the template \c .pkg file. + \row \o -c= \o Read certificate information from a file. + \endtable + + Execute the \c{createpackage.pl} script without any + parameters for detailed information about options. By default no otions are given. + + For example: + + \snippet doc/src/snippets/code/doc_src_symbian-introduction.qdoc 4 + + The environment variables for \c make can also be given as parameters: + + \snippet doc/src/snippets/code/doc_src_symbian-introduction.qdoc 3 + + If you want to install the program immediately, make sure that the device + is connected to the computer in "PC Suite" mode, and run \c sis target + with the \c QT_SIS_OPTIONS=-i, like this: + + \snippet doc/src/snippets/code/doc_src_symbian-introduction.qdoc 5 +*/ diff --git a/doc/src/platforms/winsystem.qdoc b/doc/src/platforms/winsystem.qdoc index 72e7da6..2f43a74 100644 --- a/doc/src/platforms/winsystem.qdoc +++ b/doc/src/platforms/winsystem.qdoc @@ -102,9 +102,9 @@ When compiling for this platform, the macro \c{Q_WS_WINCE} is defined. See the \l{Qt for Windows CE} documentation for more information. - \section1 Qt for Symbian Platform + \section1 Qt for the Symbian platform When compiling for this platform, the macro \c{Q_WS_S60} is defined. - See the \l{Symbian Platform - Introduction to Qt} documentation for + See the \l{The Symbian platform - Introduction to Qt} documentation for more information. */ diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index 2a1f8ff..fb1d0e4 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -491,7 +491,7 @@ rich end-user applications for devices running S60 3.1 and later. - See the \l{Symbian Platform - Introduction to Qt} for more information. + See the \l{The Symbian platform - Introduction to Qt} for more information. \section1 Animation Framework diff --git a/doc/src/snippets/code/doc_src_deployment.qdoc b/doc/src/snippets/code/doc_src_deployment.qdoc index d233ec3..2d6a78f 100644 --- a/doc/src/snippets/code/doc_src_deployment.qdoc +++ b/doc/src/snippets/code/doc_src_deployment.qdoc @@ -453,3 +453,44 @@ CONFIG+=x86 ppc //! [54] qApp->addLibraryPath("C:/customPath/plugins"); //! [54] + +//! [55] +cd examples\widgets\wiggly +//! [55] + +//! [56] +vendorinfo = \ + "%{\"Example Localized Vendor\"}" \ + ":\"Example Vendor\"" + +default_deployment.pkg_prerules = vendorinfo +//! [56] + +//! [57] +supported_platforms = \ + "; This demo only supports S60 5.0" \ + "[0x1028315F],0,0,0,{\"S60ProductID\"}" + +default_deployment.pkg_prerules += supported_platforms +//! [57] + +//! [58] +embedded_deployments = \ + "; Embed Open C dependencies" \ + "@\"$${EPOCROOT}nokia_plugin/openc/s60opencsis/pips_s60_1_6_SS.sis\",(0x20013851)" \ + "@\"$${EPOCROOT}nokia_plugin/openc/s60opencsis/openc_ssl_s60_1_6_SS.sis\",(0x200110CB)" \ + "@\"$${EPOCROOT}nokia_plugin/opencpp/s60opencppsis/STDCPP_s60_1_6_SS.sis\",(0x2000F866)" \ + "; Embed Qt dependencies" \ + "@\"$$[QT_INSTALL_PREFIX]/qt_rndsigned.sis\",(0x2001E61C)" + +default_deployment.pkg_prerules += embedded_deployments +//! [58] + +//! [59] +qmake +make release-gcce +//! [59] + +//! [60] +make sis +//! [60] \ No newline at end of file diff --git a/doc/src/snippets/code/doc_src_installation.qdoc b/doc/src/snippets/code/doc_src_installation.qdoc index 68765ec..3563a64 100644 --- a/doc/src/snippets/code/doc_src_installation.qdoc +++ b/doc/src/snippets/code/doc_src_installation.qdoc @@ -209,3 +209,10 @@ make sis QT_SIS_OPTIONS=-i cd \Qt\%VERSION% configure -platform win32-g++ -xplatform symbian-sbsv2 //! [31] + +//! [32] +cd \S60CppExamples\Note\group +bldmake bldfiles +abld build winscw udeb +abld build gcce urel +//! [32] diff --git a/doc/src/snippets/code/doc_src_s60-introduction.qdoc b/doc/src/snippets/code/doc_src_s60-introduction.qdoc deleted file mode 100644 index 8949df6..0000000 --- a/doc/src/snippets/code/doc_src_s60-introduction.qdoc +++ /dev/null @@ -1,69 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -//! [0] - qmake -//! [0] - - -//! [1] - make debug-winscw -//! [1] - -//! [2] - qmake - make debug-winscw release-armv5 - make sis -//! [2] - -//! [3] - make sis QT_SIS_TARGET=debug-armv5 -//! [3] - -//! [4] - set QT_SIS_TARGET=debug-armv5 - make sis -//! [4] - -//! [5] - set QT_SIS_OPTIONS=-i - make sis -//! [5] diff --git a/doc/src/snippets/code/doc_src_symbian-introduction.qdoc b/doc/src/snippets/code/doc_src_symbian-introduction.qdoc new file mode 100644 index 0000000..8949df6 --- /dev/null +++ b/doc/src/snippets/code/doc_src_symbian-introduction.qdoc @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +//! [0] + qmake +//! [0] + + +//! [1] + make debug-winscw +//! [1] + +//! [2] + qmake + make debug-winscw release-armv5 + make sis +//! [2] + +//! [3] + make sis QT_SIS_TARGET=debug-armv5 +//! [3] + +//! [4] + set QT_SIS_TARGET=debug-armv5 + make sis +//! [4] + +//! [5] + set QT_SIS_OPTIONS=-i + make sis +//! [5] -- cgit v0.12