/*!

\contentspage{index.html}{Nokia Smart Installer for Symbian}

\page index.html

\title Nokia Smart Installer for Symbian Manual

\section1 Version 1.0.0

This document describes how you can use Nokia Smart Installer for Symbian

to package Qt based applications for Symbian devices.

\list

    \o \l{Introduction}

	\list

	    \o \l{Accessing the Internet}

	\endlist

    \o \l{Installing Dependencies and Applications}

	\list

	    \o \l{Disk Space Requirements}

	    \o \l{Installing Applications}

	    \o \l{Messages}

	\endlist

    \o \l{Packaging}

	\list

	    \o \l{Wrapper Package File}

	    \o \l{Signing Wrapper Packages}

	\endlist

\endlist

*/

/*!

\contentspage{index.html}

\page smartinstaller-introduction.html

\title Introduction

Nokia Smart Installer for Symbian

ensures that the installed 3rd party Qt applications have always access to the

required versions of their dependent libraries.

Smart Installer is split into two components: smartinstaller and smartinstaller

ADM (for application dependency manager). Smart Installer is a small component

that is embedded with the application into a wrapper package. It ensures that

a recent version of ADM is installed on the device and installs or upgrades ADM, if

necessary.

A network connection is

always required during installation. For a detailed description of network usage,

see \l{Accessing the Internet}.

Smart Installer is invoked during the application installation process on the

Symbian device. It immediately fetches the latest ADM from the server and runs

it. ADM checks whether the required components (dependencies) are already

installed on the device and downloads and installs or upgrades them, if needed.

Information about the application's dependencies is extracted from the

application .sis file, where each dependency is defined using the standard

dependency statements as defined in the pkg file format. For Qt, the

dependencies are automatically generated during the build process, but

developers can manually adjust them as well.

After the required dependencies have been successfully installed to the device,

the application installation process is invoked. This follows the normal UI flow

of application installation on a Symbian device.

*/

/*!

\contentspage{index.html}

\page smartinstaller-connectivity.html

\title Accessing the Internet

Nokia Smart Installer for Symbian tries to automatically select the appropriate

internet access point. If the access point cannot be determined automatically,

the user is prompted to select one. By default, Smart Installer uses the browser

access point settings to access the internet. If the installation is started

from the Ovi Store client, Smart Installer uses the access point used by the Ovi

Store. In addition, the size of the download package is displayed to the user.

Otherwise, no prompt is shown if WLAN is selected as the access point. For

packet data connections, the user is always informed about the download size.

Smart Installer downloads the required packages from a server provided by Nokia

at dl.qt.nokia.com. Because a data connection (such as WLAN, general packet

radio service (GPRS), EDGE, or 3G) is used, transmission fees may apply and

therefore, some costs may be incurred for the user.

If the required versions of Qt and the necessary components are already

installed on the device, the amount of data downloaded from the server is some

kilobytes (the latest ADM, if one is available, and a few dependency definition

files for the components involved). If all dependencies need to be installed,

the amount of data to download is currently about 12 MB. For a summary of

download package sizes, see \l{Disk Space Requirements}.

*/

/*!

\contentspage{index.html}

\page smartinstaller-installation.html

\title Installing Dependencies and Applications

The following sections describe in detail, how Nokia Smart Installer for Symbian

installs the dependencies and the application.

Due to performance reasons, the Qt libraries are always installed to the C:

drive of the device. Other packages can be installed to other drives. Therefore,

the minimum free space required on the C: drive is about 10 MB (up to 14 MB, if

QtWebkit and QtMobility are also needed). The free space requirements are larger

than the combined package download size, because the S60 application installer

temporarily requires some additional space. Smart Installer displays an error

message if there is not enough free space available on the device. For more

information, see \l{Messages}.

For other packages than Qt, Smart Installer chooses the next available drive if

drive C: becomes full. The user cannot control where the packages are going to

be installed. The process of determining the installation drive is automated to

minimize the need for user interaction.

*/

/*!

\contentspage{index.html}

\page smartinstaller-disk-space.html

\title Disk Space Requirements

The following table shows how much space each package consumes after

installation to the device at the time of publication.

The other packages except QtWebKit and QtMobility are the minimum set required

for a Qt application to run in a Symbian device. For example, even though the

Open C libraries are preinstalled in some Symbian devices it still needs to be

updated to v1.6, so these numbers are a fair estimate of the required space.

The table also describes the dependencies currently installed by Nokia Smart

Installer for Symbian. For an updated list, see

\l{http://wiki.forum.nokia.com/index.php/Nokia_Smart_Installer_for_Symbian#Packa

ges_distributed_by_Smart_Installer}{Packages Distributed by Smart Installer}.

\table

	\header

		\o Package Name

		\o UID

		\o Versions

		\o Download Size

		\o Space Required

		\o Description

	\row

		\o Stdcpp

		\o 0x2000F866

		\o 1.6.0

		\o 0.2 MB

		\o 0.2 MB

		\o Standard C++ library Common

	\row

		\o Openc_ssl

		\o 0x200110CB

		\o 1.6.0

		\o 0.8 MB

		\o 0.8 MB

		\o Open C LIBSSL Common

	\row

		\o PIPS

		\o 0x20013851

		\o 1.6.0

		\o 1.2 MB

		\o 1.4 MB

		\o PIPS Installer

	\row

		\o Sqlite

		\o 0x2002AF5F

		\o 0.5.0

		\o 0.2 MB

		\o 0.1 MB

		\o Sqlite library

	\row

		\o Qt

		\o 0x2001E61C

		\o 4.6.3

		\o 5.8 MB

		\o 5.9 MB

		\o Qt libraries

	\row

		\o QtWebKit

		\o 0x200267C2

		\o 4.6.3

		\o 2.9 MB

		\o 3.0 MB

		\o QtWebKit library

	\row

		\o QtMobility

		\o 0x2002AC89

		\o 1.0.0

		\o 1.0 MB

		\o 1.0 MB

		\o QtMobility library

	\row

		\o {3,1} \bold{Total for Qt excluding QtWebKit}

		\o 8.3 MB

		\o {2,1} 8.5 MB

	\row

		\o {3,1} \bold{Total for Qt including QtWebKit}

		\o 12.1 MB

		\o {2,1} 12.4 MB

\endtable

*/

/*!

\contentspage{index.html}

\page smartinstaller-app-installation.html

\title Installing Applications

When Nokia Smart Installer for Symbian is invoked from the Ovi Store, the

application is installed to the drive selected in the Ovi Store as the

installation target drive. It defaults to the drive with the largest amount of

available space. Usually, that is the internal flash drive (eMMC) or a memory

card. Users can change this behavior in the Ovi Store settings.

Otherwise, Smart Installer uses the developer chosen installation drive defined

in the wrapper package. For more information, see \l{Wrapper Package File}.

\section1 Resuming Interrupted Installation

Nokia Smart Installer for Symbian can resume cancelled or interrupted

installation. To resume interrupted installation, users choose the Smart

Installer icon from the application menu grid. Smart Installer icon is visible

only, when a pending installation is available.

\inlineimage smartinstaller-icon.png

Smart Installer icon

\note Only the latest interrupted installation can be resumed.

\section1 Integration with Qt Build Tools

The Qt build chain supports Nokia Smart Installer for Symbian from Qt 4.6.2 for

Symbian onwards.

\note It is recommended that Qt 4.6.3 or newer is used when creating the applications.

\section1 Incompatible Devices

There are known issues with Open C upgradeability on some devices. This makes

Nokia Smart Installer for Symbian unsuitable for deploying Qt or any other

package that require an Open C upgrade. If a user tries to install Qt

applications to these devices, the error note \e {Device not supported} is

shown, and the installation is cancelled.

The following table lists devices that are known to have problems and are not

supported by Smart Installer. For an up-to-date list, see

\l{http://wiki.forum.nokia.com/index.php/Nokia_Smart_Installer_for_Symbian#Suppo

rted_Devices}{Supported Devices}.

\table

	\header

		\o Device

		\o Incompatible Firmware Versions

		\o Description

	\row

		\o Nokia 6650 AT&T variant

		\o All

		\o PIPS cannot be upgraded

	\row

		\o Nokia N96

		\o All

		\o Not supported by Qt

\endtable

*/

/*!

\contentspage{index.html}

\page smartinstaller-messages.html

\title Messages

Informative messages appear if problems occurr during the installation.

The following table describes the messages and their causes.

\table

	\header

		\o Message

		\o Description

	\row

		\o Verifying components

		\o Smart Installer is checking to see which components the application requires

		   to be installed, and which components are on the device.

	\row

		\o Downloading X of Y

		\o Required dependency X is being downloaded out of the total number of Y. Time

		   required depends on network connection speed.

	\row

		\o Installing X of Y

		\o Required dependency X is being installed out of the total number of Y. Time

		   required depends on phone speed.

	\row

		\o Download XX MB?

		\o The prompt the user gets when Smart Installer has determined which components

		   to download. If user denies download, the installation is cancelled.

	\row

		\o Phone is roaming. Download XX MB anyway?

		\o User is warned that device is roaming, and additional data charges may apply.

		   User needs to confirm the download in order to continue the installation.

	\row

		\o No pending installations

		\o Smart Installer was opened from the \gui Application menu, but no pending

		   installations were found.

	\row

		\o Installation failed!

		\o Unrecoverable installation failure has occurred. Installation can be resumed

		   later by selecting the Smart Installer icon from the \gui Application menu.

	\row

		\o Installation cancelled!

		\o User has cancelled the installation. Installation can be resumed later.

	\row

		\o Device is not supported

		\o Device is known to have problems with Smart Installer and installation is not

		   allowed to continue. For more information, see \l{Incompatible Devices}.

	\row

		\o Download failed!

		\o Unrecoverable error has occurred during downloading. Check network

		   connectivity and coverage. Installation can be resumed later.

	\row

		\o Unsupported Smart Installer version

		\o Incompatible version of Smart Installer is in use. Software distributor must

		   update the package. Installation cannot continue.

	\row

		\o Cancelling installation

		\o Installation was cancelled or interrupted due to an error. Smart Installer is

		   removing any downloaded files. Installation can be resumed later.

	\row

		\o Not enough space to install

		\o Device does not have enough space to download and install the required

		   components.

		   Free space on the destination drive and resume the installation by

		   selecting the Smart Installer icon from the \gui Application menu.

		   Space requirements for drive C: are described in \l{Disk Space Requirements}.

\endtable

*/

/*!

\contentspage{index.html}

\page smartinstaller-packaging.html

\title Packaging

Nokia Smart Installer for Symbian is wrapped with the application .sis file to a

wrapper .sis package. This is needed in order to ensure successful installation

of the dependencies before the application is installed.

For and example of a wrapper package file, see \l{Wrapper Package File}. For

signing options for the wrapper package, see \l{Signing Wrapper Packages}. For

adding the dependency information to the application, see \l{Application

Dependencies}.

The qmake build tool automatically creates the necessary files to the source

directory. The make tool can be invoked to automatically create the Smart

Installer wrapped package. For examples of the command flows, see \l{Building a

Self-signed Smart Installer Package} and \l{Building a Symbian Signed Smart

Installer package}.

For more information about the UIDs to be used with Smart Installer, see

\l{Reserved UIDs for Smart Installer}.

*/

/*!

\contentspage{index.html}

\page smartinstaller-wrapper-format.html

\title Wrapper Package File

This section contains an example of a wrapper package file.

To deploy the wrapper package as a self-signed .sis file, you must obtain a free

UID from the appropriate UID range. The normal restrictions apply about which

UIDs are available for self-signed packages. Qmake uses a fixed UID (0xA000D7CE)

when creating a self-signed wrapper package.

Nokia has reserved a UID to be used with the wrapper package (0x2002CCCF) when

submitting the package to Symbian Signed (see \l{Signing Wrapper Packages} and

\l{Building a Symbian Signed Smart Installer Package}). The wrapper package is

used only temporarily to transmit the application with Nokia Smart Installer for

Symbian to the device, and it is deleted after installation. Therefore, a fixed

UID can be used for the wrapper package.

Standard rules apply to selecting the  target drive for the installation. If the

drive is “!”, the user is prompted to select the drive. Otherwise, the specified

target drive is used automatically without user interaction.

\code

; The package header

&EN

#{"Application Installer"}, (0x2002CCCF), 1, 0, 0, TYPE=SA

%{"Vendor-EN"}

:"Vendor"

;Supports S60 v3.1

[0x102032BE], 0, 0, 0, {"SymbianProductID"}

;Supports S60 v3.2

[0x102752AE], 0, 0, 0, {"SymbianProductID"}

;Supports S60 v5.0

[0x1028315F], 0, 0, 0, {"SymbianProductID"}

; The actual application.sis file (required)

"application.sis"-"!:\private\2002CCCE\import\application.sis"

; Embedded Smart Installer (required)

@"smartinstaller.sis",(0x2002CCCD)

\endcode

\note This file is created automatically by qmake, and it is overwritten each

time qmake is run.

\note It is recommended that you do not change the qmake-created package

file directly. If necessary, you can change the following values:

\list

    \o \c {&EN} to change the supported languages of the installer package.

    \o \c Application to change the name of the installer package.

    \o \c Vendor to change the vendor name.

    \o \c {application.sis} to change the name of the application file

	  i.e. the application to be installed.

\endlist

*/

/*!

\contentspage{index.html}

\page smartinstaller-wrapper-signing.html

\title Signing Wrapper Packages

The wrapper package can be self-signed. However, during the installation, a

standard warning note is displayed on the device stating that the source of

the package is not trusted.

In order to assign trust to the wrapper package, the wrapper can be put through

the Symbian Signed Express Signed service, which offers a low-cost self-

certification service. Unfortunately, standard signing fees apply to

developers wanting to sign the wrapper package, but work is being done to remedy

this situation.

\note Use the provided fixed UID (0x2002CCCF) when submitting a wrapper package to Symbian Signed.

\section1 Application Dependencies

Qmake automatically generates package files (*.pkg) with correct dependencies

for the version of Qt the application is built against. Developers can add

additional dependencies using the deployment keyword in the .pro file (see Qt

documentation for details).

\note Typically, all Qt for Symbian applications have their dependencies assigned

automatically by the build tools. Nokia Smart Installer for Symbian takes care of any

dependencies that Qt libraries might have during installation. There is no need

to specify any other dependencies unless your application is using the APIs

provided by the packages in question.

\note Currently Smart Installer can provide only the dependencies described in

\l{Disk Space Requirements}.

\section1 Building a Self-signed Smart Installer Package

This section explains how you can create a self-signed Nokia Smart Installer for

Symbian wrapped .sis file. It is assumed that you are already familiar with Qt

build tools and the build process.

\note Ovi Store does not accept self-signed packages.

In the list below, \c Application is the target application name defined in

the .pro file.

\list 1

\o To invoke the qmake tool for creating the required files needed for the build

process, enter the following command:

\code

C:\Sources\Application> qmake

\endcode

\o To build the application release version with the GCCE compiler, enter the

following command:

\code

C:\Sources\Application> make release-gcce

\endcode