--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/smartinstaller/doc/smartinstaller.qdoc Wed Jun 30 11:01:26 2010 +0530
@@ -0,0 +1,624 @@
+/*!
+
+\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
+
+\o To create the wrapper .sis file, enter the following command:
+
+\code
+C:\Sources\Application> make installer_sis
+\endcode
+
+\endlist
+
+Now the directory contains a self-signed application_installer.sis, which is the
+Smart Installer wrapped version of the application.sis.
+
+\section1 Building a Symbian Signed Smart Installer Package
+
+Building a Symbian Signed Smart Installer package requires passing information
+about the key to sign it to the tools.
+
+In the list below, \c Application is the target application name defined
+in the .pro file.
+
+\note Commands need to be entered on a single line.
+
+\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
+
+\o Create a .sis file and sign it with the appropriate keys. For Symbian
+Signed certification submission, use the keys for your Publisher ID.
+The example assumes that the Publisher ID key and certificate are in the current
+directory.
+
+\code
+C:\Sources\Application> make sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key
+\endcode
+
+
+\note Here, the publisher key and certificate are located in the current folder.
+If they are located in another folder, specify the path as well as the filename.
+
+\o Submit the created .sis file
+(application.sis) to Symbian Signed for certification. Depending on
+application specific needs and properties (that is, Platform Security capabilities
+used) you may use either the Express Signed or the Certified Signed path.
+
+\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.
+
+\o To create the signed wrapper package, enter the following command:
+
+\code
+C:\Sources\Application> make installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key
+\endcode
+
+\o Submit the created wrapped .sis file, application_installer.sis, to
+Symbian Signed. Express Signed is a suitable signing option for the wrapper
+package.
+
+\endlist
+
+\section1 Reserved UIDs for Smart Installer
+
+Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian:
+
+\table
+ \header
+ \o UID
+ \o Description
+ \row
+ \o 0x2002CCCD
+ \o Smart Installer UID. To be used in the wrapper package when including the smartinstaller.sis.
+ \row
+ \o 0x2002CCCF
+ \o Wrapper package UID when providing a package to Symbian Signed.
+ \row
+ \o 0xA000D7CE
+ \o Reserved UID when creating a self-signed wrapper package using Qt tools.
+\endtable
+
+*/