Commit c9f0988e authored by Leena Miettinen's avatar Leena Miettinen
Browse files

Doc: move info about Symbian target to a separate folder

Change-Id: I93db9d03057f9f80a041447f41eefe98f8b4c41c
Reviewed-on: http://codereview.qt-project.org/5613

Reviewed-by: default avatarQt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: default avatarEike Ziller <eike.ziller@nokia.com>
Reviewed-by: default avatarCasper van Donderen <casper.vandonderen@nokia.com>
parent a91ba2b3
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.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 info@qt.nokia.com.
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\contentspage index.html
\previouspage creator-deployment.html
\page creator-deployment-symbian.html
\nextpage creator-deployment-maemo.html
\title Deploying Applications to Symbian Devices
This section describes how to create installation packages that meet the
requirements for installing applications to Symbian devices.
\section1 Creating SIS Files
When you deploy the application for the \gui{Symbian Device} target, \QC
automatically generates a Symbian installation system (SIS) file
in the project folder. You can deliver the installation file to users for
installation on Symbian devices.
The name of the installation file is displayed in the \gui {Installation file}
field in the \gui {Run Settings}. In the \gui {Installation drive} field, select the drive on the device
to install the application to. To suppress notifications on the device during the
installation, select the \gui {Silent installation} check box. If the silent
installation fails, \QC attempts installation again, this time displaying
notifications and error messages.
To create a SIS package without copying it to the device (for example, to submit it
to \e {Application Signing Services for Ovi Store} or \e {Symbian Signed}),
create a deploy configuration that contains only the
\gui {Create SIS Package} step.
\image qtcreator-run-settings-create.png "Create SIS Package step"
\section1 Signing SIS Files
Only installation files signed with a certificate and private key are
allowed to be installed onto Symbian devices. By default, \QC
self-signs the installation file. This self-signing allows you to install
the application on a mobile device but places limits on what you can do
with the installation file, including:
\list
\o Self-signed applications cannot access the more sensitive
\l{Capabilities and Signing}{capabilities} of the mobile device.
\o Security warnings will be displayed when you install the self-signed
application on a mobile device.
\o Self-signed applications cannot be published to Ovi
Store.
\endlist
To get around these limitations, you need to go through the Symbian Signed
or Application Signing Services for Ovi Store. The Symbian Signed organisation
manages a public key
infrastructure to provide public authentication of the information in the
application signing certificates. Their security partner can validate your
certificate and give you a Publisher ID. Then, when you sign an
application, other people can be confident that the information in your
certificate is correct and that the application does actually come from you.
Application Signing Services for Ovi Store is a variant of the Symbian
Signed certification provided by Ovi
Publishing. It is limited to the Basic and System capability sets
(Express Signing). Participants can submit an unsigned SIS file to Ovi
Publishing for signing. For more information about how
to participate, see
\l {http://www.developer.nokia.com/Community/Wiki/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store}.
There are also options that do not require you to get a Publisher ID. For
more detail about how the Symbian Signed process works, see
\l{https://www.symbiansigned.com}{Symbian Signed}.
When you have your own certificate and private key, you can specify them in
the \gui{Create SIS Package} step in the \gui {Run Settings}.
\image qtcreator-qt4-symbian-signing.png
If your private key is protected by a passphrase, \QC asks you for the
passphrase when the package is signed and offers to store it. However, storing
passphrases in \QC presents a security risk. To make \QC forget
all saved passphrases, click \gui {Reset Passphrases}.
\section2 Capabilities and Signing
Capabilities allow the Symbian platform to control access by applications to
the functionality provided by the platform APIs. Access to capabilities is
determined by the device configuration and how the application has been signed.
Symbian Signed offers the following signing options depending on the
capabilities that the application accesses:
\list
\o \bold{Express signed} for applications that access only user and system
capabilities.
\o \bold{Certified signed} for applications that access also restricted or
device manufacturer capabilities.
\note You need to request the rights to access device manufacturer
capabilities from the manufacturer.
\endlist
For more information about how to choose the appropriate signing option and
how you can check which capabilities you need, see
\l{https://www.symbiansigned.com}{Symbian Signed}
and
\l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.
For more information on how to define capabilities for a project, see
\l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.
\note In Qt 4.7.1 and later, if you select the \gui {Self-signed certificate}
option, the SIS generation process checks that the package can be self-signed.
If problems are found, it attempts to fix the package. If fixes cannot be made,
a message appears in the \gui {Compile Output} view.
The following modifications can be made:
\list
\o Package UID is changed to an UID from the unprotected range (if it was
from the protected range).
\o Vendor ID is set to zero on all binaries included in the package file.
\o All restricted and device manufacturer capabilities are removed from all
libraries included in the package file.
\endlist
The application UID or capabilities used in executables (.exe) cannot be changed,
because that would break the application. If the executables use protected UIDs
or restricted or device manufacturer capabilities, signing fails and an error
message appears in the \gui {Compile Output} view.
\section1 Creating Smart Installer for Symbian Packages
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^3 and later devices, some version of Qt
is pre-installed. On earlier devices, you must install the modules that Qt
applications require. Nokia Smart Installer for Symbian makes it easier
for users to install Qt applications to Symbian phones by checking whether the device contains
the necessary software and by installing the missing pieces.
For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
application SIS file must first be Symbian Signed or signed by the Application
Signing Services for Ovi Store. The capabilities used in the applications
determine, which signing option must be selected. The wrapper package must be signed using
either the same option or a more extensive option than the application SIS.
\note If you use the Application Signing Services for Ovi Store, you can submit an unsigned
wrapper package to Ovi Publishing. For more information, see
\l{Publishing Applications to Ovi Store}.
You can either install the Nokia Smart Installer for Symbian as part of
the \QSDK, or download and install it from the
\l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian}
wiki.
To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
package} check box. This ensures that up-to-date and appropriate versions of Qt and its
dependencies are installed on devices. Further, it reduces the file size of the application you
publish, because you do not have to deliver the required libraries.
Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian:
\list
\o 0xA000D7CE for self-signed applications
\o 0x2002CCCF for Ovi Store or Symbian Signed packages
\endlist
\section2 Creating Self-signed Smart Installer Packages
To create a self-signed Nokia Smart Installer for Symbian wrapped .sis file,
you must use an UID from the unprotected UID range, provided by Symbian Signed
and the wrapper package UID value 0xA000D7CE. If you used the \QC project
wizard to create the project, this wrapper package UID is used by default.
\list 1
\o Make sure that the source directory is clean. For example, if you use Git,
enter the following command:
\c {git clean -dfx}
\o Click \gui Projects to edit the \gui {Build Settings} for the
\gui {Symbian Device} target.
\o Select the \gui Release configuration.
\o Open the \gui {Run Settings}.
\o In the \gui {Create SIS Package} step, select \gui {Self-signed certificate}.
\o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
skip the step of copying the SIS file to a device. The SIS file is created
in the project folder.
\image qtcreator-remove-deploy-step.png "Removing deploy steps"
\o To package Nokia Smart Installer for Symbian with the application, select
the \gui {Create Smart Installer package} check box.
\o Edit the project .pro file to use the correct UIDs for the application and
the wrapper package, as illustrated by the following code snippet:
\code
symbian {
TARGET.UID3 = 0xE4DE5D27
DEPLOYMENT.installer_header=0xA000D7CE
vendorinfo = \
"%{\"CustomVendor-EN\"}" \
":\"CustomVendor\""
my_deployment.pkg_prerules = vendorinfo
DEPLOYMENT += my_deployment
}
\endcode
\o Choose \gui {Build > Run Project}.
\endlist
\QC automatically generates a wrapper package in the project folder.
\section2 Creating Symbian Signed Smart Installer Packages
If the application uses functions that require advanced capabilities (AllFiles,
DRM, TCB, CommDD, DiskAdmin, NetworkControl, MultimediaDD), you must use the
standard Symbian Signed process to have the application Symbian Signed. Depending
on the capabilities used, you may use either the Express Signed or the Certified
Signed path, or the manufacturer-specific channel (for AllFiles, DRM, and TCB).
\list 1
\o Make sure that the source directory is clean. For example, if you use Git,
enter the following command:
\c {git clean -dfx}
\o Click \gui Projects to edit the \gui {Build Settings} for the
\gui {Symbian Device} target.
\o Select the \gui Release configuration.
\o Open the \gui {Run Settings}.
\o In the \gui {Create SIS Package} step, specify the developer certificate
and key in the \gui {Custom certificate} and \gui {Key file} fields.
\o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
skip the step of copying the SIS file to a device. The SIS file is created
in the project folder.
\o Edit the project .pro file to use the correct UIDs and vendor information
for the application, as illustrated by the following code snippet:
\code
symbian {
TARGET.UID3 = 0x2000D7D1
DEPLOYMENT.installer_header=0x2002CCCF
vendorinfo = \
"%{\"CustomVendor-EN\"}" \
":\"CustomVendor\""
my_deployment.pkg_prerules = vendorinfo
DEPLOYMENT += my_deployment
}
\endcode
\o Choose \gui {Build > Run Project}.
\o Submit the created .sis file to Symbian Signed for certification.
\note Ensure that your application complies with the Symbian Signed
Test Criteria before submitting the file for certification. Also, if the file is
intended for Ovi Store publishing, verify that the application complies with Ovi
Store publishing requirements.
\o After receiving the .sis file from Symbian Signed, copy it over the old
application.sis.
\note The instructions below assume that you have installed \QSDK.
\o To package Nokia Smart Installer for Symbian with the application, choose
\gui {Start > Qt SDK > Symbian > Qt for Symbian Command Prompt}
to open the Qt command line environment.
\o Change to the project directory. For example:
\c{cd C:\Sources\Application}
\o To create a Smart Installer wrapper package, enter the following
command:
\c {C:\Sources\Application> make ok_installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key}
\o Submit the created wrapped .sis file, application_installer.sis, to
Symbian Signed. Express Signed is a suitable signing option for the wrapper
package. The capabilities used in the application do not play a role here,
because the wrapper package is already signed.
\endlist
\QC automatically generates a wrapper package in the project folder.
\note Ensure that your application complies with the requirements before submitting
the file to Ovi Store.
For more information about the qmake DEPLOYMENT variable, see
\l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#deployment}{qmake Variable Reference}.
For more information about the Nokia Smart Installer, see the
\l{http://doc.qt.nokia.com/smart-installer/index.html}{Nokia Smart Installer for Symbian Manual}.
Note: Nokia Smart Installer for Symbian is only available on Windows.
\section1 Application UID
A UID is a globally unique identifier that is used to
uniquely identify, for example, an object or file type. In Symbian development,
objects are identified by compound identifiers that are constructed from three
UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
object, whereas UID3 identifies a particular object, such as an application.
When you create a \gui {Mobile Qt Application}, \QC adds a UID3 suitable for
development and debugging automatically to the application .pro file. However, to
distribute your application and get it Symbian Signed, you must apply for a UID
from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
web site.
If you use the Ovi Signed process, Ovi Publisher Support allocates the UID for you.
Replace the testing UID with the distribution UID in the .pro file before you
build the final installation package. For more information, see
\l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
*/
\bold {On Symbian OS}: \c qDebug() and related functions use the native
\c RDebug::Print functionality.
When you use the Symbian emulator on Windows, the output is redirected to
standard debug output. To view it, you can use a Windows debug output
viewer, such as the DebugView for Windows.
On devices, the \c RDebug output is intercepted by \e CODA or \e {App TRK}
and then propagated to \QC, which displays it in the
\gui {Application Output} pane.
Symbian OS provides no support for differentiating between standard output
and error output.
\section1 Building 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. For more information,
see \l{Building with Remote Compiler}.
\section2 Troubleshooting Build Issues
If you cannot build the application for a Symbian device, check that:
\list
\o You selected the Symbian Device target to build the application.
\o You selected the correct Qt version to build the application.
For more information, see \l{Selecting Qt for Symbian Versions}.
\endlist
\section1 Building for Symbian Emulator
\QC does not create release configurations for the \gui {Symbian Emulator}
target, because Symbian Emulator supports only debug builds.
\section2 Setting Up Qt for Symbian Versions
If you install Qt for Symbian as a part of \QSDK, it is automatically
detected by \QC. If you install other Symbian SDKs and register them
with devices.exe, \QC automatically detects the Qt version.
If the selected Qt version was built using the SBSv2 build system, that
is available for Symbian OS 9.5 based SDKs, \QC builds your projects
using this build system. The \gui {SBS v2 directory} field is enabled and
you must specify the path to the directory where the SBS executable (for
example, sbs.bat on Windows) is located.
To add a Qt for Symbian version:
\list 1
\o Select \gui Tools > \gui Options > \gui Qt4 > \gui{Qt Versions}.
\o Select the Qt for Symbian version you want the \QC to use.
\image qtcreator-qt4-qtversions-win-symbian.png
For more information about how to add tool chains for using the
GCCE and WINSCW compilers, see \l{Adding Tool Chains}.
\o In the \gui {S60 SDK} field, enter the path to the directory where
the Symbian SDK is located.
\o In the \gui {SBS v2 directory} field, enter the path to the
directory where the SBS v2 executable is located.
\endlist
\section1 Running on Symbian
\list 1
\o Build and run the application for \l{Running on Qt Simulator}
{Qt Simulator}.
\o If no problems are found, build and run the application for a
device.
\o To test functionality that uses Symbian APIs, you can build and
run the application for Symbian Emulator.
\endlist
\section2 Running on a Device
\list 1
\o Install the required software on the device. For more information,
see \l{Connecting Symbian Devices}.
\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.
\note If you use CODA over an USB connection, it starts up
automatically when you connect the device to the development PC.
\o Click the \gui Run button.
\endlist
You can connect several devices to your development PC simultaneously.
In the details of the run configuration for the \gui{Symbian Device} target,
select the device to run your application on.
When your application is ready for delivery to users, specify run settings
for creating the final SIS installation packages. For more information,
see \l{Creating SIS Files}.
If you cannot run the application on a device, check that:
\list
\o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
have been installed on the development PC.
\o The device is connected through USB cable in \e{PC Suite} mode.
\o The CODA debugging agent is installed on the device and it is
running with the status \e connected.
\note If you use the CODA debugging agent over WLAN, you must enter
the WLAN address and port number in \QC, separated by a colon (:).
For example: 192.167.0.100:1534
\o The device is detected and selected in the \gui {Run Settings}.
\endlist
If this does not help to solve your problem, search the
qt-creator@trolltech.com mailing list archives or provide feedback to us via
the methods described on the
\l{http://developer.qt.nokia.com/wiki/Category:Tools::QtCreator}
{\QC Development Wiki}.
\section2 Running on Symbian Emulator
Select the \gui{Symbian Emulator} target as the active one, and build and
run your project.
If you cannot run the application in the emulator, check that:
\list
\o You selected the \gui{Symbian Emulator} target for your application.
\o If you cannot select \gui {Symbian Emulator} as target, check that
Carbide.c++ is installed correctly and that the path to the
Carbide.c++ installation directory is specified for the WINSCW tool
chain in the \gui{Compiler path} field in \gui {Tools > Options >
Tool Chains}.
\o If the emulator process cannot be started, try closing \QC and
starting the application directly from your file manager. Having
done this, \QC should be able to run your projects in the emulator.
\endlist
\section2 Specifying Run Settings for Symbian Devices
\QC automatically detects Symbian devices that are connected to the
development PC with a USB cable. If only one device is detected, the
application is deployed to it and run on it. If multiple devices are
connected to the PC, make sure that the correct device is selected in the
\gui {Symbian Device} run settings for your project.
You can also pass command line arguments to your application on the device.
Press the \gui{Device info button} to get more information about the
selected device, such as the CPU type and the running debugging agent
version.
\image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
To use the CODA debugging agent over a WLAN connection, enter the WLAN
address of the device and the port number to use, separated by a colon (:),
in the \gui WLAN field. For example: 192.167.0.100:1534
When you deploy the application for the \gui{Symbian Device} target, \QC
generates a Symbian installation system (SIS) file in the project folder
and copies it to the device that is connected to the development PC. If no
device is connected, you must remove the \gui {Deploy SIS Package} step,
to create the package. Click \gui {Remove Item} to skip the step.
\image qtcreator-remove-deploy-step.png "Removing deploy steps"
When you are ready to publish the application on Ovi Store or some other
channel, you must make sure that the SIS file meets the requirements for
publishing and installing applications on Symbian devices. For more
information, see \l{Deploying Applications to Symbian Devices}.
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.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 info@qt.nokia.com.
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\contentspage index.html
\previouspage creator-publish-ovi.html
\page creator-publish-ovi-symbian.html
\nextpage creator-publish-ovi-maemo.html
\title Publishing Qt Content for Symbian Devices
You can use the \e {Application Signing Services for Ovi Store} to get your
application Express Signed for free by Nokia. Make sure to use the
\l{Application UID}{application UID} that you receive from Ovi Publisher
Support.
The \gui {Publish Qt Symbian Applications to Ovi Store} wizard allows you
to check that your application can be published on Ovi Store. It checks that
the application UID, vendor name, and the capabilities used meet the Ovi
Publishing criteria.