How to upgrade OS components

The software installer allows the replacement of binaries and data files in ROM, for instance to allow a manufacturer to fix a software issue, by means of eclipsing, but it is strictly controlled.

Eclipsing occurs when some form of path-processing logic is being applied, and a file is installed with the same name and path as an existing file - but to a different drive. Under these circumstances, therefore, the new file is used instead of the original.

The OS loader exhibits this behaviour; when an EXE or DLL is loaded, drives are searched in the order Y: to A: followed by Z:. Therefore, a binary file installed to the C: drive, (or any other drive between A: and Y:) will eclipse one with the same name and path on Z: and will be loaded instead of the original X: file.

In order to eclipse data files in ROM, an application must explicitly support this behaviour, in other words, it should not assume that data files will be located on Z:.

Creating the stub SIS file

Files in ROM can only be eclipsed if the device manufacturer has added a stub SIS file, which claims ownership of these files, to the ROM. The stub SIS file must be located in Z:\system\install\ and its name is not particularly significant.

Without a relevant stub SIS file present, any attempt by the user to install a package that eclipses files in ROM will fail.

In the PKG file used to generate the stub SIS file, the source file entries are irrelevant (because no installable files are included in a stub SIS file), and are therefore specified as empty strings. For instance:

; Example STUB File
&EN
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."
#{"Hello World"},(0x18000091),1,0,0
"" - "z:\sys\bin\HelloWorld.exe"
"" - "z:\resource\apps\HelloWorld.rsc"
"" - "z:\resource\apps\HelloWorld.mbm"
"" - "z:\private\10003a3f\import\apps\HelloWorld_reg.rsc"

To generate the stub SIS file, use:

> makesis –s <PKG_filename>

The stub SIS file is not signed, but it must have a package UID from the protected range. In other words, it must be selected from the range allocated to the device manufacturer by Symbian Signed.

Creating the eclipsing package

The files in the eclipsing package must be installed to the same path, and have the same filename as the files in ROM that are being eclipsed (except of course the drive is different). For instance:

;Example eclipsing package
&EN
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."
#{"Hello World"},(0x18000091),1,1,0, TYPE=PU
"HelloWorld.exe"-"c:\sys\bin\HelloWorld.exe"
"HelloWorld.rsc"-"c:\resource\apps\HelloWorld.rsc"
"HelloWorld.mbm" - "c:\resource\apps\HelloWorld.mbm"
"HelloWorld_reg.rsc" - "c:\private\10003a3f\import\apps\HelloWorld_reg.rsc"

Hard coding the target drive letter as C: may be preferable to allowing the user to select it, because if the user chose to install the package to a removable drive, which was subsequently removed, the version on Z: would be in use again.

The upgrading package must have the same package UID as the stub SIS file. As this is always from the protected range, the eclipsing (and upgrading) package must have been signed by a signing authority.

The eclipsing package must either be of type PU (partial upgrade) or SP (patch). ROM files cannot be eclipsed using a standard full upgrade package, (TYPE=SA), because that would need to remove the original package in ROM.

The installer prevents a file from being eclipsed twice. For instance, if you install a file to C: that eclipses a ROM file, then an attempt to eclipse the file again, by installing to D:, will fail.

Eclipsing using a partial upgrade

An eclipsing package of type PU should have the same package name and global vendor name as the package it is eclipsing (because the changes made by a partial upgrade are considered to become a part of the original package). Such a package cannot be removed, although it is possible to install multiple partial upgrades with the same package name and UID, for example:

Eclipsing using a patch

Although a patch cannot overwrite files in a base package in RAM, it can eclipse files in ROM. An eclipsing package of type SP must have a different package name from the package it is eclipsing, because it subsequently can be removed separately from it. If two patches with the same package name and UID are installed, the second patch is treated as an upgrade of the first patch and will replace it entirely, for example:

An OS component can be augmented by the installation of a patch. A patch can subsequently be removed separately from the package it is augmenting.

It is possible to re-patch the package to fix any problems which the first patch may introduce. A patch can overwrite an existing patch, if both patches have the same package name.

An OS component does not necessarily need a stub SIS file in order to be patched. However, if the patch attempts to install any files to the component’s private directory, then a stub SIS file is required which specifies the relevant EXE. If the patch installs files to more than one private directory, all relevant EXEs must be specified in the stub file.

A patch (or any package) can install files to a component’s import directory (\private\<SID>\import\) without a stub SIS file present, (the purpose of the import directory is to enable other packages to install files to it). However, the import directory must already exist – the software installer will not create it.

If a stub SIS file is required, the patch must have the same package UID and non-localized vendor name as the package it is patching. The package name should be different in order to distinguish the patch from the existing component. The patch can have its own version number. The PKG file type for a patch is SP. For instance:

; Example patching package
&EN
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."
#{"Hello World patch"},(0x18000091),1,0,0, TYPE=SP
; installs a file to the private directory – a stub SIS is required.
; the private directory is the SID, which in this case is not the same as the package UID
"patch.dat" - "!:\private\e800005a\patch.dat"