Symbian Installation System
The Symbian Installation System (SIS) provides a simple and consistent approach to installing applications, data or configuration information to Symbian OS-based devices. This system is not designed for software installation on an emulator. Developers and end users install components packaged in ( .sis ) files either from a PC, using the installer, or from a Series 60 device, using the Application Controller utility.
Using digital certificates, the Symbian OS software installation system allows users to identify the software vendor, prior to installing software, and hence verify that the installation file has not been tampered with since it was created. This functionality is particularly important within an environment in which there is easy access to a wide range of freely downloadable software ”software that might be infected with viruses. The Certificate Generator ( makekeys.exe ) can create a public/private-key pair. You may then choose to have the Installation File Generator ( makesis.exe ) create a digitally signed installation file. This process is described in detail in the SDK documents ”see the section on Tools and Utilities and refer to the Installation Guide and Installation Reference sections.
An installation file can incorporate other embedded installation files. This feature might be used for packaging files into logical components that are installed and removed as a complete set. For example, a shared library might be put in a separate installation file from the application files that use it.
A number of options may be offered to the user so that during installation the system will perform different actions depending on user selections. It is possible to install a different set of files, display text or to run custom programs, during the installation and/or removal of an application. The most common use of this facility is to display a license agreement during installation. Users may be prompted about installation options such as where to install the components, to accept a security certificates that verifies the creator or to choose a particular language.
After the installation process completes, a small "stub" .sis file remains on the device to control the uninstallation of the application if required.
Example installation project files are provided with the examples in this chapter, and with the majority of projects associated with this book, to allow the example applications to be installed on a Series 60 device.
SIS File Build Tools
Two tools are provided with the Series 60 SDK to enable developers to build installation files.
-
The Installation File Generator ( makesis.exe ) creates the installation ( .sis ) files from a specification provided in a package source ( .pkg ) file. A .pkg file is a text file containing installation information for applications or files. This is the option used in all of the example GUI applications described in this chapter.
-
Alternatively, you can produce .sis files using the sisar tool provided with the Series 60 SDK. Sisar packages all the application files into one .sis file for ease of installation onto target hardware. It stores the installation project details in a file with a .sisar filename extension. Manually created .pkg text files can be imported into the sisar utility, but they cannot be exported again. In addition, sisar can import .aifb files generated by the aifbuilder tool described earlier.
 | Sisar is a convenient and easy-to-use tool for creating simple .sis files. However, using a .pkg source file with the makesis.exe utility is, at the time of writing, more flexible. Most importantly, the makesis method permits the use of the Series 60 Platform UID code (explained later in this chapter), and sisar currently does not. Makesis also allows for fine-tuning of the installation options and process. |
Another SDK tool, the Certificate Generator ( makekeys.exe ), can create private/public-key pairs, which you may optionally use, via the Installation File Generator ( makesis.exe ), to digitally sign installation files. During installation the users will be warned that they are about to install an unsigned application.
Both makesis and makekeys can be run from the command line or may be invoked from within sisar. Sisar itself can also be invoked from the command line to build a .sis file.
Text source ( .pkg ) files specify the executable code files and other resources needed to install an application onto a device. It is usual to create the required .pkg files by hand with a text editor or within an IDE, and then build the .sis file using the makesis tool.
Using the sisar tool is basically self-explanatory, but has its own internal help mechanism and is separately documented in the Series 60 SDK. Note that sisar depends on a Java99 2 Runtime, which is available from http://java.sun.com.
Format of .pkg Files
There is another version of the HelloWorld example project, called HelloWorldLoc , which is a localized alternative to show how you can supply an application installation package suitable for several different locales. During installation, appropriate language versions of the resource file, caption file and even the application information file will be used. Hence all the text of the application, the name of the application and even the icons can be tailored to the needs of each supported locale. This subsection looks at the syntax of the nonlocalized .pkg file and then points out the essential differences in the localized version.
[View full width]; Languages - Only English so the next line is optional &EN ; Name/caption needed for each language, caption file used if supplied ; Name, the app UID, version, minor version, build & package type #{"HelloWorld"},(0x101F6148),1,0,0,TYPE=SISAPP ; Platform UID code required for recognition by a compatible ; device at installation time (0x101F6F88),0,0,0, {"Series60ProductID"} ; Four files to install "\Epoc32\release\armi\urel\HelloWorld.aif" -"!:\system\apps\HelloWorld\HelloWorld.aif" "\Epoc32\release\armi\urel\HelloWorld.r01" -"!:\system\apps\HelloWorld\HelloWorld.rsc" "\Epoc32\release\armi\urel\HelloWorld_caption.r01" -"!:\system\apps\HelloWorld\HelloWorld_caption.rsc" "\Epoc32\release\armi\urel\HelloWorld.app" -"!:\system\apps\HelloWorld\HelloWorld.app" ; End of File
The HelloWorld example is in English only. If you wish to support other languages, you must specify each one at the top of the file, and then the syntax of the rest of the file must provide options for each language/locale ”this is illustrated later using the HelloWorldLoc example.
; Languages - Only English so the next line is optional &EN
The package header contains the component name (application name in this case), the UID of the application or component, the major and minor version numbers , the build number and the package options ( SISAPP ) ”whether this is an application installation, upgrade, patch, system option and so on.
#{"HelloWorld"},(0x101F6148),1,0,0,TYPE=SISAPP | | Note that . exe applications do not require a value for the application UID ( UID3 ) in their .mmp and .pkg files ”for a test or experimental .exe , the application UID is typically set to zero. However, if you are going to release an .exe (say as a server) then you will need to give it a UID so that it is truly unique. If the same application UID ( ) is specified in two different .pkg files, then a previously installed .exe will be removed when installing a new one. |
Note that within the package file, it is a requirement that a Series 60 Platform identification code be included as follows .
(0x101F6F88),0,0,0, {"Series60ProductID"} The platform identification code ( Platform UID ) enables a built-in system mechanism to issue a warning if a user attempts to install incompatible software onto a Series 60 device. The Platform UID is a 32-bit number assigned to identify a specific version of Series 60 or a particular device ”it has no relationship to the three UIDs associated with executables or application documents.
All installation packages of Series 60 applications should carry the sequence in order to facilitate smooth installation of software. If the Platform UID sequence is not found, or if the UID refers to a platform release newer than in the terminal, the user will get a notification about the potential conflict. Depending upon the product, the installation process may be automatically aborted. If it is allowed to continue, there is obviously a risk of application functionality failure.
The identifier for applications that are based on Series 60 Platform first release (0.9) is 0x101F6F88 (for example, early Nokia 7650 devices were based upon this first release of Series 60). Application installation packages specifying this value are compatible with Series 60 Platform 0.9 and potentially with later releases of Series 60 Platform.
A new Series 60 Platform UID was introduced for Series 60 2.0, namely 0x101f7960 . You should use this Platform UID in applications that rely on Series 60 2.0 features and APIs. Earlier version Platform UIDs are still supported and they must be used in applications intended to run on Series 60 Platform version 0.9, 1.x, 2.x and so on.
Multiple Series 60 Platform UIDs can be defined in a .pkg file to signify all platforms and devices that an application is able to run on.
 | See the Advanced Application Deployment and Build Guide section later in this chapter for a more complete list of Platform UIDs. |
Finally, each of the application components to be installed is listed ”in this case: HelloWorld.aif , HelloWorld.r01 , HelloWorld_caption.rsc and HelloWorld.app . Note that the format of each line is the source filename followed by the location and name of the destination file.
Also note that the file locations of the application components (resulting from the build process) on the development PC will vary depending on the version of Series 60 Platform you are working with.
Version 1.x of the SDK places the .app and all of the other files in the relative location: \Epoc32\release\armi\urel.
A version 2.x SDK build (and all CodeWarrior builds) will only put the .app file in that location; any other files ( .r01 , .aif , .mbm ) are placed in the relative location: \Epoc32\data\z\system\apps\ appname \ .
Using the AnsPhone example project as an illustration, the version 1.x .pkg file would be:
"\epoc32\release\armi\urel\AnsPhone.aif" - "!:\system\apps\AnsPhone\AnsPhone.aif" "\epoc32\release\armi\urel\AnsPhone.app" - "!:\system\apps\AnsPhone\AnsPhone.app" "\epoc32\release\armi\urel\AnsPhone.r01" - "!:\system\apps\AnsPhone\AnsPhone.rsc" "\epoc32\release\armi\urel\AnsPhone.mbm" - "!:\system\apps\AnsPhone\AnsPhone.mbm"
An equivalent version 2.x (or CodeWarrior) .pkg file would contain:
"\epoc32\data\z\system\apps\AnsPhone\AnsPhone.aif" - "!:\system\apps\AnsPhone\AnsPhone.aif" "\epoc32\release\armi\urel\AnsPhone.app" - "!:\system\apps\AnsPhone\AnsPhone.app" "\epoc32\data\z\system\apps\AnsPhone\AnsPhone.r01" - "!:\system\apps\AnsPhone\AnsPhone.rsc" "\epoc32\data\z\system\apps\AnsPhone\AnsPhone.mbm" - "!:\system\apps\AnsPhone\AnsPhone.mbm"
Note that the Platform UID will need to be changed between versions 1.x and 2.x of the .pkg file.
Also note that the filename extensions of the source file and the destination file in the .pkg script are not always the same. The reason is that there may be a choice of alternative source files, and this is illustrated in the HelloWorldLoc localized example later in this section.
To give the user the choice of installing the application on any drive on the device (for example, on a removable memory card instead of flash memory), the drive letter is specified by a " ! " character, as illustrated in the example given here. During installation the user will be prompted with a list of alternative drives for storing the application.
| | To ensure that the application always appears with the correct icon, arrange the order of the files as shown in the example provided ” specifically , place the name of the .aif file before the .app file. |
Running Executables During Installation
To have the HelloWorld GUI application run during the installation process an additional parameter is required immediately following the application filename as follows:
"\Epoc32\release\armi\urel\HelloWorld.app" -"!:\system\apps\HelloWorld\HelloWorld.app", FR
Or in the case of the HelloWorldCon console application:
"\Epoc32\release\thumb\urel\HelloWorldCon.exe" "c:\EMCC\Exes\HelloWorldCon.exe", FR
Make sure that all of the other application component files are installed before the application in the .pkg file.
The " FR " parameter means "File Run". During the installation process, do not be fooled into thinking that the application has shut down again ”the application is left running; it is simply that the installation process starts the application up, then tasks back to itself to complete the rest of the installation process. Example "file run" installation package ( .pkg ) files are provided for each of the example projects. They are located in the \install folder, under the main project folder, with the filename ending in FR ”for example, HelloWorldConFR.pkg .
Multi-Locale Installation
The HelloWorldLoc version of the example application supports three alternative locales: English, French and German. You will find the project located under: \EMCCSoft\HelloWorldLoc\ ”relative to the root level of the Series 60 SDK.
Here are sections from the HelloWorldLoc.pkg file that are relevant to the localization of the application installation:
; Languages - English, French and German &EN,FR,GE
Note here how the supported languages are specified ”as EN , FR and GE , unlike the method used in the LANG statement in the project .MMP file ”as 01 , 02 and 03 . It seems that this discrepancy in identifying the supported languages is simply due to a historical oddity. The other language codes for .pkg files are documented in the SDK documentation under "Package file format".
The package header must contain the component name in each of the supported languages:
; Name/caption for each language, caption file is used if supplied #{"HelloWorldLoc","BonjourMondeLoc","HalloWeltLoc"},(0x101F6149),1,0,0,TYPE=SISAPP The package ( .pkg ) file syntax forces you to duplicate the Series60ProductID string for each language:
(0x101F6F88), 0, 0, 0, {"Series60ProductID","Series60ProductID","Series60ProductID"} Next, a list of three locale-specific .aif files is supplied, of which only one will be installed:
{ "\Epoc32\release\armi\urel\HelloWorldLoc.a01" "\Epoc32\release\armi\urel\HelloWorldLoc.a02" "\Epoc32\release\armi\urel\HelloWorldLoc.a03" }-"!:\system\apps\HelloWorldLoc\HelloWorldLoc.aif" Now the name of the application to be installed is specified. Other application components can each have their own line, or components can be installed using embedded installation ( .sis ) files. See Multicomponent Installation later for more details.
[View full width]"\Epoc32\release\armi\urel\HelloWorldLoc.app" -"!:\system\apps\HelloWorldLoc
Next, a list of three locale-specific resource files are supplied, of which only one will be installed:
{ "\Epoc32\release\armi\urel\HelloWorldLoc.r01" "\Epoc32\release\armi\urel\HelloWorldLoc.r02" "\Epoc32\release\armi\urel\HelloWorldLoc.r03" }-"!:\system\apps\HelloWorldLoc\HelloWorldLoc.rsc" Finally, a list of three locale-specific caption resource files are supplied, of which, again, only one will be installed:
{ "\Epoc32\release\armi\urel\HelloWorldLoc_caption.r01" "\Epoc32\release\armi\urel\HelloWorldLoc_caption.r02" "\Epoc32\release\armi\urel\HelloWorldLoc_caption.r03" }-"!:\system\apps\HelloWorldLoc\HelloWorldLoc_caption.rsc" ; End of File Multicomponent Installation
Sometimes it is better to handle the installation of components needed by an application using embedded installation ( .sis ) files. This is easily achieved as follows:
; Embedded SIS file for components e.g. DLLs @"..\..\Engine\group\Engine.sis", (0x101F6150) @"..\..\Controls\group\Emccctrls.sis", (0x101F6151)
Note that each line that specifies the name of an embedded .sis file begins with an @ symbol. The path and filename for the .sis file is provided ”relative to the current application location ”inside quotation marks. Following the filename and path, is the UID3 for the application or component that is to be included as part of this main installation package.
Each component will either be a separate project or will form part of the main project, and each will require a .pkg (or .sisar ) file of its own to generate the corresponding embedded .sis file. If one or more embedded .sis files are specified, to be included as part of the installation of the application, the components will be removed when the application or component within which they were embedded is removed (provided no other component has a dependency upon them).
Conditional Component Installation
Occasionally it may be necessary to decide during the installation process itself which components are needed or are appropriate. Conditional statements can be incorporated into an installation script file and how to do this is illustrated later in the chapter ”see the subsection titled Device Identification at Install Time under the Advanced Application Deployment and Build Guide section.
Building a SIS File
To build the HelloWorld.sis file, open a command prompt, navigate to the folder for the HelloWorld project and build the project as follows:
bldmake bldfiles abld build armi urel
Then change to the \install folder. To build the .sis file enter:
makesis helloworld.pkg
Or to build the auto-running version:
makesis helloworldfr.pkg
Note that the Borland C++BuilderX IDE can generate the .sis file during the build process if a suitable .pkg file is included in the project. Select the ProjectProperties menu item, then select the Symbian settings tab. Set the platform to a suitable target device and the build to urel , and the .sis file will be generated when the project is built.
To run the application on a target device, transfer the .sis file to the device using an infrared or Bluetooth connection.
EAN: 2147483647
Pages: 139